DocBook Install mini-HOWTO: DocBook 5 tools and alternatives

Updated November 2026

You no longer have to hunt down five separate packages and set SGML_CATALOG_FILES to process DocBook. One package install gives you a working DocBook 5 XML toolchain that can produce HTML, PDF and man pages. This page sets it up, then compares DocBook with the lighter tools most projects now choose: Asciidoctor, Markdown with Pandoc, Sphinx and MkDocs.

The classic DocBook Install mini-HOWTO (2002) is kept by the LDP at tldp.org. It described DocBook SGML with OpenJade and DSSSL stylesheets. That toolchain is obsolete. Use XML and XSLT, as below.

Where DocBook stands

DocBook is an XML vocabulary for technical books and articles. You mark up meaning (<command>, <filename>, <procedure>), and stylesheets decide the look. The OASIS technical committee that maintained it for many years closed in September 2024. The schemas and stylesheets are still published at docbook.org.

There are two stylesheet families:

Install the toolchain

# Debian 13, Ubuntu
sudo apt install xsltproc docbook-xsl-ns docbook5-xml jing libxml2-utils fop

# Fedora
sudo dnf install libxslt docbook5-style-xsl docbook5-schemas fop

docbook-xsl-ns is the namespace-aware stylesheet set for DocBook 5. (Plain docbook-xsl is for DocBook 4.) The stylesheets are installed here:

The examples below use the Debian path in a shell variable, so on Fedora you change one line:

XSL=/usr/share/xml/docbook/stylesheet/docbook-xsl-ns
# Fedora: XSL=/usr/share/sgml/docbook/xsl-ns-stylesheets

A minimal DocBook 5 article

Save this as guide.xml. The xmlns and version="5.0" attributes are what make it DocBook 5:

<?xml version="1.0" encoding="UTF-8"?>
<article xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
  <info>
    <title>Backing up with rsync</title>
    <author><personname>Ada Lovelace</personname></author>
  </info>
  <section>
    <title>Copy your home directory</title>
    <para>Run <command>rsync</command> with archive mode:</para>
    <screen>rsync -a ~/ /mnt/backup/home/</screen>
    <note><para>A trailing slash on the source copies its contents.</para></note>
  </section>
</article>

Validate it

DocBook 5 is defined in RELAX NG. Validate before you build, because stylesheets quietly drop elements they do not expect:

jing /usr/share/xml/docbook/schema/rng/5.0/docbook.rng guide.xml

No output means the document is valid. Errors come with line numbers. Fedora does not package jing. There, use xmllint --noout --relaxng /usr/share/xml/docbook5/schema/rng/5.1/docbook.rng guide.xml instead. Debian packages the 5.0 schema and Fedora packages 5.1. Both are fine for everyday documents. xmllint --noout guide.xml (from libxml2) checks that the file is at least well-formed XML.

Build HTML, PDF and man pages

# One HTML page
xsltproc --nonet --xinclude -o guide.html "$XSL/html/docbook.xsl" guide.xml

# HTML5, split into one file per section, in out/
xsltproc --nonet --xinclude --stringparam base.dir out/ \
    "$XSL/xhtml5/chunk.xsl" guide.xml

# PDF through XSL-FO and Apache FOP
xsltproc --nonet --xinclude -o guide.fo "$XSL/fo/docbook.xsl" guide.xml
fop -fo guide.fo -pdf guide.pdf

# A man page (the document must be a refentry)
xsltproc --nonet --xinclude "$XSL/manpages/docbook.xsl" mytool.xml

--nonet stops xsltproc from downloading files from the internet. Everything comes from the local catalog, so builds are fast and work offline. --xinclude lets you split a book into one file per chapter with <xi:include href="ch01.xml"/>, after you declare xmlns:xi="http://www.w3.org/2001/XInclude" on the root element. Parameters such as --stringparam html.stylesheet style.css customize the output.

With xslTNG instead

Download the release zip from the xslTNG project. It contains a runnable jar, the libraries it needs (Saxon included), and a bin/docbook wrapper script. After you unzip it, a run looks like this:

java -jar docbook-xslTNG-2.7.1/libs/docbook-xslTNG-2.7.1.jar guide.xml -o:guide.html

Change the version number to match the release you downloaded (2.7.1 at the time of writing). The output is modern HTML5. For PDF, xslTNG uses CSS print stylesheets and a CSS paged-media processor instead of FOP.

The lighter alternatives

Most new Linux projects do not write raw XML. These tools use plain-text markup that is easy to write and review in Git:

Documentation toolchains compared (versions as of November 2026)
ToolSource formatGood forDebian 13 package
DocBook XSLDocBook XMLlong books, strict structure, many outputsdocbook-xsl-ns
Asciidoctor 2.0AsciiDocmanuals and man pages with rich markupasciidoctor
Pandoc 3.13Markdown (and many others)converting between formatspandoc (3.1)
Sphinx 9reStructuredText or Markdown (MyST)large project docs with cross-references and API docspython3-sphinx (8.1)
MkDocs 1.6Markdownsmall project websitesmkdocs

Asciidoctor

AsciiDoc reads like plain text but has everything DocBook has: admonitions, cross-references, includes and tables. Asciidoctor can even write DocBook 5.0 XML for an existing DocBook pipeline:

asciidoctor guide.adoc                 # guide.html
asciidoctor -b docbook guide.adoc      # guide.xml (DocBook 5.0)
asciidoctor -b manpage mytool.adoc     # mytool.1

For a man page, the document title must be the program name with a section number, such as = mytool(1), with :doctype: manpage in the header. The first section must be == Name, holding one line like mytool - back up files. PDF output comes from the separate Asciidoctor PDF project.

Markdown with Pandoc

pandoc -s --toc -o guide.html guide.md
pandoc -s -t docbook5 -o guide.xml guide.md
pandoc -s -t man -o mytool.1 mytool.md
pandoc -o guide.pdf guide.md           # needs a LaTeX install (pdflatex by default)

Pandoc picks the output format from the file extension unless you give -t. -s makes a complete standalone document, not a fragment. --toc adds a table of contents, which only works together with -s.

Sphinx

sphinx-quickstart docs                 # creates docs/conf.py and index
sphinx-build -M html docs docs/_build

Sphinx uses reStructuredText by default. To write Markdown, install MyST-Parser and add extensions = ['myst_parser'] to conf.py. The Linux kernel's own documentation is built with Sphinx from reStructuredText (make htmldocs).

MkDocs

mkdocs new my-docs && cd my-docs      # creates mkdocs.yml and docs/index.md
mkdocs serve                           # preview at http://127.0.0.1:8000/
mkdocs build                           # static site in site/

The only required setting in mkdocs.yml is site_name.

Which one should you use?

Whatever you pick, keep the sources in Git next to the code and build them in CI, so broken markup is caught before release.

Common problems

For how to write good documentation, whatever the format, see the guide to writing Linux documentation.

Sources