Our Manual is written in DocBook and we generate HTML and CHM manuals for distributing.
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.
The hard way: libxml
and xsltproc
Easier with complete command-line environment:
Cygwin contains needed tools:
Our preferred build system based on Java and Saxon.
Our preferred 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
or build_html.bat
html
subdirectory at the build
directory.build.bat html withads
or build_html.bat withads
html
subdirectory at the build
directory.build.bat htmlhelp
or build_htmlhelp.bat
htmlhelp
subdirectory at the build
directory.build.bat
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"/>
SourceForge has Docbook tools installed, and they can be used from shell server. Tools we are interested in:
docbook2html
docbook2pdf
docbook2txt
docbook2rtf
)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"
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
html
subdirectory at the build
directory../build.sh pdf
pdf
subdirectory at the build
directory../build.sh txt
txt
subdirectory at the build
directory../build.sh
./build.sh 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.