Re: [jamboost] Re: V2 documentation format

From: Vladimir Prus (ghost_at_[hidden])
Date: 2004-02-02 09:27:03

David Abrahams wrote:

> > First question is how does it look?
>
> It's beautiful!

That's good.

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

First means the header with all the section names and nagivation links.
The second means access to full programming language where you can write 
anything you desired.

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

Did you tried docbook and PDF? The page at http://docutils.sourceforge.net/
says that 

Writers for DocBook XML and PDF have been started

Which implies they are not quite ready. Also, looking at

http://docutils.sourceforge.net/docs/tools.html

it's not clear if it can split html at section boundaries, which is desired 
for Boost.Build docs.

- Volodya