Boost logo

Boost-Build :

From: David Abrahams (dave_at_[hidden])
Date: 2004-02-03 07:16:18

Vladimir Prus <ghost_at_[hidden]> writes:

>> 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.
> Hmm... I'm pretty sure one can add images to Docbook, at least book on
> Subversion ( uses them, and they work in PDF,
> too.

Yes, FOP was only choking on some images... or was it Jimi that
choked? That whole Java toolchain is a big mess.

>> 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.
> That's good, but I'd rather not plan to write any code just just to get better
> documentation.

Understood. It's just a question of whether the long-term cost of
requiring anyone who wants to write documentation to write/know/read
DocBook is worth it.

>> > 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
>> document.
> But how do you add "next" and "prev" links in this case?

I think the only way to solve that problem *automatically*, if it
needs solving, is with a preprocessor or another ReST extension.

Dave Abrahams
Boost Consulting

Boost-Build list run by bdawes at, david.abrahams at, gregod at, cpdaniel at, john at