XML & DocBook: Structured Technical Documentation Authoring

An introduction to XML and DocBook: what is it and why should I learn yet another data format?

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.

XML Fundamentals

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.

Figure 1. Simplified DocBook Publishing Model

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.



Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Thanks a trillion!!

Anonymous's picture

Thanks a lot... This is indeed a great documentation... helped me a lot ... !!!!

Sample code won't compile! ;-)

thundt's picture

The example in Listing 1 has an error: It is missing the </author> tag.


Red-3's picture

I had to laugh (out loud and for a very long time) when I read this statement half-way through this article:

"General Guidelines for Writing Content

If you are an author, it is okay to skim or skip the above technical explanations..."

The author then goes on to give advice on how to write a good, well structured document. I would hate to be an author, having gone through all the technical explanations, only to read that it was okay to "skim or skip" the stuff I had already trawled through for half an hour!
Surely a statement like this would have been much more useful at the start of the document...

Oh the mindset of the developer - details first, usability second. ;)
Nice one!

Re: XML & DocBook: Structured Technical Documentation Authoring

Anonymous's picture

Does anyone know a good Docbook editor. As far as I am concern, it is not obvious to write a big document under vim :)

The one I know:
Conglomerate : a gnome XML (Docbook) editor
Butterfly : a java XML editor
Jaxe : another java XML editor

The first is the best...
Any other ?

Re: XML & DocBook: Structured Technical Documentation Authoring

Anonymous's picture

XML Mind is a nice and easy WYSIWYG editor.

Re: XML & DocBook: Structured Technical Documentation Authoring

Anonymous's picture

Re: XML & DocBook: Structured Technical Documentation Authoring

Anonymous's picture

XML is Extensible Markup Language, not Extended Markup Language.


Need for a stylesheet catalogue

Anonymous's picture

Thanks for the great howto.

I have used docbook a little and I always get annoyed with the rather plain results of the default stylesheets. I see docbook written material in books and web sites that look good but I do not have the time to learn all the stylesheet stuff to set up my own.

Is there a catalogue of stylesheets/css for docbook somewhere. If not I think it would be a good idea. I think that more people (myself included) would make more use of docbook if it was easier to get nice looking final format results.


Re: Need for a stylesheet catalogue

Anonymous's picture

Whilst I generally don't get on with LaTeX too well, I do find that it produces great looking output. Therefore, I tend to convert DocBook files to LaTeX (you can get XSL files which will do this) and then use either latex itself or pdflatex to convert to a printable format. For the XSL files, start at http://db2latex.sourceforge.net/

Re: XML & DocBook: Structured Technical Documentation Authoring

Anonymous's picture

Does anyone know of an XML format for storing or creating exams? I am interested in online and paper tests, and I am beginning to believe that XML would be a natural format to store tests in. Is there already a standard defined for this usage?

Re: XML & DocBook: Structured Technical Documentation Authoring

Anonymous's picture

For assessment/test information in XML you might be in interested in the "IMS Question & Test Interoperability Specification" from the IMS Global Learning Consortium


Re: XML & DocBook: Structured Technical Documentation Authoring

Anonymous's picture

This might be one of those situations where creating your own DTD for a test would be applicable. Then write your exams based on that DTD. I am pretty sure you can then use the same xml/xsl tools to generate your .html, .ps, .pdf, etc. files.

send me a linux project

kuldeep's picture

pleaz send me a linux project about any new topic