Re: [boost] Re: Reference documentation

From: William E. Kempf (wekempf_at_[hidden])
Date: 2002-10-29 16:22:31

Kevin S. Van Horn said:
> As I see it, the advantages of DocBook are
>
> 1. Well-established standard tool (same advantage applies to LaTex, but
>    not to home-grown XML or the ReStructuredText Dave mentioned).
>
> 2. Readily-available tools to convert to both HTML (for Web
> presentation)
>    and Tex/postscript/PDF (for printed documentation).
>
>    - Whether or not it is easy to do this conversion on platforms other
>      than Unix isn't a big deal, as it only has to be done once for each
> release, and then the converted forms can be distributed as part of
> the Boost package.

I have to disagree with this point.  As a developer, I have to know that
the documentation I write is accurate and presented in a "proper" form. 
If I can't generate the final output I can only be sure of half of that.

>    - The lack of a reasonable printed form for Boost documentation has
>      always been an irritating problem.

This part I totally agree with, and it's one of the compelling reasons for
finding another solution.

> 3. The focus is on structure, not presentation.  This makes it much more
>
>    suitable for automatic processing to extracting indices and other
> information from the documentation.  For example, one could
>    automatically generate the Concepts Dictionary that I've mentioned in
>  the past.
>
> I think that (2) and (3) are especially important.

I think (again, I'm no expert on either) that LaTeX can do 2 as well. 
It's 3 where DocBook appears to have an advantage.

-- 
William E. Kempf