Re: [boost] Re: Reference documentation

From: Anthony Williams (anthony.williamsNOSPAM_at_[hidden])
Date: 2002-10-30 03:51:41

William E. Kempf writes:
 > 
 > Kevin S. Van Horn said:
 > > As I see it, the advantages of DocBook are
 > >
 > > 1. Well-established standard tool (same advantage applies to LaTex, but
 > >    not to home-grown XML or the ReStructuredText Dave mentioned).
 > >
 > > 2. Readily-available tools to convert to both HTML (for Web
 > > presentation)
 > >    and Tex/postscript/PDF (for printed documentation).
 > >
 > >    - Whether or not it is easy to do this conversion on platforms other
 > >      than Unix isn't a big deal, as it only has to be done once for each
 > > release, and then the converted forms can be distributed as part of
 > > the Boost package.
 > 
 > I have to disagree with this point.  As a developer, I have to know that
 > the documentation I write is accurate and presented in a "proper" form. 
 > If I can't generate the final output I can only be sure of half of that.

Agreed. However, there are free LaTeX distributions for Windows and MacOS, and
probably others too.
 
 > >    - The lack of a reasonable printed form for Boost documentation has
 > >      always been an irritating problem.
 > 
 > This part I totally agree with, and it's one of the compelling reasons for
 > finding another solution.
 > 
 > > 3. The focus is on structure, not presentation.  This makes it much more
 > >
 > >    suitable for automatic processing to extracting indices and other
 > > information from the documentation.  For example, one could
 > >    automatically generate the Concepts Dictionary that I've mentioned in
 > >  the past.
 > >
 > > I think that (2) and (3) are especially important.
 > 
 > I think (again, I'm no expert on either) that LaTeX can do 2 as well. 
 > It's 3 where DocBook appears to have an advantage.

LaTeX can definitely convert to both HTML and PDF/PostScript quite
readily. The printed (PDF/PostScript) output is _very_ good, whereas HTML
output often needs a bit of fiddling (with config files, not with the output)
to get it looking just how one might like (though the "initial attempt" is
generally reasonable).

As for point 3, one of the main features of using LaTeX is that you can focus
on structure, and let the tools take care of the presentation. If the required
structural element isn't present, you can add a package to provide it. If we
were to use LaTeX, I would imagine that we would write a Boost LaTeX class
which provided all the necessary structural elements, along with appropriate
formatting information for generating output, and then writing documentation
is just a matter of "filling in the blanks" --- I want a section here, an
itemized list there, a C++ class definition over there, etc.

Likewise, if we were to use DocBook, I would expect to find a Boost stylesheet
(or set thereof) to control the output.

Anthony
-- 
Anthony Williams
Senior Software Engineer, Beran Instruments Ltd.
Remove NOSPAM when replying, for timely response.