XML & DocBook: Structured Technical Documentation Authoring
XML is short for Extended Markup Language and is a subset of SGML, the Standard Generalized Markup Language. XML is an HTML-like formatting language. Whereas most HTML-related formats developed in the past adopted the "be conservative in what you send and liberal in what you receive" attitude, XML takes the opposite approach--documents should be 100% compatible. This compatibility is known as "well-formedness" of an XML document. To this end, even when the goal is clear, a document is rejected if it does not follow XML specifications to the fullest extent. In terms of practicality, this approach guarantees interoperability in the long run. Unlike HTML, which is the standard groupname for a lot of sub-protocols that are slightly different and not fully interoperable with one another, the strictness of XML ensures compatibility. XML also improves security dramatically, because there is only one way to interpret expressions, a way on which everybody agrees.
DocBook is an XML Document Type Definition or DTD. It is a subset of XML particularly suited for but not limited to the creation of books and papers about computer hardware and software. DocBook is well-known in the Linux community and is used by many publishing companies and open-source development projects. Most tools are developed for the DocBook DTD and are included in most Linux distributions. This allows for sending raw data that can be processed at the receiver's end--wherever applications able to interpret XML directly are available.
The important thing to keep in mind is XML and DocBook let authors focus on content. In that sense, the presence of the word "markup" in the definition of XML is misleading. With XML, authors specify what type of data they are including, such as text explanations, command names, tables or images. How the content is formatted, laid out and displayed should not be their concern. From a single source, the receiver might generate PDF, PS, plain text, HTML and many other representations of the content.
Another advantage is DocBook XML files are written in plain text. Although many editors are available, such as oXygen and XMLmind, advanced DocBook users easily can write the source texts using vim, Emacs or any other text editor.
Before you can convert or process an XML document, it is best to validate it, because documents that do not strictly respect the XML definitions cannot be processed. Validation consists of two parts: the document must be well-formed according to the rules defined in XML, and it must use valid markup that is part of the XML vocabulary.
The libxml package provides a simple validator called xmllint. It points out inconsistencies in opening and closing tags and does a couple of other basic checks. The xmllint tool is an XML validator by default; for checking the DocBook DTD validity you need to give it options. In other words, the standard behavior is to check well-formedness and not the vocabulary being used.
Checking the vocabulary is done using a catalog. Most systems these days have the file /etc/sgml/catalog, which holds pointers to catalogs for different SGML subsets, which in turn hold references to public or system-local vocabularies. The catalog files are read by the XML processing tools. A common way of processing is to use an XSL processor, which converts the XML file into formatted output. XSL is the abbreviation of Extensible Stylesheet Language, a way of expressing XML stylesheets. Included in the XSL language is the XSL-FO language, for creating Formatted Objects. XSL Transformations (XSLT) are applied by the XSLT processor on the XML file to rearrange the content of an XML file or to convert it into intermediate formatting objects called FO-files. Finally, an XSL-FO processor converts the FO-files into PostScript and PDF output formats. An overview of how these processes are related is illustrated in Figure 1.
DocBook XML source is fed to the XSLT processor together with the XML DTD, XML catalog and XSLT stylesheet. From this combination, the XSLT processor makes either HTML, which can be converted to TXT or PDB, or XSL-formatted objects, which can be converted to PDF or PS by using FOP, discussed below.
Functionality is provided by, among others, the xsltproc and FOP tools, part of the libxslt and FOP packages, respectively. The libxslt library that provides the xsltproc tool originally was developed as part of the GNOME project, but it operates independently of the GNOME desktop. FOP, the formatted objects processor, is a Java application that can generate, among other formats, PDF, PS, SVG and TXT files. FOP is part of the Apache XML Project. Other popular XSLT processors are Xalan, from the Apache XML project, and Saxon, by the author of the XSLT Reference.
For those who don't want to bother with the intricate and sometimes confusing procedures of XSLT and XSL-FO, other tools, such as docbook-utils and xmlto, are available. The xmlto command applies an XSL stylesheet to an XML document. Docbook-utils provide commands such as db2html, db2pdf and db2ps for easy conversion of XML. Additionally, you can use on-line validators such as Saqib Ali's HTML/XHTML/DocBook XML validator.
Below is a summary of the benefits of using xsltproc and fop tools instead of other tools:
xsltproc and fop are the latest generation of tools to use XSL as opposed to DSSSL (Document Style Semantics and Specification Language). Although the DSSSL-based tools also work with non-XML DocBook--for instance, the DocBook SGML specification--they are not 100% compatible with DocBook XML.
Conversions using the XSL method and xsltproc are more flexible. xsltproc is the fastest processor and is installed by default on many systems.
xsltproc is easier to customize that are other validation tools.
fop is the only freeware XSL-FO processor.
The stylesheets are independent of the XSL processor, and in turn, the XSL-FO processor is independent of the XSL processor.
Editorial Advisory Panel
Thank you to our 2014 Editorial Advisors!
- Jeff Parent
- Brad Baillio
- Nick Baronian
- Steve Case
- Chadalavada Kalyana
- Caleb Cullen
- Keir Davis
- Michael Eager
- Nick Faltys
- Dennis Frey
- Philip Jacob
- Jay Kruizenga
- Steve Marquez
- Dave McAllister
- Craig Oda
- Mike Roberts
- Chris Stark
- Patrick Swartz
- David Lynch
- Alicia Gibb
- Thomas Quinlan
- Carson McDonald
- Kristen Shoemaker
- Charnell Luchich
- James Walker
- Victor Gregorio
- Hari Boukis
- Brian Conner
- David Lane