Re: [docbook] Markup for revisions / comments

[Thomas Schraitle <tom_schr@web.de>]

Hi Jose,

On Wednesday 22 February 2006 15:56, Jose Gonzalez Gomez wrote:
>
> Is there any kind of markup for specifying a comment during the
> revision of a document, keeping track of the author? I'm thinking about
> a docbook document that is sent for review, and reviewers write their
> comments, even answering to each other. Is this possible to do with
> docbook? I know about remark, but don't know if this may be used in
> combination with some other tag.

I don't think there is a special element for this purpose. However you can 
use this:


* Use revhistory[1]
This element can be used from a more "global" view.  However you can use 
it in hierachical elements only like section, chapter and such. So it is 
limited if you need to comment a para only. Of course you can xref to it, 
but it might be difficult if your sections or chapters are very long.
  It may be not the best option to hold this sort of comments, but it 
depends on your structure of your document and if you or your reviewers 
"like" this sort of markup.


* Use remark in combination with phrase
This element can be used for a more "local" view. You can (ab)use it with 
phrase to hold an author with his comment (if you need this granularity):

 <para>Bla bla bla <remark><phrase>tux: Use XYZ</phrase>
     <phrase>wilber: is this correct?</phrase></remark> ... </para>

However if you work with different authors it needs probably some sort of 
discipline to enforce this structure. Unfortunatly this markup can be 
very hard to read if a para is interspersed with remarks and lots of 
comments. Probably it's better to move remarks in front of the respective 
para.


* XML Comments
Why not use them? :)


Hope that helps,
Tom

---------
[1] http://www.docbook.org/tdg/en/html/revhistory.html

-- 
Thomas Schraitle