Re: [boost] Reference documentation: one approach

From: Maciej Sobczak (maciej_at_[hidden])
Date: 2002-10-29 08:46:36

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

- XML is more trendy in this season.

I'm really sorry if you find the second point offensive, but I just do 
not understand the motivation for the additional effort with XSLT. Note 
also that the description of the logical structure of the text is much 
more concise in LaTeX than in XML. At least I think so.

My 0.05 Euro.

Maciej Sobczak
http://www.maciejsobczak.com/