## User Manual in DocBook/XML

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

### Useful DocBook resources:

- Official DocBook homepage
- DocBook Wiki

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

- NewbieDoc DocBook guide
- Creating HTML help from DocBook
- Customising HTML output with DSSL
- Customising print formats with DSSL
- DocBook XSL: The Complete Guide

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:

- The hard way: `libxml` and `xsltproc`

  - Good instructions
    Read ch 3. about how to install Windows environment. Note that only libxml and DocBook DTD are needed for creating HTML documentation.
  - libxml download

- Easier with complete command-line environment:

  - eDE which is easy to setup environment for DocBook, and its GPL.

- Cygwin contains needed tools:

  - Long manual for cygwin and XML
  - Shorter and easier manual for cygwin and docbook

- Our preferred build system based on Java and Saxon.

### Our preferred build system is based on Java and Saxon

Our preferred build system uses the following tools:

- Java Runtime Environment
- Saxon
- DocBook DTD
- XSL StyleSheets
- HTML Help Compiler

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`.