PUBLICAN DOC BUILDING: A QUICK HOWTO
Some of the newer SystemTap documentation (for example The SystemTap Beginners Guide) is being written using Publican. Publican, an open-source toolchain, outputs several formats from XML. These formats include HTML, PDF, RPM, HTML-single, etc.Publican is available on Fedora. Additional details about Publican are at http://fedoraproject.org/wiki/DocsProject/Publican.
PUBLICAN SETUP
On Fedora install Publican and the related brand files using:
yum install publican\*
GENERATING FORMATTED DOCUMENT
Go into the document directory, for example:
cd systemtap/doc/SystemTap_Beginners_Guide
The directory will have the en-US directory which holds the XML source for the English version of the documentation and the Makefile to create the various formats. Examine the Makefile and make sure that the BRAND is set appropriately. On a Fedora machine it should be set to:
BRAND = fedora
The syncandbuild command in the directory copies the need example files and starts the make. To make PDF version of the document:
./syncandbuild
When asked for "build target" type in:
pdf-en-US
Just hit return when asked for "build parameters".
To make html version of the document: use html-en-US rather than pdf-en-US.
The resulting formatted documentation will be be placed in tmp/en-US/pdf subdirectory for the pdf version and tmp/en-US/html for the html version.
You can remove the generated output with:
make clean
CREATING NEW DOC
It is advisable that you use Publican to build your source XML from the ground up to begin with. Once Publican is installed, run the following command:
create_book --name <book_name> --version <version> --product Red_Hat_Enterprise_Linux --brand fedora
The <book_name> is your book's full title; use underscores (_) instead of spaces. For resources on writing in Docbook XML, refer to the following link: http://www.docbook.org/tdg/en/html/ To build a local HTML build, use the following command:
make html-en-US