Our Manual is written in DocBook and can convert to other formats like HTML or CHM.
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:
The hard way: libxml
and xsltproc
Easier with complete command-line environment:
Cygwin contains needed tools too!
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
html
subdirectory at the build
directory.build.bat htmlhelp
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 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
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
.