User Tools

  • Logged in as: anonymous (anonymous)
  • Log Out

Site Tools


mantisbt:docbook

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
mantisbt:docbook [2008/03/07 13:10] – Fixed the sample path to the manual vboctormantisbt:docbook [2016/07/03 11:26] (current) – [MantisBT 1.3 and later] added new section's contents dregad
Line 3: Line 3:
 ===== Required Tools ===== ===== 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.+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.
  
-For Debian- or Ubuntu-based Linux distributions, simply install the necessary packages with the following command: 
 <code> <code>
-  $ sudo aptitude install docbook, docbook-dsssl, docbook-slides, docbook-utils, linuxdoc-tools, make, openjade, xmlto+$ sudo apt-get install publican
 </code> </code>
  
-For Fedora-based distrosrun this command instead:+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> <code>
-  su -c 'yum groupinstall "Authoring and Publishing"'+sudo apt-get install docbook docbook-dsssl docbook-slides docbook-utils linuxdoc-tools make openjade xmlto
 </code> </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 ===== ===== 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. 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.
Line 42: Line 91:
   $ make pdf html   $ make pdf html
   $ make INSTALL_DIR=/path/to/install install   $ 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> </code>
mantisbt/docbook.1204913436.txt.gz · Last modified: 2008/10/29 04:32 (external edit)

Driven by DokuWiki