Re: [boost] Reference documentation: one approach

From: Douglas Gregor (gregod_at_[hidden])
Date: 2002-10-29 10:09:42

On Tuesday 29 October 2002 08:10 am, William E. Kempf wrote:
> Can you compare and contrast this to DocBook?  I expect your XML is a lot
> simpler than the DocBook DTD, but since DocBook is an industry standard
> for this sort of thing it would be nice to know what we'd be giving up for
> the simplicity.

I looked at DocBook a bit, but I'm no expert in it. With DocBook alone we 
can't express our reference documentation by the C++ code structure and end 
up with a useful document. However, with just the XML/XSLT as it stands now, 
we're missing the big picture: chapter organization, footnotes, references, 
etc. 

The answer is probably to use both. The overall document structure comes from 
DocBook, but the nitty-gritty C++ reference details are specified with some 
simple C++ declaration/documentation DTD and transformed into DocBook.

I'll look into this. We'd also be wise to watch what the Spirit folks are 
doing, because they are also experimenting with DocBook for documentation.

        Doug