Re: [boost] Reference documentation: one approach

From: David Abrahams (dave_at_[hidden])
Date: 2002-10-29 10:04:58

Douglas Gregor <gregod_at_[hidden]> writes:

> 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.

I very much dislike the idea of having the /source/ of our docs be in
any kind of <tag>...</tag> representation. I would like to explore a
more-readable (and typable) alternative: ReStructuredText.

   http://docutils.sourceforge.net/docs/rst/quickref.html

-- 
                    David Abrahams
dave_at_[hidden] * http://www.boost-consulting.com