Re: [boost] Reference documentation: one approach

From: Mattias Flodin (flodin_at_[hidden])
Date: 2002-10-30 04:25:56

On Tue, Oct 29, 2002 at 03:05:08PM -0500, Douglas Gregor wrote:
> [I'm going to try to pin down my set of requirements for Boost reference 
> documentation so that we can try to evaluate potential solutions more 
> objectively]

Please do! Discussing what is required of the solution rather than which
solution is preferred might give more consensus. Perhaps the list can be
put somewhere and added to as people name (and agree on?) requirements.

So far the requirements I can remember seeing are:

 * Should be possible to express mathematical formulas
 * The source format should be easy to write _and_ read
 * Should allow for transformation to many other formats, e.g. HTML,
   LaTeX and PDF.
 * Should be customizable (e.g. macros / substitutions)
 * Should be easy to learn (that's the only way to get people to
   actually write documentation)

To this I would like to add:

 * Should have freely available, well-written and complete reference
   documentation on the typesetting language and tutorials on how to use it.
 * Must be possible to add hyperlinks between documents.
 * Must be able to represent documents in other languages than English
   (to support translation efforts).
 * Should be available for UNIX, MacOS (X only?) and Windows (_without_
   having to install POSIX emulation layers). Possibly other platforms?

The math notation requirement I personally don't really agree with at
the moment - so far the need for mathematical notation doesn't seem to
have been that high. But perhaps that will change in the future,
especially considering the recent interest in numerical integration
functions. 

The remainder of this post gives only my arguments on why LaTeX does not
comply with these requirements.

I think LaTeX can be ruled out because it fails on at least the
learning, translation and free-documentation points. It also possibly
fails on the hyperlink point, although I could quite possibly be wrong
about this (I know conversion to HTML can generate section links, but
can you make cross-document links?).

I have been using LaTeX for 3-4 years now and I still have trouble
figuring out how to do things. I never bought a book on the subject and
thus have to rely on ad-hoc web pages that only document pieces of the
system. Even the simplest thing, such as choosing a different font for
section headings, is something I still haven't found how to do properly
(I currently simply do \renewcommand{section} but that just can't be the
right way to do it). Changing to european-style paragraph spacing turned
out to be impossible to do in a way that is guaranteed not to break in
some cases. Furthermore, due to its nature of being a type-unsafe macro
language, I often get errors deep deep down in the macro package because
of issuing the wrong arguments to some command. It is actually quite
reminiscent of the indecipherable errors you get from C++ compilers when
instantiating templates with noncomplying arguments.

As for translation into other languages, conversion to PDF runs into
problems when using non-english characters (e.g. Å Ä Ö). If I understood
things correctly, Acrobat Reader is really to blame for this, but the
problem is there regardless (what happens is that the screen rendering
comes out in very poor quality, making it difficult to read the text). I
know there are some efforts to support CJK character sets, but AFAIK
these are not complete, and they are definitely not well-documented. I
also strongly doubt that it would be possible to transform Chinese LaTeX
documents into proper Chinese HTML.

<rant>
The entire language feels to me like a set of patches upon patches, with
no sense of orthogonality or simplicity whatsoever. For instance, the
\verb command for verbatim text can be used in paragraphs but not in
footnotes or section headings. I never found a document that explains
why. Any typesetting language that gives error messages such as "Badness
10000" or "You need to go see a wizard" scares me.
</rant>

/Mattias
(Note that when I say "I doubt that..." or "I don't think...", it is not
attempts at FUD, but simply to say that to the best of my knowledge,
there is no way. But since the documentation is incomplete, there may be
ways that I am not aware of.)

-- 
Mattias Flodin <flodin_at_[hidden]>  -  http://www.cs.umu.se/~flodin/
Room NADV 102
Department of Computing Science
Umeå University
S-901 87 Umeå, Sweden
--
"If there's anything more important than my ego around, I want it
caught and shot now."  -- Zaphod Beeblebrox