[docbook-apps] Ideas needed: Annotation mechanism for DocBook

[Joachim Ziegler <ziegler at mpi-sb dot mpg dot de>]

Hello,

I have the opportunity to let one of our students build an "annotation 
mechanism" for DocBook. We need such a mechanism for one of our documents.

(What I mean by that is something like "The Book of Zope" which can be 
read *and* commented online at
http://www.zope.org/Documentation/Books/ZopeBook/current/index_html
Every reader can insert comments (and/or questions) after every 
paragraph. This is very useful for both readers and authors.

The Manual of PHP
http://www.php.net/manual/en/
has a comparable mechanism; it calls it "user contributed notes")

I'm currently collecting ideas for such a project and would like to ask 
you what you expect from such a mechanism and how it could be done 
technically.

Of course, the final version will be in public domain.

Here are my first thoughts:

- At least the <para>s should be commentable.

- To achieve this, the HTML stylesheets must be changed such that after 
processing a <para> an HTML link is created which refers to a CGI 
script. This script when called collects the user's notes and inserts it
back into the original HTML document. In order to find the place where 
the notes are to be inserted, the template for <para> must also place an 
anchor into the HTML document. The actual anchor must be a unique string 
like e.g. the sequence number of the <para> in the document. (I don't 
know if and how this works with chunked documents; I have not studied 
the stylesheets yet.)

- Other candidates for commentable elements are all the block elements.

- One should be able to specify exactly what can and what cannot be 
annotated.

- Maybe an attribute could indicate whether an element is annotatable.

- A different approach is to let the HTML file unchanged after creation 
and to store all user notes in an external file (or database). Then the 
HTML document must be delivered by a CGI script which inserts the notes 
on the fly.

We'd be glad to get some feedback from you.

The longer I work with DocBook the more I like it. I think such an 
annotation mechanism would make it even more attractive for authors in 
our world of technical writing.

Joachim

--
Joachim Ziegler                       Stuhlsatzenhausweg 85
Max-Planck-Institut für Informatik    66123 Saarbrücken
Email: ziegler@mpi-sb.mpg.de          Germany


---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org