This is the mail archive of the
docbook-apps@lists.oasis-open.org
mailing list .
[docbook-apps] Ideas needed: Annotation mechanism for DocBook
- From: Joachim Ziegler <ziegler at mpi-sb dot mpg dot de>
- To: docbook-apps at lists dot oasis-open dot org
- Date: Wed, 07 May 2003 10:44:56 +0200
- Subject: [docbook-apps] Ideas needed: Annotation mechanism for DocBook
- Organization: Max-Planck-Institut für Informatik
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