From the Source

Documentation for standard software tools can be written using the simplest resources. For example, the ReadMe files included in most source code packages can be written with the use of any text editor. In recent years, developers have also used the Markdown format [1], which offers bulleted lists, listings, and web links and is formatted neatly by code hosting provider GitHub.

However, users of powerful software suites, particularly commercial software, need and expect genuine manuals. The DocBook [2] format, which exists in SGML and XML flavors, satisfies this need, prevailing over more lightweight competitors, such as reStructuredText [3].

DocBook provides everything a developer needs for a professional manual – from tables of content and tables of figures to cross references and indexes. DocBook has also established itself as a kind of lingua franca for technical documentation. Free software can handle this language just as well as proprietary applications, such as Adobe FrameMaker.

If you use DocBook XML, you do not need to worry about whether it will still be possible to read and maintain your documents in a few years' time. Of course, this assumes that you are not fazed by working with XML source code, although this work can be made easier by choosing a suitable editor.

On Board

The DocBook schemas and a collection of XSL style sheets for converting into HTML and other formats are parts of the package scope for virtually all Linux distributions. Using them, it is possible to implement single-source publishing workflows (i.e., create man pages and info, HTML, PDF, and EPUB documents from the same source code).

A practical publishing system, however, needs to offer more – especially if multiple users need to collaborate. It needs to specify where the numerous XML, image, and other files from the documentation project end up; automate the process of building output files; and make sure the cross references actually work. Additionally, a good system needs to create the framework for a new documentation project in a single step.

Test Site

Those who don't fancy programming all that themselves can draw on the work of others who have published the source code for their software. The SUSE Linux documentation team has developed the DocBook Authoring and Publishing Suite (DAPS) [4] for in-house projects and openSUSE. Red Hat, which runs projects like Fedora or oVirt, meets similar requirements with Publican [5]. The third candidate is the group of programs by the Gnome project centered on the Yelp [6] help browser.

DAPS

The openSUSE and SUSE Linux Enterprise manuals are created using DAPS (Figure 1), so you can simply install the suite on these distributions from the package repository. The installation guide [7] lists the required packages for other flavors of Linux. Thanks to Git, the code for the suite ends up on the hard disk and can be run directly in the cloned directory with just a few tweaks.

Figure 1: The official SUSE documentation in WebHelp format is created using the DAPs.

DAPS follows the usual DocBook recipe and converts the DocBook XML into other formats such as (X)HTML, HTML Help, man page, EPUB, or WebHelp using xsltproc and the DocBook stylesheets.

WebHelp is included in the latest DocBook stylesheets, offering an expandable navigation bar and presenting SLES documentation clearly on the web. Another ability is to convert to XSL Formatting Objects (XSL-FO), which serve as raw material for producing PDFs using the Apache Formatting Objects Processor (FOP) [8]. Bash scripts and Makefiles glue the components together.

The central command is daps; it has zillions of options and parameters, from checks, through transformations, to packaging options. The daps-init command creates a new document; Figure 2 shows the results.

Figure 2: The daps-init command creates the directory structure for a new documentation project.

The DC file contains the key settings for the publishing project; the DocBook XML file is in the XML directory. It can also be used as a main file for unitized XML and, for example, integrate chapters from separate files. The images directory shows the variety of formats that DAPS processes: the software also automatically generates output versions for Dia, Xfig and SVG when publishing.

While typing, authors can make use of suitable extensions, as required, for the Emacs, Vim, and jEdit editors. DAPs also supports authors with various options that validate the DocBook XML, check cross references and web links, and find required or orphaned files. The spellchecker is not fazed by the XML tags thanks to Aspell.

The suite also fulfills advanced documentation requirements by creating several versions of a document using conditional text and profiling to replace product names or exclude sections and features that only apply to a specific product version. It is also possible to add comments and draft watermarks for proofreaders and translators.

As well as the output formats mentioned, DAPS also creates tarballs, which contain either the XML source code or HTML Help. On request, it also packages the documentation for RPMs or the Gnome and KDE help systems.