Differences

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

--- mantisbt:docbook [2013/05/10 09:11] – Added reference to publican for docbook in master branch dregad
+++ mantisbt:docbook [2016/07/03 11:26] (current) – [MantisBT 1.3 and later] added new section's contents 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.
-===== Required Tools =====
+In order to build the manuals however, you need to have a working DocBook tool chain installed on your system.
-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)
+==== 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 docbook docbook-dsssl docbook-slides docbook-utils linuxdoc-tools make openjade xmlto
+$ 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
+$ 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"'
+$ su -c 'yum groupinstall "Authoring and Publishing"'
 </code>
-To build the docbook in the **master branch**, additional package ''publican'' is required.
+===== Building a DocBook Manual =====
+==== MantisBT 1.3 and later ====
-===== Building a DocBook Manual =====
+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.