## User Manual in DocBook/XML

Our Manual is written in DocBook and can convert to other formats like HTML or CHM.

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

### 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 too!

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

- Own build system which based on Java and Saxon.

### Own build system which based on Java and Saxon

Our own 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`
  Creates the HTML files under the `html` subdirectory at the `build` directory.
`build.bat htmlhelp`
  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 replace the `docbook.dtd` url automatically and do some other works too.

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 to the file:

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