OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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


just a quick thought: If you generate an unique id for every paragraph in
the DocBook source, you could do the following:

1) Change the generated HTML on the webserver (insert the comment after the
respective paragraph) - for the sake of performance.
2) Save the comment with the id in an external storage (file, database).
3) Before processing the DocBook XSL transformation next time (e.g.
nightly), move the comment from the external storage into a <remark> node
within the respective paragraph in the source.
4) Later on, the author(s) can deal with the <remark> nodes.

BTW: Remarks can appear almost everywhere in a DocBook document and can
contain fairly verbose markup (e.g. you could add the name and emailadress
of the contributor - (see http://www.docbook.org/tdg/en/html/remark.html)

Kind regards
Gisbert Amm

> -----Original Message-----
> From: Joachim Ziegler [mailto:ziegler@mpi-sb.mpg.de]
> Sent: Wednesday, May 07, 2003 10:45 AM
> To: docbook-apps@lists.oasis-open.org
> Subject: [docbook-apps] Ideas needed: Annotation mechanism for DocBook
> 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

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]