Differences

This shows you the differences between two versions of the page.

--- mantisbt:docbook [2008/08/25 13:32] – jreese
+++ mantisbt:docbook [2025/12/30 07:11] (current) – [MantisBT 1.3 and later] fix broken link dregad
@@ Line 1: / Line 1: @@
+====== 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://sourceware.org/publican/en-US/index.html|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>