RE: [boost] Reference documentation: one approach

From: William E. Kempf (wekempf_at_[hidden])
Date: 2002-10-31 09:40:55

Anthony Williams said:
> 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've given one example already.  A parser that can verify the code and
documentation are up to date.  Another good example would be a tool to
auto-generate test cases.  You probably could get LaTeX to do some of
this, but not easily because the emphasis on data presentation is
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.

There are standard transforms to change the SGML into fully compliant XML,
rendering this a non-argument. ;)

-- 
William E. Kempf