User Manual in DocBook/XML

Our Manual is written in DocBook and we generate HTML and CHM manuals for distributing.

Useful DocBook resources:

Editing manual

The user's manual is XML, so you can use XML editor or your favourite text editor. Note that XML requires document to be well formed, unlike HTML, before it can be processed. So if possible, make sure your DocBook is well formed before submitting document patches.

See these tutorials for editing DocBook:

Note: For screenshots we prefer the PNG format. Only for images (for example icons), where we want transparency, we use the GIF format, since older browsers have problems with transparent PNG images.

Installing conversion tools needed:

Our preferred build system is based on Java and Saxon

Our preferred build system uses the following tools:

The easiest way is to download our manual build tools package v1. The package contains required tools for manual building. Java Runtime (JRE) is the only external requirement. Installing the tools is easy - just unzip the tools package to folder /Docs/Users/Manual/build.

The batch files are also located at the same build subfolder. The main file is build.bat. Paths to the installed tools are written in the configuration.bat file.

build.bat html or build_html.bat
Creates the HTML files under the html subdirectory at the build directory.
build.bat html withads or
build_html.bat withads
Creates the HTML files with adds under the html subdirectory at the build directory.
build.bat htmlhelp or
build_htmlhelp.bat
Creates the CHM file under the htmlhelp subdirectory at the build directory.
build.bat
Is the same like build.bat html.