How to write with Docbook

There are more ways to read documentation, technical or otherwise, than ever before. Bodies of work appear as websites and ebooks and PDF documents on computer screens and small and medium-sized hand-held devices, plain text transcripts attached to videos, tooltips, interactive tutorials, Linux "man" pages, and even on paper. With so many potential avenues for content delivery, there's an advantage to writing the source text in a way that makes it easy to translate it from one format to another. That's where Docbook comes in.

Docbook XML is a verbose markup language, allowing text to be extensively tagged and classified, which in turn ensures that the context of writing is preserved across transformation. Docbook isn't software, nor even a markup language. It's a schema, which means it's a set of rules for writing XML using specific markup tags.

Like Markdown or HTML, you can write Docbook using any text editor, and then process it using a software toolchain that parses and converts the text into any other format, including PDF, EPUB, HTML, DOC, ODT, and more. There are several good converters, so you don't need to know much about XML to write in Docbook.

Intuitive Docbook

When you write Docbook, you write as normal with added XML tags. The tags are self-descriptive, so they're easy to remember once you know what they are. Logically, a book starts with the <book> tag, and an article starts with the <article> tag.

The <section> tag provides logical breaks and a <title> produces a subheading for that section. The <para> tag indicates a paragraph.

Here's a complete example of a sample Docbook document:

<article>
 <info>
 <title>My first docbook document</title>
 </info>

 <section id="intro">
 <title>Introduction</title>
 <para>Docbook is an XML schema.</para>
 </section>

 <section id="content">
 <title>My content</title>
 <para>You can use Docbook to markup your writing.</para>
 <para>Docbook can be transformed into other formats of text.</para>
 </section>

 <section id="conclusion">
 <title>Conclusion</title>
 <para>In conclusion, Docbook is simple.</para>
 </section>
</article>

Each tag you use must be closed after the element it is marking. The subtitle My content, for example, starts with <title> and ends with </title>. Each paragraph opens with <para> and closes with </para>. A title doesn't include a paragraph, and a paragraph doesn't include a title. Instead, they exist as separate block elements.

Each section, however, encompasses other elements, including a title and some number of paragraphs.

It's easy to forget to close elements in Docbook because many writing formats don't require closure. In an office application, a preceding section is closed and a new one is opened when you create a new subtitle. A paragraph is closed when you press Return or Enter on your keyboard. In other words, the structure of a document is implied by its style.

Docbook doesn't natively have a style, though, and so you must declare its structure explicitly through tags. It's extra work up front, but in the end you'll have created a document that leaves nothing about its structure to interpretation. Sections stay together, paragraphs stay separate, titles are clearly indicated, and so on.

A good text editor has plugins to help with syntax. Pulsar, Emacs, VS Code, VSCodium, Vim, and many others have XML extensions that either highlight errors or automatically close tags for you.

Transforming text with Pandoc

Docbook is expected to serve as the source code of your documentation. After you've written something in Docbook, you can transform it into whatever format you want to deliver to your readers. The intent is that your documentation will require no changes to fit each format. From one source, you can create HTML for a website, a PDF for a printer, an EPUB for e-readers, and so on. You can change stylesheets to accommodate your target format, but the source code stays the same.

Technically, you need XML schemas and XSL stylesheets to transform Docbook XML into another format. Practically though, the Docbook toolchain is flexible. You can download Docbook stylesheets from Docbook.org, or you can use Pandoc, which has its own internal stylesheets.

Here's an example of transforming Docbook XML to HTML using Pandoc:

$ pandoc file.xml --from docbook --to html --output file.html

For other formats, change the --to option with the format you want, such as pdf, epub3, odt, docx, or plain for plain text. Use pandoc --list-output-formats to see a complete list of output formats.

Transforming text with XSL

If you want to maintain an XML workflow, you can use the extensible stylesheet language (XSL) instead. A set of default stylesheets are available from Docbook's GitHub repository. You can download just the ones you need, or an archive of all of them.

Save the stylesheets on your system, and then use the xsltproc command to parse your XML source using the stylesheet of your choice. In this example, I've saved the XSL in my working directory, and I use it to transform XML to HTML:

$ xsltproc ./docbook-xsl-snapshot/html/docbook.xsl test.xml > test.html

HTML makes using XSL look easy, but not all formats produce such quick results. Using XSL to output to PDF, for example, takes some extra steps. XSL is just a transformation language, so it can't produce a PDF directly. Instead, it can write data to an FO file, which you can convert to PDF using a PDF writer. A common one is Apache FOP:

$ xsltproc ./docbook-xsl-snapshot/fo/docbook.xsl test.xml > test.fo
$ fop test.fo test.pdf

Choosing an XML processor

Pandoc eliminates the requirement for extra processing, but the workflow isn't as easily customized either. If you intend to create elaborate custom stylesheets for output, then XSL is an important and powerful tool (with a steep learning curve). Otherwise, Pandoc or simple converters like xmlto make the conversion process easy.

Learning new tags

You've seen most of the essential Docbook tags in this article:

• <article> and <book> to define the structure of your work
• <section> (for articles and chapters) and <chapter> (for books) define break points for your readers
• <title> creates titles
• <para> creates paragraphs

Beyond those, there are many more tags available in Docbook. In fact, the intimidating number of tags in Docbook is widely considered one of its strengths. Docbook excels at specificity, which is exactly why it makes such a good source language. I keep a copy of The Docbook Guide on my desk for quick reference. Until you get your own copy, you can use the online version at tdg.docbook.org. It lists all the tags in the Docbook namespace, identifies when each tag is legal to use (for instance, you can't open a <book> within a <para> because books contain paragraphs, not the other way round), and provides at least one working example for each tag.

The number of tags can seem overwhelming at first. I learned them in "reverse." That is, I didn't try to memorize all the tags before I started writing in Docbook. Instead, I started writing and every time I felt compelled to make a word bold or italics or quoted, I looked at the available tags to learn something specific to the interface I was describing. There are tags for code input, code output, key presses, icons, labels, buttons, menus, and more.

It might surprise you at how refreshing it is to tag keywords by what they represent instead of just bold or italic. Consider this passage written in Markdown:

Click **System** to continue.

Is System a button? A menu? A key on a specialized hardware interface? A hyperlink in text? Formats like Markdown don't provide that extra context.

Here's the same passage written in Docbook, assuming that System is a button in a GUI interface:

<para>Click <guibutton>System</guibutton> to continue.</para>

Imagining that System is instead a menu in a GUI interface, here's another possible version:

<para>Click <guimenu>System</guimenu> to continue.</para>

Docbook doesn't have a tag for everything, but it has a tag for most conventions of computer interfaces, because that's what it's designed for. Because Docbook provides that metadata, you can build semantic awareness into your delivery method. It may not matter whether a bold word is a button or a menu when reading a document on a computer screen with accompanying screenshots that make the context obvious, but it could be useful to add text based on tags for users who must use your documentation without images.

Semantic awareness can help computers interpret your documentation, too. A screen reader for blind users could be programmed to read certain internal tags, or an interactive tutorial could render images or icons based on tags. Without semantic markup, mobile phones wouldn't be able to reliably differentiate a phone number from a postal code, rendering click-to-dial interfaces useless. Semantic markup adds context to your documentation, and makes no assumption about how your documentation is going to be consumed.

Docbook for technical writers

Technical documentation is an endeavor toward precision. When you write about technology, you're explaining a complex task in a way readers can comprehend. Using Docbook can help you describe technology explicitly and clearly, with plenty of metadata about the information you're conveying.