RE: [boost] Reference documentation: one approach

From: Anthony Williams (anthony.williamsNOSPAM_at_[hidden])
Date: 2002-10-30 04:23:11

William E. Kempf writes:
 > 
 > David Bergman said:
 > > I agree with Bill (Kempf) that LaTeX would also host some of the
 > > benefits of DocBook, if generation of static documents can be automated
 > > or considered trivial. In the case of LaTeX, this community probably has
 > > several individuals who could "pdftex" them, and, soon enough, add a
 > > "pdftex" as an automated script to CVS.
 > >
 > > I would definitely support PDF as the preferred static document format,
 > > most people do have or can install PDF readers on their platforms (or?)
 > 
 > As an additional format, sure (it's better suited for printing), but as
 > the preferred format, no.  The preferred format will remain HTML, I think,
 > for use on the Boost web site.

I'd just like to point out that PDF supports hyperlinks between documents, and
can be "linearized" so that they can be viewed whilst downloading in the
background, so viewing a set of PDFs need not be unlike viewing a set of HTML
pages.

But yes, we ought to have HTML output too, since not everyone has a PDF plugin
for their browser, even if they have a PDF viewer.
 
 > > I am a bit curious as to the benefits of DocBook (I have only played
 > > with it, so I am definitely one of those pseudo-knowledgable in that
 > > field) in comparison to LaTeX.
 > 
 > Both are very comparable.  As a non-expert of either, I can still point
 > out a few differences.  DocBook is better suited for transformations and
 > other such processing.  Here's an interesting link on the subject (of
 > course, this is a religious issue, so you'll find similar posts/remarks
 > about LaTeX being better than DocBook):
 > http://mail.gnome.org/archives/gnome-list/1998-April/msg01049.html.

If you posted that link on comp.text.tex, you would get pounced on. The whole
point of LaTeX is that you specify _what_ you want to typeset, and the tools
do it for you. If there isn't a macro for what you want, you can write a
package to specify it, including how it should be formatted.

As for transformations, there are many tools for converting TeX/LaTeX to other
formats, such as latex2html, latex2rtf, etc. In particular, TeX4HT can convert
(La)TeX to HTML and XML with very little effort, and even handles custom
macros (which many other solutions can't) because it uses the TeX processor
itself to format the document. I believe it is configurable for other such
structured output formats too, but that probably requires a fair bit of work
writing the config files.

 > I can read/understand/write DocBook because I'm used to XML/HTML.  That's
 > honestly probably the biggest reason I lean towards DocBook instead of
 > LaTeX, but the fact of the matter is that both are going to be painful for
 > me to use on Windows.  So maybe tbook is worth looking into.  And the
 > reStructuredText would be the easiest to use, if it can handle the scope
 > of Boost documentation.

I mainly use LaTeX on Windows, which is simply a matter of installing the
TeXLive CD, entering the LaTeX source in a text editor (I use XEmacs 21.4.10
native-win32, with the AUC-TeX package) and running (pdf)latex at the command
prompt (or from xemacs).

I am also very familiar with XML/SGML/HTML, but I still find LaTeX easier to
write and read than XML. For starters, you only (generally) specify each name
once --- \emph{stuff to be emphasised} rather than <emph>stuff to be
emphasised</emph>.
 
 > > MathML seems to offer a lot of features that are probably not crucial
 > > for Boost documentation, such as canonical representations of formulas,
 > > being independent of the layout. The Match subset of LaTeX seems to be
 > > more suited for our rather non-stringent (in the mathematical sense)
 > > communication.
 > 
 > I just don't think the math stuff is too important.  Very little of our
 > documentation needs the full power of a math renderer.  When it's needed
 > there's ways to deal with it.  Even if it's only using your favorite
 > solution and rendering it as a JPEG in the documentation.

Agreed.

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