RE: [boost] Reference documentation: one approach

From: William E. Kempf (wekempf_at_[hidden])
Date: 2002-10-29 14:56:04

David Bergman said:
> Mohammed,
>
> Is that not just DreamWeaver?
>
> A "Studio" package, including web application logic connection, seems to
> a bit overkill in this context...
>
> Anyhow, there are a multitude of HTML editors out there.

And most of us are using something more than notepad here.

> I agree with Bill (Kempf) that LaTeX would also host some of the
> benefits of DocBook, if generation of static documents can be automated
> or considered trivial. In the case of LaTeX, this community probably has
> several individuals who could "pdftex" them, and, soon enough, add a
> "pdftex" as an automated script to CVS.
>
> I would definitely support PDF as the preferred static document format,
> most people do have or can install PDF readers on their platforms (or?)

As an additional format, sure (it's better suited for printing), but as
the preferred format, no.  The preferred format will remain HTML, I think,
for use on the Boost web site.

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

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.

> MathML seems to offer a lot of features that are probably not crucial
> for Boost documentation, such as canonical representations of formulas,
> being independent of the layout. The Match subset of LaTeX seems to be
> more suited for our rather non-stringent (in the mathematical sense)
> communication.

I just don't think the math stuff is too important.  Very little of our
documentation needs the full power of a math renderer.  When it's needed
there's ways to deal with it.  Even if it's only using your favorite
solution and rendering it as a JPEG in the documentation.

-- 
William E. Kempf