Re: [boost] Reference documentation: one approach

From: Douglas Gregor (gregod_at_[hidden])
Date: 2002-10-29 15:31:03

On Tuesday 29 October 2002 10:43 am, Peter Simons wrote:
> Douglas Gregor writes:
>  > With DocBook alone we can't express our reference documentation by
>  > the C++ code structure and end up with a useful document.
>
> DocBook provides tags to express classes, interfaces, member
> functions ... Pretty much anything, actually. Here's an example from
> my RFC822 parser documentation:
[snip]

In your opinion, do you think it's enough to handle what we need in Boost? My 
FUD-ridden opinion is that the tag set for expressing classes, member 
functions, etc. is too Java-centric to be applicable to generic C++ code.

> I had much fun learning this kind of stuff, until I finally realized
> that this is a waste of time and just placed my class declarations
> into <literallayout> or <programlisting> tags. :-)

That's precisely what we _don't_ want to do, because it tosses inter-library 
consistency right out the window :)

> Also, DocBook is extensible; if you find that tags are missing, just
> define them. Or report them to the guys at docbook.org: They are very
> cooperative and certainly value input from their users. This would
> also be beneficial to many more people than just "Boosters'.

I wouldn't expect the guys at docbook.org to understand what we need for Boost 
documentation, so we're probably (mostly) on our own if we want to extend 
DocBook for Boost.

        Doug