User Manual in DocBook/XML

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

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:

Installing conversion tools needed:

Own build system which based on Java and Saxon

Our own build system uses the following tools:

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:

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.