Re: [boost] Reference documentation: one approach

From: Peter Simons (simons_at_[hidden])
Date: 2002-10-29 16:46:41

Douglas Gregor writes:

 > In your opinion, do you think it's enough to handle what we need in
 > Boost?

In the current state, DocBook does definitely not suffice to express
complex C++ code. If you want to express every little detail, that is.
I don't think that this is necessary, though, not even useful, because
the results are almost completely unreadable if you're editing the
SGML document directly. One could try to solve this by generating the
DocBook "code" from the actual C++ code, but this would be a major
undertaking.

You can extend DocBook almost arbitrarily without changing the DTD,
though, so one could go and add any missing expressions. This effort
could then flow back into the standard --- and that would be great.

 >> [I just place] 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 :)

It depends. You don't need to wrap _anything_ in a tag just to be able
to generate dependencies, links, etc. I always use the more basic tags
like <type>, <classname>, etc., and that has worked nicely for me.

        -peter