Re: [boost] Reference documentation: one approach

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

Maciej Sobczak said:
> Douglas Gregor wrote:
>> Boost library documentation is scattered amongst many HTML files in
>> many  different directories. Several users and developers have
>> expressed an  interest in unified reference documentation for all of
>> the Boost libraries.
> [...]
>> I chose to try out an XML format for the documentation, using XSLT to
>> transform the XML into a suitable HTML document.
> [...]
>>   4) We can transform the XML into whatever sort of medium we want.
>
>> Comments? Questions? Boos from the crowd?
>
> I think that the effort of creating a unified documentation is a very
> reasonable idea. However...
>
> AFAIK, the well-established way to write anything is to use LaTeX. It
> has all the characteristics you write, from "omnipresence" to
> possibility to convert to any format I've heard of.

I'd have to disagree. LaTeX has a large dominance on *nix platforms, but
that's about it.  XML, on the other hand, has just as large a dominance on
every platform.  Further more, DocBook (SGML/XML based) has become the
standard for electronic documentation.  It's much more flexible than LaTeX
in what it can represent in the documentation, and is also convertable to
practically any format you'd ever care to convert it to... including
LaTex.

The problem is the complexity.  With HTML documentation, Boost doesn't put
hardly any burden on the developers.  Most already know enough HTML to
produce documentation from scratch.  What they don't know is very easy to
learn, documented all over the place and shouldn't cause any steep
learning curves.  More over, there's a LOT of HTML editors available that
make it nearly as simple as using a word processor, which completely
eliminates any issues with complexity.  And a huge bonus is that the
documents are static, requiring no intervention at distribution time...
where as LaTex and DocBook would require some preprocessing to convert
them to a format usable by the target audience (likely HTML, though PDF
would also be an alternative that's widely available and accepted).

I've been very interested in DocBook for Boost documentation, because it
can produce much nicer documents, with more consistent formatting, and
allow for printing of the entire documentation set, including table of
contents and indexes.  It's the complexity that's held me back.  The DTD
is daunting, and with out a tool to manage it, I'm not sure our developers
could afford the learning curve.  However, I believe there are now some
solutions to this.  For instance, AbiWord is supposed to import/export to
the DocBook format... but the question is how good a job it does.  Also,
the tools used to convert DocBook to the various formats are, well, quite
complex.  On *nix platforms you can usually get these up and running with
out too much difficulty (I believe some distros even install this stuff by
default, though I've not done any real research on this), but on Win32
platforms it's a major pain.  I had occasion to do this for work once, and
it required 2 days of research and 2 more days of hair pulling frustration
to get anything to work.  And after all that, I can't say that I really
learned anything or feel comfortable that I could reproduce what I did
with out spending another 2 days of frustration again.

If anyone has knowledge/experience about DocBook that they'd like to
share, I'd be glad to hear from you (though probably directly, as it's
only peripherally related to Boost and thus off topic).

> The difference between XML/XSLT and LaTeX is that:
>
> - LaTeX is *ALREADY* present in every reasonable Unix/Linux
> distribution, it is also available as freeware for Windows. Nobody
> expects from you writing any additional tool: PDF? PostScript? RTF?
> HTML? plain text? man pages? They're all there.

The same can be said for XML/XSLT.

> - XML is more trendy in this season.

I don't get this point.

-- 
William E. Kempf