65. DocBook

Asciidoctor can produce DocBook 5.0 output. Since the AsciiDoc syntax was designed with DocBook output in mind, the conversion is very good. There’s a corresponding DocBook element for each markup in the AsciiDoc syntax.

To convert the mysample.adoc document to DocBook 5.0 format, call the processor with the backend flag set to docbook.

$ asciidoctor -b docbook mysample.adoc

A new XML document, named mysample.xml, will now be present in the current directory.

$ ls
mysample.adoc  mysample.html  mysample.xml

Here’s a snippet of the XML generated by the DocBook converter.

XML generated from AsciiDoc
<?xml version="1.0" encoding="UTF-8"?>
<article xmlns="http://docbook.org/ns/docbook"
    xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
  <info>
    <title>Hello, AsciiDoc!</title>
    <date>2013-09-03</date>
    <author>
      <personname>
        <firstname>Doc</firstname>
        <surname>Writer</surname>
      </personname>
      <email>doc@example.com</email>
    </author>
    <authorinitials>DW</authorinitials>
  </info>
  <simpara>
    An introduction to <link xl:href="http://asciidoc.org">AsciiDoc</link>.
  </simpara>
  <section xml:id="_first_section">
    <title>First Section</title>
    <itemizedlist>
      <listitem>
        <simpara>item 1</simpara>
      </listitem>
      <listitem>
        <simpara>item 2</simpara>
      </listitem>
    </itemizedlist>
  </section>
</article>

If you’re on Linux, you can view the DocBook file with Yelp.

$ yelp mysample.xml

And of course, if you’re using the Asciidoctor Ruby API, you can generate a DocBook document directly from your application.

Generate DocBook output from the API
Asciidoctor.convert_file 'mysample.adoc', backend: 'docbook'

By default, the docbook converter produces DocBook 5.0 output that is compliant to the DocBook 5.0 specification.

A summary of the differences are as follows:

  • XSD declarations are used on the document root instead of a DTD

  • <info> elements for document info instead of <articleinfo> and <bookinfo>

  • elements that hold the author’s name are wrapped in a <personname> element

  • the id for an element is defined using an xml:id attribute

  • <link> is used for links instead of <ulink>

  • the URL for a link is defined using the xl:href attribute

Refer to What’s new in DocBook v5.0? for more details about how DocBook 5.0 differs from DocBook 4.5.

If you need to output DocBook 4.5, you may find the community-supported DocBook 4.5 Converter useful.

$ asciidoctor -b docbook45 mysample.adoc