====== Working with DocBook Manuals ======

===== Required Tools =====

No special tools are needed to edit DocBook files, a plain-text editor is good enough to do the job, although a specialized XML editor may be useful.

In order to build the manuals however, you need to have a working DocBook tool chain installed on your system.


==== MantisBT 1.3 and later ====

MantisBT 1.3 uses [[https://fedorahosted.org/publican/|Publican]] to build the documentation. All necessary tools can be installed with the following command, which takes care of dependencies.

<code>
$ sudo apt-get install publican
</code>

This was tested successfully on Ubuntu 14.04 LTS, but should work with older versions too.


==== MantisBT 1.2 ====

To build MantisBT 1.2 documentation, this tool chain includes //GNU Make//, //OpenJade//, and various //DocBook// tools.

The command below installs the toolchain on **Ubuntu**-based systems (tested successfully on Ubuntu 12.04 LTS and 13.04 desktop)
<code>
$ sudo apt-get install docbook docbook-dsssl docbook-slides docbook-utils linuxdoc-tools make openjade xmlto
</code>

For **Debian**-based Linux distributions, simply install the necessary packages with the following command:
<code>
$ sudo aptitude install docbook docbook-dsssl docbook-slides docbook-utils linuxdoc-tools make openjade xmlto
</code>

For **Fedora**-based distros, run this command instead:
<code>
$ su -c 'yum groupinstall "Authoring and Publishing"'
</code>

===== Building a DocBook Manual =====

==== MantisBT 1.3 and later ====

GNU Make files are present in each DocBook's directory, allowing easy build with a single command.

To build all DocBooks in default //html-desktop// format <code>
cd /path/to/mantisbt/docbook
make
</code>

To process a specific DocBook, first go to the corresponding directory, e.g. for Administrator's Guide <code>cd /path/to/mantisbt/docbook/Admin_Guide
</code>

then execute the appropriate command:

  * Build it in default (//html-desktop//) format <code>make</code>
  * Validate the XML files, without building the DocBook <code>make test</code>
  * Build a PDF <code>make pdf</code>
  * Clean build in all available formats <code>make clean all</code>

This is just a few examples, refer to the [[https://github.com/jhradilek/publican-makefile|Makefile's documentation]] for further details.

It is also possible to manually execute Publican, e.g. <code>
publican build --langs=en-US --formats=html-desktop,pdf
</code>

==== MantisBT 1.2 ====

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:
<code>
  $ cd /path/to/mantisbt/docbook/adminguide/en
</code>

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:
<code>
  $ 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
</code>

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:
<code>
  $ make clean
  $ make pdf html
  $ make INSTALL_DIR=/path/to/install install
</code>

- or for cron jobs (order matters):
<code>
  $ make INSTALL_DIR=/path/to/install clean pdf html install
</code>

===== 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:

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

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:

<code>
  $ /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
</code>