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
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.
>> 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
> Also, looking at
> 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
-- Dave Abrahams Boost Consulting www.boost-consulting.com
Boost-Build list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk