Re: V2 documentation format

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 (http://svnbook.red-bean.com/) 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
>> >
>> > 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.
>
> 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
www.boost-consulting.com