Generate DocBook from AsciiDoc

DocBook 5.0 converter

Asciidoctor can produce DocBook 5.0 XML output. There’s a corresponding DocBook element for each AsciiDoc element.

docbook: The DocBook 5.0 converter generates DocBook 5.0 XML. To use the DocBook converter, assign docbook or docbook5 to the backend option.

Generate DocBook with the docbook converter

To follow along with the steps below, use your own AsciiDoc file or copy the contents of Example 1 into a new plain text file.

Example 1. my-document.adoc

= The Dangers of Wolpertingers
:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger

Don't worry about gumberoos or splintercats.
Something far more fearsome plagues the days, nights, and inbetweens.
Wolpertingers.

== Origins

Wolpertingers are {url-wolpertinger}[ravenous beasts].

Make sure to save the file with the .adoc file extension.
To convert the my-document.adoc document to DocBook 5.0 format, call the processor with the backend flag set to docbook.
```
$ asciidoctor -b docbook my-document.adoc
```

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

$ ls
my-document.adoc  my-document.xml

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

Example 2. XML generated from AsciiDoc

<?xml version="1.0" encoding="UTF-8"?>
<?asciidoc-toc?>
<?asciidoc-numbered?>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info>
<title>The Dangers of Wolpertingers</title>
<date>2020-12-08</date>
</info>
<simpara>Don&#8217;t worry about gumberoos or splintercats.
Something far more fearsome plagues the days, nights, and inbetweens.
Wolpertingers.</simpara>
<section xml:id="_origins">
<title>Origins</title>
<simpara>Wolpertingers are <link xl:href="https://en.wikipedia.org/wiki/Wolpertinger">ravenous beasts</link>.</simpara>
</section>
</article>

On Linux, you can view the DocBook file with Yelp.
```
$ yelp my-document.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.

Example 3. Generate DocBook output from the API

Asciidoctor.convert_file 'my-document.adoc', backend: 'docbook'

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