Re: [boost] Reference documentation: one approach

From: William E. Kempf (wekempf_at_[hidden])
Date: 2002-10-29 10:31:26

Douglas Gregor said:
> 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.

You can't?  I'm not a DocBook expert, as pointed out in another posting. 
But I thought the DocBook structure was specifically open ended enough to
allow for complex structures similar to what we need?

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

Sounds like a reasonable approach.  My concern is still the complexity,
however.  Developers make lousy enough documentors as it is.  Make it more
difficult for them to write the documenation and I bet you'll see the
quality go down even more.  Not to mention you may very well scare away
some potential Boost submissions if we require them to use this stuff,
even if it stems solely from FUD and not fact.

> 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'm very interested in this, regardless.  So maybe some of us should
collaborate on our research and findings?

-- 
William E. Kempf