Thousands of people use Synalyze It! now, many of them every day to work on their binary files. Although there is an online help available, a more comprehensive manual was missing yet.
There are many ways how to create technical documentation. If your primary goal is to produce a PDF file, most word processors are well-suited for the job. However, if you want to target different formats and incorporate other input data, without any doubt DocBook is the best choice.
DocBook is an XML language that allows to tag almost everything that can occur in technical documents. As every good XML language it doesn't mix structure and presentation. So you describe for example a command (<command>ls</command>) as such or a keystroke Cmd-k (<keycombo><keycap>Cmd</keycap><keycap>K</keycap></keycombo>), there's no information how to display them.
The actual presentation is added later in the process so you can be sure it's applied consistently to the whole document. To produce PDF you usually produce an intermediate XSL-FO file that can be processed by formatters like FOP or any of the commercial ones.
Here I'll describe what can be done to produce a documentation that is modular and extensible. There are other ways and tools which can be used but this article just explains what works for me - and could work for you, too. :-)
Btw: Here's the result:
All tools needed can be found at no charge in the net that brought this article to you.
These are the Java packages I use (installed via MacPorts):
They are used later when translating the DocBook file to XSL-FO.
Let's start with a customized title page. In DocBook you describe the title page in an abstract way so the actual contents are written in the main DocBook XML file. Find my titlepage.spec.xml here. This needs to be translated to another XSL file (titlepage.xsl) used later in the process.
xsltproc --output titlepage.xsl /opt/local/share/xsl/docbook-xsl/template/titlepage.xsl \
In my manual I added some files exported from OmniGraffle. However, the SVG output had a minor flaw: even normal text had a font weight of 500 set which makes text bold (400 means "normal"). To fix this I applied a small style sheet to the SVG files OmniGraffle exported (small shell script):
if test $1 -nt $2; then
# file1 is newer than file2
echo Correct $1 to $2
/opt/local/bin/xsltproc --output $2 CorrectFontWeight.xsl $1
Ok, so much for the preparation. The main document is quite simple and looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY app "<application>Synalyze It!</application>">
<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:db="http://docbook.org/ns/docbook" lang="en" version="4.5">
<!-- here comes the address -->
<para>Synalysis makes no warranties…
<imagedata fileref="../SynalyzeIt.png" format="PNG" scale="200">
<para role="tagline">The Official Documentation for &app;</para>
<!-- more chapters here -->
All the chapters are referenced externally. A simple call to xmllint merges all used files to one:
/opt/local/bin/xmllint --nonet --xinclude --output DocumentationInclude.xml Documentation.xml
The second-last step now applies the DocBook stylesheet for XSL-FO output to this file:
java -cp ".:$XALANJAR:$XERCESJAR:$SERIALIZERJAR:$RESOLVERJAR" \
-ENTITYRESOLVER org.apache.xml.resolver.tools.CatalogResolver \
-URIRESOLVER org.apache.xml.resolver.tools.CatalogResolver \
-out Documentation.fo -in $DocumentationInclude.xml -xsl $STYLESHEET
But wait! What is $STYLESHEET? Usually you apply there /opt/local/share/xsl/docbook-xsl/fo/docbook.xsl directly but it makes sense to introduce here a so-called customization layer. This lets you refer to your custom title page style sheet and set some parameters needed by FOP. So STYLESHEET=customization_layer.xsl
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:param name="body.font.family" select="'Palatino,Verdana'"/>
<xsl:param name="title.font.family" select="'Palatino,Verdana'"/>
<xsl:param name="monospace.font.family" select="'Courier,MS Gothic'"/>
<xsl:param name="ulink.show" select="0"/>
<xsl:param name="fop1.extensions" select="1"/>
The fop1.extensions parameter tells FOP to generate a TOC for the output PDF file.
Now we almost made our way to the final PDF file. The only thing that's missing is to ask FOP if it would like to produce our manual:
/opt/local/bin/fop -c ./fop.xconf -fo Documentation.fo -pdf Documentation.pdf
My fop.xconf is just a slightly extended default fop.xconf. In the section used for PDF output I enabled the automatic font search (<auto-detect/>) and referenced a TrueType font collection:
<font embed-url="/Library/Fonts/Palatino.ttc" sub-font="Palatino Italic">
<font-triplet name="Palatino-Roman" style="normal" weight="normal"/>
You see, there's a lot to learn and do to write documentation in DocBook. However, if you mastered these initial steps you're rewarded with a professional manual and a maximum of flexibility for later extensions.