Convert AsciiDoc to DocBook

Why Convert AsciiDoc to DocBook?

Converting AsciiDoc to DocBook is one of the most natural and well-supported conversion paths in the documentation ecosystem. In fact, AsciiDoc was originally created by Stuart Rackham specifically as a more human-friendly way to write DocBook content. The Asciidoctor processor includes a native DocBook backend, making this conversion highly reliable with excellent element mapping between the two formats.

DocBook XML is the industry standard for structured technical documentation, used by organizations like Red Hat, the Linux Documentation Project, GNOME, KDE, and many publishers. It provides over 400 semantic XML elements that precisely describe document structure -- from books and chapters to programlistings and admonitions. By converting AsciiDoc to DocBook, you gain access to DocBook's powerful XSLT-based publishing pipeline, which can produce HTML, PDF (via XSL-FO), EPUB, man pages, and other formats with professional typographic quality.

The AsciiDoc-to-DocBook workflow is used extensively in enterprise documentation. Red Hat uses Asciidoctor to write content in AsciiDoc and then converts to DocBook for their publishing pipeline. This approach combines the ease of writing in AsciiDoc with the power of DocBook's structured output capabilities. The conversion preserves document semantics: AsciiDoc headings become DocBook section/chapter elements, code blocks become programlisting elements, admonitions map to their DocBook equivalents, and tables are converted to DocBook's CALS table model.

For teams already invested in DocBook-based publishing infrastructure, AsciiDoc serves as an excellent authoring frontend. Writers create content in readable AsciiDoc markup, which is then converted to DocBook XML for processing through existing XSLT stylesheets, validation pipelines, and content management systems. This eliminates the pain of writing raw XML while preserving full compatibility with DocBook toolchains.

Key Benefits of Converting AsciiDoc to DocBook:

• Natural Mapping: AsciiDoc was designed to produce DocBook output
• Publishing Pipeline: Access DocBook's XSLT-based multi-format output
• Schema Validation: DocBook XML can be validated against RELAX NG schema
• Enterprise Compatibility: Integrates with existing DocBook workflows
• Semantic Markup: Content gains precise semantic XML structure
• Professional Publishing: Produce publication-quality books and manuals
• Authoring Ease: Write in simple AsciiDoc, publish via DocBook

Practical Examples

Example 1: Book Structure Conversion

Input AsciiDoc file (handbook.adoc):

= Developer Handbook
Author Name
:doctype: book
:toc:

== Chapter 1: Setup

=== Prerequisites

You need *Java 17* and _Maven 3.8+_.

TIP: Use SDKMAN to manage Java versions.

Output DocBook XML (handbook.xml):

<?xml version="1.0" encoding="UTF-8"?>
<book xmlns="http://docbook.org/ns/docbook"
      version="5.0">
  <info>
    <title>Developer Handbook</title>
    <author><personname>Author Name</personname></author>
  </info>
  <chapter xml:id="chapter-1-setup">
    <title>Chapter 1: Setup</title>
    <section xml:id="prerequisites">
      <title>Prerequisites</title>
      <para>You need <emphasis role="bold">Java 17</emphasis>
        and <emphasis>Maven 3.8+</emphasis>.</para>
      <tip><para>Use SDKMAN to manage Java versions.</para></tip>
    </section>
  </chapter>
</book>

Example 2: Code Listing with Callouts

Input AsciiDoc file (api-guide.adoc):

== REST Controller

[source,java]
----
@RestController
@RequestMapping("/api")
public class UserController {
    @GetMapping("/users")
    public List<User> getUsers() {
        return userService.findAll();
    }
}
----

WARNING: Validate all input parameters.

Output DocBook XML:

<section xml:id="rest-controller">
  <title>REST Controller</title>
  <programlisting language="java">
@RestController
@RequestMapping("/api")
public class UserController {
    @GetMapping("/users")
    public List&lt;User&gt; getUsers() {
        return userService.findAll();
    }
}
  </programlisting>
  <warning>
    <para>Validate all input parameters.</para>
  </warning>
</section>

Example 3: Table and Cross-Reference

Input AsciiDoc file (reference.adoc):

[[config-table]]
.Configuration Options
|===
| Property | Type | Default
| timeout | Integer | 30
| retries | Integer | 3
|===

See <<config-table>> for all options.

Output DocBook XML:

<table xml:id="config-table">
  <title>Configuration Options</title>
  <tgroup cols="3">
    <thead>
      <row>
        <entry>Property</entry>
        <entry>Type</entry>
        <entry>Default</entry>
      </row>
    </thead>
    <tbody>
      <row><entry>timeout</entry><entry>Integer</entry><entry>30</entry></row>
      <row><entry>retries</entry><entry>Integer</entry><entry>3</entry></row>
    </tbody>
  </tgroup>
</table>
<para>See <xref linkend="config-table"/> for all options.</para>

Frequently Asked Questions (FAQ)

Q: What is DocBook?

A: DocBook is a semantic XML markup language for technical documentation, maintained by OASIS (Organization for the Advancement of Structured Information Standards). It provides over 400 XML elements for describing the structure and content of books, articles, and reference pages. DocBook content is transformed into presentation formats (HTML, PDF, EPUB) using XSLT stylesheets.

Q: Why was AsciiDoc created as a DocBook frontend?

A: Stuart Rackham created AsciiDoc in 2002 because writing raw DocBook XML was extremely tedious and error-prone. AsciiDoc provides the same semantic expressiveness as DocBook but in a human-readable plain text format. This allows writers to focus on content rather than XML tags, while still producing valid DocBook output for publishing.

Q: Does Asciidoctor have a native DocBook backend?

A: Yes, Asciidoctor includes a built-in DocBook 5 backend. You can convert AsciiDoc to DocBook using the command: asciidoctor -b docbook5 document.adoc. This produces a valid DocBook 5 XML file that can be processed by any DocBook toolchain (DocBook XSL stylesheets, xmlto, dblatex, etc.).

Q: Which version of DocBook is produced?

A: Asciidoctor's default DocBook backend produces DocBook 5.x XML, which uses XML namespaces and RELAX NG validation. DocBook 5 is the current OASIS standard. If you need DocBook 4.5 (the older DTD-based version), some tools offer a DocBook 4.5 output option, though DocBook 5 is recommended.

Q: How are AsciiDoc admonitions mapped to DocBook?

A: AsciiDoc admonitions have a direct one-to-one mapping to DocBook admonition elements: NOTE becomes <note>, TIP becomes <tip>, WARNING becomes <warning>, CAUTION becomes <caution>, and IMPORTANT becomes <important>. This is one of the most natural element mappings in the conversion.

Q: Can I use DocBook output for professional publishing?

A: Absolutely. DocBook is the standard for professional technical publishing. Organizations like O'Reilly Media, Red Hat, and the Linux Documentation Project use DocBook for producing books and manuals. The DocBook XSL stylesheets can generate high-quality PDF (via Apache FOP or dblatex), HTML, EPUB, and other formats suitable for commercial publication.

Q: What DocBook elements does AsciiDoc not support?

A: While AsciiDoc covers the most commonly used DocBook elements, some specialized elements like <cmdsynopsis>, <funcsynopsis>, <classsynopsis>, detailed <biblioentry> fields, and complex <index> markup require direct DocBook XML or Asciidoctor extensions. For most technical documentation needs, AsciiDoc's coverage is more than sufficient.

Q: Can I process the DocBook output with existing XSLT stylesheets?

A: Yes! The DocBook XML output from AsciiDoc conversion is fully compatible with the standard DocBook XSL stylesheets maintained by Norman Walsh. You can use tools like xsltproc, Saxon, or xmlto to transform the DocBook output into HTML, PDF, man pages, or any other format supported by your DocBook toolchain.