Re: V2 documentation format

From: David Abrahams (dave_at_[hidden])
Date: 2004-02-02 10:14:52

Vladimir Prus <ghost_at_[hidden]> writes:

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

I still don't know what "header" means in this context.

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

I generate PDF by going through TeX and using pdflatex. It works
great for me. Generating PDF directly is probably not going to be a
winner very soon, because ReportLab (the Python PDF library) has put
relatively little attention on figuring out how to generate page
breaks. It's not a hugely difficult problem, but the company behind
ReportLab probably isn't going to invest in it.

I did try generating DocBook at one point. It seemed to work, but I
was really just trying to get to PDF, and FOP (the DocBook -> PDF tool
I know about) was a pain to get running, and then IIRC FOP was choking
on some simple embedded images so I gave up on it.

Two other points about DocBook: 

1. docutils writers are easy to write and modify, so I'm sure we
could get acceptable DocBook fairly quickly if the current writer
is missing something.

2. docutils has a native XML output, so as a last resort anyone
versed in XSLT should be able to write a docbook translator that
way, IIUC.

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

Generally you write each separate HTML page in a separate ReST
document.

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