Re: V2 documentation format

From: David Abrahams (dave_at_[hidden])
Date: 2004-02-02 09:12:19

Vladimir Prus <ghost_at_[hidden]> writes:

> Hello,
> recently, several people asked that V2 docs be split into more manageable 
> parts. Zbynek Winkler made an initial attempt on this, and results can be 
> seen at 
>
> http://zigzag.lvk.cs.msu.su/~ghost/Boost.Build.docs/
>
> First question is how does it look? 

It's beautiful!

> The second question is what documentation format should be use. Zbynek has 
> used PHP to automatically generate header and navigation links, and I'd like 
> to discuss if we're going to use that format, or current html, or something 
> else.
>
> Here's a table listing possible alternatives: staing with what we have now, 
> using PHP, and using Docbook. (Make sure your mailer uses fixed font when 
> reading this).
>
> HTML PHP DOCBOOK
> Need for migration no done arleady yes, hard
> Automatic headers no yes yes
> Automatic TOC no no yes
> PDF output no no yes 
> Familiarity yes low? more-or-less?
> Full language no yes no
>
> Eventually, I think moving to Docbook is the best approach. 

I don't know what "automatic headers" and "Full Language" mean, but
I'd like to suggest RestructuredText. It can generate docbook, PDF,
automatic TOC, but most importantly the source code format is fast to
write and easy to read as plain text. Aleksey and I are writing a
book in RestructuredText, and it's been a very positive experience.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com