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
News
-
An All-Snap Version of Ubuntu is In The Works
Along with the standard deb version of the open-source operating system, Canonical will release an-all snap version.
-
Mageia 9 Beta 2 Ready for Testing
The latest beta of the popular Mageia distribution now includes the latest kernel and plenty of updated applications.
-
KDE Plasma 6 Looks to Bring Basic HDR Support
The KWin piece of KDE Plasma now has HDR support and color management geared for the 6.0 release.
-
Bodhi Linux 7.0 Beta Ready for Testing
The latest iteration of the Bohdi Linux distribution is now available for those who want to experience what's in store and for testing purposes.
-
Changes Coming to Ubuntu PPA Usage
The way you manage Personal Package Archives will be changing with the release of Ubuntu 23.10.
-
AlmaLinux 9.2 Now Available for Download
AlmaLinux has been released and provides a free alternative to upstream Red Hat Enterprise Linux.
-
An Immutable Version of Fedora Is Under Consideration
For anyone who's a fan of using immutable versions of Linux, the Fedora team is currently considering adding a new spin called Fedora Onyx.
-
New Release of Br OS Includes ChatGPT Integration
Br OS 23.04 is now available and is geared specifically toward web content creation.
-
Command-Line Only Peropesis 2.1 Available Now
The latest iteration of Peropesis has been released with plenty of updates and introduces new software development tools.
-
TUXEDO Computers Announces InfinityBook Pro 14
With the new generation of their popular InfinityBook Pro 14, TUXEDO upgrades its ultra-mobile, powerful business laptop with some impressive specs.