Publishing systems for DocBook XML
From the Source

© Lead Image © Photosani, Fotolia.com
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
Direct Download
Read full article as PDF:
Price $2.95
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Find SysAdmin Jobs
News
-
The Next Major Release of Elementary OS has Arrived
It's been over a year since the developers of elementary OS released version 6.1 (Jólnir) but they've finally made their latest release (Horus) available with a renewed focus on the user.
-
KDE Plasma 5.27 Beta is Ready for Testing
The latest beta iteration of the KDE Plasma desktop is now available and includes some important additions and fixes.
-
Netrunner OS 23 Is Now Available
The latest version of this Linux distribution is now based on Debian Bullseye and is ready for installation and finally hits the KDE 5.20 branch of the desktop.
-
New Linux Distribution Built for Gamers
With a Gnome desktop that offers different layouts and a custom kernel, PikaOS is a great option for gamers of all types.
-
System76 Beefs Up Popular Pangolin Laptop
The darling of open-source-powered laptops and desktops will soon drop a new AMD Ryzen 7-powered version of their popular Pangolin laptop.
-
Nobara Project Is a Modified Version of Fedora with User-Friendly Fixes
If you're looking for a version of Fedora that includes third-party and proprietary packages, look no further than the Nobara Project.
-
Gnome 44 Now Has a Release Date
Gnome 44 will be officially released on March 22, 2023.
-
Nitrux 2.6 Available with Kernel 6.1 and a Major Change
The developers of Nitrux have officially released version 2.6 of their Linux distribution with plenty of new features to excite users.
-
Vanilla OS Initial Release Is Now Available
A stock GNOME experience with on-demand immutability finally sees its first production release.
-
Critical Linux Vulnerability Found to Impact SMB Servers
A Linux vulnerability with a CVSS score of 10 has been found to affect SMB servers and can lead to remote code execution.