This is a post with ideas I’ve considered over time regarding a comment system for the stacks project. The most important thing is that I don’t know what will work. I think initially we want something where it is relatively easy to leave comments, where comments can be tracked (maybe by an rss feed), and where it isn’t too hard to work the comments back into the stacks project.
Structure that exists now:
- lots of tex files coded in a neurotic way so it is (relatively) easy to parse them
- the tags system (Cathy came up with this) which tracks mathematical results as they move around the tex files
- a query page for tags where looking up a tag 0123 returns the results page
- the results page contains links to the mathematical result in the corresponding pdf and moreover (a more recent feature) the latex code of the environment.
Cathy made some suggestions for what a comment system could look like: Besides the “results page” for each tag have a “comments page” where
- the address of the comments page is something like
http://commentson0123for direct access, - on the query page you can choose to end up on the comments page or the results page for the tag,
- links between comments page and results page,
- Cathy’s ideas about the comments page are:
- at the top of the page a link to the result in one of the pdfs
- have the statement of the lemma/proposition/theorem/remark/exercise there
- under this a small strip where if you click it expands to show you the proof
- under this comments by visitors
- to the right of the statement a small column with two lists:
- the results that rely on this tag and
- the results that are used in the proof of this tag.
I have the following thoughts on this:
- Go for functionality over looks,
- statements of theorems, etc are updated over time and the comments page should always have the current version.
- It may seem that we don’t really need both the results page and the comments page. But I think we do. I want the web addresses of the “results pages” to remain the same forever. These addresses are supposed to be used if you want to give a direct url to a result in the stacks project, and they should not be used for more than a link to the result in the pdf and the statement. I think that in the future all of the stacks project will be directly online (i.e., not in pdf form anymore) and then the “results page” may become a redirect (?) to the result in the project — so we will need another page with the comments.
- I would like there to be a way for the maintainer of the project to check (or be notified) if there is a comment.
- I want there to be a very low threshold for leaving comments, so have minimal protection to comment spam
- Math rendering issues: This is a real problem and I don’t think it has been solved by mathjax. But eventually some software package will take care of this. We can in any case generate png from latex code and put that up on the “comments page”.
Different ideas I have toyed and experimented with in the past
- Have a bug tracking system. What is good about this is that there is standard system that works. My feeling is that it won’t work because the average mathematician has never used or even looked at a bug tracking system.
- Sign off system: Try to get people like Brian Conrad to sign off on tags: “I, Brian Conrad, declare this theorem is correct”. Again I think that this won’t work, yet, but I think it would be a really cool thing to have in the future.
- Layers: Have different “layers” of comments, some historical, some references, some sign-off, some bug, etc. This could probably be managed simply by having different types of comments.
- Mailing list. I actually think this isn’t needed until I convince more people to be active on the stacks project
- Use blogging software with one page for each tag. I actually kind of like this idea, but I do not see how to make it work.
- Use wiki software with one page for each tag. I think this could actually work and be easier to implement then Cathy’s above suggestion provided somebody knows how to set-up wikis. My preference would be a wiki which is file based, or a wiki which uses git to keep track of files, etc.
- Online latex editor for the stacks project
Common feature of all of these ideas: Use already existing, open source, software and just write scripts to interface the stacks project with this. One of my problems with this is that most of the wiki and blog software I looked at will not allow automatic page generation/updating as far as I could tell.
If you have any ideas about this, please leave a comment or email me.
These seem like good ideas, and it constitutes a nice attempt to advance online math collaboration.
Some remarks / questions on the comments system:
* Do you envision this as a “static” thing (comments etc going into the Git repository, which might clutter the logs) or do you want to take a dynamic approach (standalone website interfacing with the Git repository)?
* Related to the above: what kind of infrastructure is possible and / or wanted?
* Would like actual user management (accompanied by a low threshold option for occasional commenters)?
* The Wiki approach seems reasonable (for instance http://en.wikipedia.org/wiki/DokuWiki has interesting properties, given the current approach using Git and your preference for file based systems), but this requires guidelines to ensure its consistency etc., another approach (entirely home-brew or hybrid) might be better suited for the specifics of the proposed system.
As per math rendering, it won’t get any better than MathJax for the moment I’m afraid. What are your objections? My main concern would be initial slowness, but aside from that I can’t come up with anything important.
“static” thing. Hmm, not completely sure what you mean. I think I would like it to be independent of the stacks project in the way that the bug system for a software development project is independent of the actual project. We can use what people write in comments to update the stacks project itself and when we do we can either literally copy their comment to the latex source files, or use their comment in the commit message of the git commit.
Infrastructure: Again I am not sure. Can you elaborate?
User management: We do need to be able to track users who leave multiple comments over time. Two reasons: (1) so we can give credit where credit is due, and (2) to boot out malfeasants.
Yes, I’ve myself tried dokuwiki and it seems pretty close to useable. For example, it is trivial to write a python script that creates a wiki-page for each tag (because dokuwiki is file backed). But as you say there are lots of issues.
Math rendering: I dislike how slow mathjax renders. I also don’t like the way it looks. Perhaps we could include use a hybrid approach where comments are rendered using mathjax, but each comment page has a png with the statement of the mathematical result. An advantage of that is that the commenters cannot edit the statement directly….
Static means an approach like the file-based wiki with the data files being *in* the Git repository. Not completely unreasonable, and a possible deduction of the givens, but as you already like it to be independent of th Stacks project not really the way to go.
By infrastructure I mean: what are the options programming- and server-wise? Is there a possibility of SQL, PHP, Ruby on Rails, …? I assume these are pretty much covered though given the fact that there is a weblog running on the server. But if there are any unavoidable restrictions it might be reasonable to know beforehand.
User management is of course a good idea, but it would be the biggest hurdle if you wish to go for the home-brew approach. I suppose DokuWiki has decent user management, so that would be a point in favor of the wiki way.
I don’t understand the remark about commenters not editing the statement of a tag. Even if you’d go for the wiki approach where the tag’s wiki page contains all information, including the statement of the tag, editing the statement wouldn’t change the actual content of the tag in the Stacks project (unless you implement this by hand for some reason).
“Static”. OK, that actually sounds fine, as we can have a separate git repository for the comments. Right? I do like the idea to have the content somehow managed by git…
“Infrastructure”. OK, I can ask my administrator to install anything we need (certainly, right now we have mysql, php, python, perl, etc available). But I think we need to be careful. I would like the comments system itself to be (a) easy to install on any server, (b) uses only software whose license is open (copyleft) and which we can expect to be around for quite a while, (c) it should be easy to get the content out of it.
User management. If we write something ourselves, then we could have some very low-level system where we have users identify themselves by leaving their name with their comment. (So each comment is entered in a web-form with a simple text-input box for the comment and a box labeled: your name.) In stead of a captcha we can have (for example) the user type the tag she/he is commenting on in another input box. I do not expect to generate high traffic with this thing, so this may be entirely adequate. Then you simply have comments stored in a flat file (one for each tag) and you include that on the corresponding comments page. Presumably we can create an rss feed for all the comments, so whoever is maintaining the project can be notified of new comments. And the users themselves can track comments (this is key as we want the stacks project to be a ‘live’ thing).
“Not editing tag”. Of course you are right. My concern is really this: At first there is just going to be a collection of “comments pages”, one for each tag, with the corresponding latex code somehow rendered on that page. Over time some of the latex code gets updated in the stacks project. Then we simply update the “comments page” as well, and this process should be automated. But what if a user has edited the latex code _on_ the comments page? Then how do we update that? Maybe there is a way in a setting such as dokuwiki to have parts of the page locked? Of course, if we make a home-brew system this problem doesn’t appear.
Using both a wiki approach and git might be a bit redundant (wiki and git both provide their own implementation of versioning), it was only a possible deduction given some of the initial ideas. I certainly don’t feel like advocating it.
The proposed user management system isn’t really a user management system, without actual registration / identification this non-system will be simple to set up. The proposed CAPTCHA is a very appropriate idea too. The idea of signing tags off would have to be independent (but that’s probably a good thing).
The actual comments page should be dynamically generated: the content of the tags is available as plaintext in a Git repository anyway, and the comments could be managed as plaintext or in a simple database. No need for a wiki if you opt for a comment form, it would look very much like a blog post that way.
The editing of LaTeX code on a comments page is only possible if we integrate the code on the wiki page, the comment form approach wouldn’t make such a thing possible.
Conclusion: the comment form approach seems both implementation-wise and usage-wise the easiest:
* everything is under your control, no need to impose any rules on the wiki etc.
* allowing Markdown syntax or an HTML subset seems appropriate, and is easy to implement
* an RSS feed is possible too
Downsides:
* no editing or user registration a priori possible (but can be implemented)
* everything is under your control: no spontaneous ideas that sometimes sprout in wikis