Working with DocBook Manuals

Required Tools

No special tools are needed to edit DocBook files, but in order to build DocBook manuals, you need to have a DocBook tool chain installed on your system, including GNU Make, OpenJade, and various DocBook tools.

The command below installs the toolchain on Ubuntu-based systems (tested successfully on Ubuntu 12.04 and 13.04 desktop)

  $ sudo apt-get install docbook docbook-dsssl docbook-slides docbook-utils linuxdoc-tools make openjade xmlto

For Debian-based Linux distributions, simply install the necessary packages with the following command:

  $ sudo aptitude install docbook docbook-dsssl docbook-slides docbook-utils linuxdoc-tools make openjade xmlto

For Fedora-based distros, run this command instead:

  $ su -c 'yum groupinstall "Authoring and Publishing"'

To build the docbook in the master branch, additional package publican is required.

Building a DocBook Manual

We will use the Developer’s Guide in English as the example manual for this process, which is in the developers/en/ directory. You can substitute any other manual or language, assuming the manual exists and has been translated to that language.

Enter the directory containing the preferred manual:

  $ cd /path/to/mantisbt/docbook/adminguide/en

Run make with a list of resulting file types that you want to build. Currently, our DocBook manuals can produce PDF, HTML (split or single page), RTF, Postscript, or plain-text manuals. All resulting manual files will be placed in the build/ subdirectory. In this example, we will build both a PDF and a split HTML manual:

  $ make pdf html
  $ ls -R build/
  build:
  developers  developers.pdf

  build/developers:
  dev.database.html          dev.eventref.html  dev.plugins.html  index.html
  dev.database.install.html  dev.events.html    images            LEGAL.html

For installing manuals into a specific location, such as for building manuals on web servers, first clean and build the desired DocBook manuals, and then run the install routine with the necessary install path:

  $ make clean
  $ make pdf html
  $ make INSTALL_DIR=/path/to/install install

- or for cron jobs (order matters):

  $ make INSTALL_DIR=/path/to/install clean pdf html install

Simple Build Script

Taking it one step further, there is a Python script in trunk/dev/ named docbook-manual.py that takes the following set of arguments to automate the update/build process from an SVN checkout:

  $ docbook-manual.py <mantisbt/docbook> <destination_path> [<lang> ...]

The last parameter is optional, and can be a space-separated list of docbook languages to build. The results are put into the destination directory in the form of <lang>/<manual>. An example command and resulting hierarchy:

  $ /home/user/mantisbt/trunk/dev/docbook-manual.py /home/user/mantisbt/trunk/docbook /var/www/mantis en de
  $ tree /var/www/mantis
  mantis
  -- en
  ---- administration_guide
  ---- developers
  -- de
  ---- administration_guide
  ---- developers
 
Logged in as: anonymous
mantisbt/docbook.txt · Last modified: 2013/05/10 09:11 by dregad