RE: [boost] Reference documentation: one approach

From: David Bergman (davidb_at_[hidden])
Date: 2002-10-29 15:15:09

Bill,

I agree. When I said "preferred" I (implicitly) meant "beside HTML",
since HTML should remain a format in which Boost documentation should be
representable. Whether it is to be the "orginal" format or not is
another question.

What follows is my overall opinion in this matter, being not only very
humble, but rather ignorant.

Whatever the original format is there must be an automated means to
convert between them, preferrably at CVS commit, ending up with:

1. HTML
2. That "other" format, being DocBook, LaTeX or similar
3. An alternative rendered format of (2), preferrably PDF

(2) and (3) should be optional, but (2) requires (3).

Of course, (1) could be generated from (2).

/David

-----Original Message-----
From: boost-bounces_at_[hidden]
[mailto:boost-bounces_at_[hidden]] On Behalf Of William E. Kempf
Sent: Tuesday, October 29, 2002 2:56 PM
To: boost_at_[hidden]
Subject: RE: [boost] Reference documentation: one approach

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
_______________________________________________
Unsubscribe & other changes:
http://lists.boost.org/mailman/listinfo.cgi/boost