Convert AsciiDoc to DocBook

Asciidoctor can produce DocBook 5.0 XML output.

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>2018-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="https://asciidoctor.org">Asciidoctor</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>

On Linux, you can view the DocBook file with Yelp.

$ yelp mysample.xml

The DocBook converter produces 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

If you’re using the Asciidoctor API, you can generate a DocBook document directly from your application.

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