Re: [boost] Reference documentation: one approach

From: Peter Simons (simons_at_[hidden])
Date: 2002-10-29 10:43:00

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:

      <classsynopsis>
        <ooclass>
          <classname>rfc822address</classname>
        </ooclass>
        <fieldsynopsis>
          <type>std::string</type>
          <varname>address</varname>
        </fieldsynopsis>
        <fieldsynopsis>
          <type>std::string</type>
          <varname>localpart</varname>
        </fieldsynopsis>
        <fieldsynopsis>
          <type>std::string</type>
          <varname>hostpart</varname>
        </fieldsynopsis>
      </classsynopsis>

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

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

There are a few more good arguments in favour of DocBook:

 - Many, many tools exist that process the DocBook format. You can
   create quality(!) output in RTF (means: MS Word), TeX (means:
   superb printed documentation), HTML, roff (Unix man page), and so
   on and so forth.

 - Accurate DTDs do exist already.

 - The DSSSL formatting backend is very flexible, extensible and
   _fast_ compared to most XLST implementations -- albeit it is
   programmed in some Lisp/Scheme/Whatever variant that is somewhat
   scary. :-)

 - It's a freely available, open industry standard.

 - I hear (No first-hand knowledge here!) that LyX and OpenOffice can
   export documents in DocBook format. Certainly Emacs with PSGML can.

 > The answer is probably to use both. 

I definitely agree with you in so far as that choosing XML or SGML as
the documentation format is the right way to go. Which DTD one chooses
for that isn't that important, IMHO, because you can convert them back
and forth anyway. :-) Personally, I use DocBook for all my texts and I
am very happy with it.

        -peter