RE: [boost] Reference documentation: one approach

From: William E. Kempf (wekempf_at_[hidden])
Date: 2002-10-30 11:46:24

Anthony Williams said:
> William E. Kempf writes:
>  > David Bergman said:
>  > > 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.

This misses the point.  DocBook, being XML based, is trivial to parse and
manipulate in any way you can imagine.  TeX/LaTeX on the other hand is
specifically designed for document transformations, and as such is not as
flexible.

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

It's the installation of the foreign tools that's a pain for me.  These
tools are usually ported from *nix, and as such require complicated
installation procedures.  In this regard, LaTeX may very well be easier. 
But once installed, both are as simple to use as writing text in an editor
and running a command line utility against it.

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

DocBook can be as simple in two ways.  First, if you use the SGML form
there are a lot of "minimization" techniques that are allowed.  Your
example could be coded in DocBook as <emphasis/stuff to be emphasised/,
which is practically identical.  This input can then even be translated to
full XML compliant code, if there's a reason for it (such as allowing easy
parsing, as discussed above).  Second, when using an XML editor you never
really have to type the tags any way.

However, I agree with Dave that it would be beneficial for all if we had
an even simpler solution (preferrably one that could output DocBook and/or
LaTeX).  So we need to keep our options open and do some more research.

-- 
William E. Kempf