Publishing systems for DocBook XML
From the Source
Good software requires detailed documentation. The DocBook Authoring and Publishing Suite, Publican, and Yelp all let you generate a variety of documents – from man pages to eBooks.
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.
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.
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.
Buy this article as PDF
(incl. VAT)
Buy Linux Magazine
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Support Our Work
Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.
News
-
Canonical Bumps LTS Support to 12 years
If you're worried that your Ubuntu LTS release won't be supported long enough to last, Canonical has a surprise for you in the form of 12 years of security coverage.
-
Fedora 40 Beta Released Soon
With the official release of Fedora 40 coming in April, it's almost time to download the beta and see what's new.
-
New Pentesting Distribution to Compete with Kali Linux
SnoopGod is now available for your testing needs
-
Juno Computers Launches Another Linux Laptop
If you're looking for a powerhouse laptop that runs Ubuntu, the Juno Computers Neptune 17 v6 should be on your radar.
-
ZorinOS 17.1 Released, Includes Improved Windows App Support
If you need or desire to run Windows applications on Linux, there's one distribution intent on making that easier for you and its new release further improves that feature.
-
Linux Market Share Surpasses 4% for the First Time
Look out Windows and macOS, Linux is on the rise and has even topped ChromeOS to become the fourth most widely used OS around the globe.
-
KDE’s Plasma 6 Officially Available
KDE’s Plasma 6.0 "Megarelease" has happened, and it's brimming with new features, polish, and performance.
-
Latest Version of Tails Unleashed
Tails 6.0 is based on Debian 12 and includes GNOME 43.
-
KDE Announces New Slimbook V with Plenty of Power and KDE’s Plasma 6
If you're a fan of KDE Plasma, you'll be thrilled to hear they've announced a new Slimbook with an AMD CPU and the latest version of KDE Plasma desktop.
-
Monthly Sponsorship Includes Early Access to elementary OS 8
If you want to get a glimpse of what's in the pipeline for elementary OS 8, just set up a monthly sponsorship to help fund its continued existence.