V2 documentation format

From: Vladimir Prus (ghost_at_[hidden])
Date: 2004-02-02 04:26:48

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? 

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. 
What should be done now? I would not like to ignore the work that Zbynek has 
done, but is there something wrong with the idea of using new tool just to 
generate headers? After all, I can do that in HTML, once. Other concern is 
that not all will be able to generate HTML from PHP. Finally, if we're going 
to move to Docbook someday, then we probably should not switch now to yet 
another format, to minimize confusion.

Thoughts?

- Volodya