Re: [jamboost] Re: V2 documentation format

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

David Abrahams wrote:

> > First means the header with all the section names and nagivation
> > links.
>
> I still don't know what "header" means in this context.

I use it to mean automatically generated text which is added at the top of 
page and provides nagivation links.

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

Ok. Last time I tried pdflatex produced decent results.

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

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

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

- Volodya