Re: [boost] Reference documentation: one approach

From: Anthony Williams (anthony.williamsNOSPAM_at_[hidden])
Date: 2002-10-30 05:38:35

Mattias Flodin writes:
 > 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.

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

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

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

Which I will attempt to refute, because I think LaTeX _does_ comply with the
requirements, IMHO.
 
 > 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 found it remarkably easy to learn to _write document_ using LaTeX --- it is
learning to write macros that is tricky, and thankfully, we should only have
to do that once at the beginning (to write a boost LaTeX class), and then
small maintenance issues as people want to add more stuff.

Using the hyperref package, it is quite straight forward to produce
cross-document links (they even appear as proper hyperlinks in PDF).

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

I guess everyones experience is different. I, too, have never read a book on
LaTeX, and rely on web pages, and comp.text.tex, but I don't find things too
tricky. The basic LaTeX stuff is documented in the "Guide to LaTeX 2e", which
is available in HTML with all distributions, and each package has its own
documentation. Since the packages are generally contributed by independent
authors, I wouldn't expect there to be centralized documentation, but there is
at least a FAQ, and a catalogue on CTAN of available packages, and what they
do.

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

This is formatting, not content --- we really ought to only have to specify
formatting _once_, for the whole of boost, and then we will get a consistent
style. As an aside, use the titlesec package.

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

Again, once we've got the fundamental macros written, documents should only
contain basic macros, so this shouldn't be too much of a problem.
 
 > 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). 

Sounds more like using the wrong font, or the wrong font encoding to me ---
Type1 fonts are very high quality when viewed in Acrobat Reader (whereas Type3
fonts generated from MetaFont are generally poor), and if you need a
non-english character then you need to ensure that you are using the correct
font encoding, so that the characters are converted correctly. You might also
want to try using Omega (Unicode-based TeX, for those who don't know)

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

This is not something I've ever tried. Why don't you ask on comp.text.tex?
 
 > <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>

The basic language (TeX) is very clean. Basic LaTeX is also quite
clean. However, like with C++, lots of the power comes from the ability to add
third party libraries (packages). The guys who maintain CTAN do a good job of
pulling together all these packages into one place, for easy access, and the
people behind the TeXLive CDs also provide a comprehensive set of these
packages on CD. Since they are written by third-parties, sometimes they will
work together, and sometimes not, and sometimes they will have a similar
interface, and sometimes not. However, the authors tend to be quite happy to
accept comments, and incorporate changes --- if you say you want to use
package A with package B, then someone will be willing to help you do that, if
it seems reasonable (using two packages with overlapping functionality is
bound to cause problems, though).

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