RE: [boost] Reference documentation: one approach

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

William E. Kempf writes:
 > 
 > Anthony Williams said:
 > > 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 don't see that this misses the point. We want a specific set of output from
our source document. With DocBook, you write something to parse the source
directly, and produce your output. With (La)TeX you write a tool to use
(La)Tex to parse the source, and produce your document --- look at the
difference between TeXinfo and LaTeX documents, for example; they both use the
same backend (TeX), but the sources are quite different. Similarly, you can
produce HTML, XML, RTF, PostScript and PDF from the same LaTeX source with
little hassle.

IOW, both DocBook and (La)TeX can be used to write documents that can be
transformed into whatever output you require, but the techniques are
different. 
 
 > > 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.

I had forgotten that DocBook comes in an SGML form as well as the newer XML
form. However, SGML is *lots* harder to parse than XML, so using SGML DocBook
loses some of its benefits.
 
 > 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.

Yes; whatever tool we use, it needs to be easy to write the documentation.

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