Re: V2 documentation format: a resolution?

From: Christopher Currie (Christopher_at_[hidden])
Date: 2004-02-03 10:55:21

Vladimir Prus wrote:

> Zbynek Winkler wrote:
> 
>>Vladimir Prus wrote:
>>
>>>So, let's go with DocBook?
>>
>>Is there anyone here familiar with the DocBook toolchain? What is needed to
>>get i.e. html out of it? Could someone write a quick howto for the most
>>common platforms, so we can try it out before the final decision?

You need three things:

1. An XML stylesheet processor (ususally xsltproc)
2. The DocBook DTD.
3. The DocBook XSL stylesheets.

Fortunately there is a wrapper script that makes using these a lot 
easier: xmlto <http://cyberelk.net/tim/xmlto/>. I've found this to be a 
great tool for doing XML conversions, and many Linux distros set it up 
to depend on packages for the DocBook DTD and XSL data files.

The most recent BoostBook docs can be found at 
<http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/boostbook.html>, 
and I used the Getting Started section to get my own toolchain working. 
I'm not running xsltproc by hand; I'm letting the BBv2 boostbook toolset 
do the work, and it works pretty well so far. A simple:

boostbook bbv2 : bbv2.xml ;

creates an 'html' directory with the generated files. There's a <format> 
feature that lets me select the output format; the default is an 'html' 
directory, but I can use <format>onehtml to generate a single html file, 
<format>man for manpages, or <format>pdf for PDF output.

Feel free to ask me if you have specific questions about the setup.

Christopher