## 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 install eDE, because it install all required tools (except of Java).

The batch files are located at the `build` subdirectory at the `Manual` directory. The main file ist `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`.

Note: If you use a other path than `C:\docbook\xsl` for the XSL StyleSheets you must change the files `build_html.xsl` and `build_htmlhelp.xsl`:

build_html.xsl:

    <xsl:import href="file:/C:/docbook/xsl/html/chunk.xsl"/>

build_htmlhelp.xsl:

    <xsl:import href="file:/C:/docbook/xsl/htmlhelp/htmlhelp.xsl"/>

### Docbook support in SourceForge

SourceForge has Docbook tools installed, and they can be used from shell server. Tools we are interested in:

- `docbook2html`
- `docbook2pdf`
- `docbook2txt`
- (`docbook2rtf`)

#### Generating HTML documentation

`Manual-html.dsl` file is a stylesheet file that defines rules for generating HTML. It forces index creation, adding navigation links, CSS stylesheet etc. File contains comments for settings so they are not repeated here.

To generate HTML documentation in SF.net shell, copy all XML files, stylesheet file and subdirectories to shell server. Then in directory which contains XML files, type:

    docbook2html -d Manual-html.dsl WinMerge_help.xml

Note: Seems that Sourceforge.net has blocked access to outside world from shell, so to generate docs one needs to replace `docbook.dtd` location in `WinMerge_help.xml` with local path. Replace url in second line `"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"` with valid path. At the moment it is:

    "/usr/share/sgml/docbook/sgml-dtd-4.2-1.0-24/docbook.dtd"

#### Own build script

We have an own build script, which replaces the `docbook.dtd` url automatically making it easier to build manual.

The `build.sh` script file is located at the `build` subdirectory at the `Manual` directory. But before you can use it at the shell server, you must give execute rights for it:

    chmod +x build.sh

Now you can call the script file (from the `build` directory):

`./build.sh html`
  Creates the HTML files under the `html` subdirectory at the `build` directory.
`./build.sh pdf`
  Creates the PDF file under the `pdf` subdirectory at the `build` directory.
`./build.sh txt`
  Creates the TXT file under the `txt` subdirectory at the `build` directory.
`./build.sh`
  Is the same like `./build.sh html`.

### Postprocessing HTML

Unfortunately some DocBook tools generate quite a messy HTML. This is especially true for DSSSL-stylesheet based tools. When using such tools it is strongly recommended to run some tidying tool before releasing/uploading HTML manual.

One good and free tool for tidying HTML is HTML tidy.

To use HTML Tidy, open command prompt, go to folder where generated HTML files are and give a command:
`tidy -m file.html`.
Repeat for all HTML files. Or create a batch file to tidy them all. This of course assumes that HTML tidy is added to $PATH so it can be found when running from commandline.