About our comment system
February 10th, 2008 by Bryan O'Sullivan
A few people have asked for details about the comment system we’re using for the book. I picked up the idea from the drafts of the Django Book and version 3 of the GNU General Public License, both of which were being developed at the time I was thinking about writing a Haskell book and finding collaborators. I believe that Adrian and Jacob thought about enabling comments on individual paragraphs based on the system Jack Slocum put together for his blog.
To the best of my knowledge, the FSF never released the software they developed for managing comments on drafts of their licenses, so that wasn’t an option. When I talked to Adrian and Jacob about possibly reusing their comment software, they demurred, claiming that their code was put together in too much of a rush to be of much use to other people.
Since I was intensely interested in making it easy for people to comment on individual paragraphs based on the experience of the Django and GPL authors, this put me in the position of developing something myself. It wasn’t hard to come up with a few obvious pieces of software that would speed up the development of the comment system.
We’re developing the book using DocBook. I wrote a few small Haskell programs to pluck code snippets out of normal Haskell source files, so that we can refer to preformatted entities instead of having to paste code into the book. We do the same thing with sessions of interaction with ghci, the GHC interpreter. This follows a practice I used when I wrote the Mercurial book, and it’s proved very useful in both instances.
I use xsltproc and a few custom stylesheets to control the generation of HTML, styled afterwards with out-of-line CSS. The browser side of the comment system is a mere 91 lines of Javascript, using the wonderful jQuery toolkit. When I was developing the Javascript code, I made extensive use of Firebug and YSlow, both of which are excellent pieces of software.
On the back end, I wrote a small comment management system using Django, backed by a MySQL database. Django has been a mixed blessing, and I might not rush into using it so quickly again.
In spite of a few rough patches early on (comments being associated with the wrong paragraphs, performance problems), I think the comment system has worked out very well so far. If you’re a writer and have a DocBook project that you’d like to use the system with, let me know and I’ll try to find some time to release it under a free license.
Thanks for your inquiries, and keep the thoughtful and encouraging comments coming!
First, I’m really looking forward to the full release of the book – it’s exciting.
Second, I’m curious – care to elaborate on why Django was a “mixed blessing”?
It’s great to see the continuing stream of comments from the community via the Atom feed. This, if nothing else, is a testament that the system you developed works. I’d been dissatisfied with the lack of a view showing all comments, but finally found the “load all comments” button under the Table of Contents. Now I’m happy too.
Overall, I think the comment system is great, if a little slow at times.
The only complaint I have is that the “see this comment in context” link in the RSS feed seems to be broken. It always just takes me to the top of the relevant chapter, with no comment nodes expanded. I would *love* to see this fixed, as there are times when I’d really like to see what a comment is responding to, but I just can’t take the time to hunt for it. So I still skim the RSS feed, but it’s not as useful as it seems like it ought to be.
Anyway great job on the system, it works really well!
It would to develop an application like this using HaPPS, going through the development in the book. That would result in a powerful piece of software and also one that shows how to use a lot of advanced parts of Haskell.
That was supposed to say “it would be awesome to…”
Interesting. Are comments valid after you modified, and rearraged paragraphs?
And take a look http://www.paragraphr.com. Paragraphr is very early-state application but supports comments per paragraphs.
Would it be possible to provide the source code of this awesome book writing+comment system application ?
Did you ever manage to release this code? If not, would love to see it!
BTW, instead of using MySQL for comment storage, how about something more lightweight?
Just one quick comment regarding something not correct in original post. In fact, the software that ran the GPLv3 process, called stet was in fact Released on 21 November 2007. However, it was written before things like jQuery existed, so it is of historical interest only, I think.