Convert DOCBOOK to ADOC

Why Convert DOCBOOK to ADOC?

Converting DocBook XML to AsciiDoc (ADOC) is a natural migration path for teams looking to modernize their documentation workflows. While DocBook has been the gold standard for structured technical documentation since the 1990s, its verbose XML syntax creates friction for writers and makes collaboration difficult without specialized XML editing tools.

AsciiDoc provides a semantically equivalent alternative to DocBook with a dramatically simpler syntax. In fact, AsciiDoc was designed with DocBook compatibility in mind -- Asciidoctor can generate DocBook output natively, and the element mapping between the two formats is well-defined. This means converting from DocBook to AsciiDoc preserves nearly all structural information.

The conversion is especially valuable for open-source projects that historically used DocBook (like Linux documentation, GNOME, and FreeBSD). Moving to AsciiDoc lowers the barrier for contributors, as writers no longer need XML expertise to contribute documentation. The plain-text format also works seamlessly with Git-based review workflows.

During conversion, DocBook elements like <chapter>, <section>, <para>, <itemizedlist>, and <programlisting> are mapped to their AsciiDoc equivalents. Attributes, cross-references, and metadata are preserved using AsciiDoc's attribute system. Complex DocBook constructs like nested tables or specialized admonitions may require manual review after conversion.

Key Benefits of Converting DOCBOOK to ADOC:

• Simplified Authoring: Replace verbose XML with clean, readable plain-text markup
• Easier Collaboration: Contributors no longer need XML editing tools or expertise
• Git-Friendly: Plain text diffs are meaningful and easy to review
• Round-Trip Capability: Asciidoctor can regenerate DocBook XML when needed
• Modern Tooling: Leverage Asciidoctor's ecosystem, CI/CD integration, and extensions
• Platform Rendering: GitHub and GitLab render ADOC files natively
• Multi-Format Output: Generate HTML, PDF, EPUB, and DocBook from a single source

Practical Examples

Example 1: Chapter with Sections and Lists

Input DocBook XML (chapter.xml):

<chapter xmlns="http://docbook.org/ns/docbook">
  <title>Installation Guide</title>
  <section>
    <title>System Requirements</title>
    <para>Before installing, ensure your system meets
    the following requirements:</para>
    <itemizedlist>
      <listitem><para>Linux kernel 5.4+</para></listitem>
      <listitem><para>4 GB RAM minimum</para></listitem>
      <listitem><para>10 GB free disk space</para></listitem>
    </itemizedlist>
  </section>
</chapter>

Output ADOC file (chapter.adoc):

== Installation Guide

=== System Requirements

Before installing, ensure your system meets
the following requirements:

* Linux kernel 5.4+
* 4 GB RAM minimum
* 10 GB free disk space

Example 2: Code Listing with Callouts

Input DocBook XML (code-example.xml):

<section xmlns="http://docbook.org/ns/docbook">
  <title>Configuration</title>
  <para>Edit the <filename>config.yaml</filename> file:</para>
  <programlisting language="yaml">server:
  host: 0.0.0.0
  port: 8080
database:
  driver: postgresql
  name: myapp</programlisting>
  <note>
    <para>Restart the service after making changes.</para>
  </note>
</section>

Output ADOC file (config.adoc):

=== Configuration

Edit the `config.yaml` file:

[source,yaml]
----
server:
  host: 0.0.0.0
  port: 8080
database:
  driver: postgresql
  name: myapp
----

NOTE: Restart the service after making changes.

Example 3: Table and Cross-References

Input DocBook XML (reference.xml):

<section xmlns="http://docbook.org/ns/docbook">
  <title>Command Reference</title>
  <para>See <xref linkend="tbl-commands"/> for details.</para>
  <table xml:id="tbl-commands">
    <title>Available Commands</title>
    <thead>
      <tr><th>Command</th><th>Description</th></tr>
    </thead>
    <tbody>
      <tr><td>start</td><td>Start the service</td></tr>
      <tr><td>stop</td><td>Stop the service</td></tr>
    </tbody>
  </table>
</section>

Output ADOC file (reference.adoc):

=== Command Reference

See <<tbl-commands>> for details.

[[tbl-commands]]
.Available Commands
|===
|Command |Description

|start |Start the service
|stop |Stop the service
|===

Frequently Asked Questions (FAQ)

Q: What is DocBook format?

A: DocBook is an XML-based semantic markup language designed for creating technical documentation. Originally developed in 1991 by HaL Computer Systems and O'Reilly Media, it is now maintained by OASIS. DocBook provides a comprehensive set of elements for structuring books, articles, manuals, and reference documentation with precise semantic meaning.

Q: Why migrate from DocBook to AsciiDoc?

A: The primary motivation is simplifying the authoring experience. DocBook's verbose XML syntax requires specialized editors and XML knowledge, while AsciiDoc achieves similar semantic richness with clean, readable plain text. Many major projects (including parts of the Linux documentation) have migrated from DocBook to AsciiDoc for this reason.

Q: Is the conversion lossless?

A: AsciiDoc supports the vast majority of DocBook's structural elements, so most content converts cleanly. However, some specialized DocBook elements (like deeply nested tables, custom processing instructions, or domain-specific extensions) may require manual adjustment after conversion. The core structure, text content, and formatting are fully preserved.

Q: Can I convert AsciiDoc back to DocBook?

A: Yes. Asciidoctor has a built-in DocBook backend that generates DocBook 5 XML output. This round-trip capability means you can maintain your documentation in AsciiDoc while still producing DocBook output for toolchains that require it, such as enterprise publishing systems or legacy documentation pipelines.

Q: How are DocBook cross-references handled?

A: DocBook <xref> elements and xml:id attributes are converted to AsciiDoc anchors ([[id]]) and cross-reference macros (<<id>>). Internal links within the document are fully preserved, maintaining the navigational structure of the original DocBook source.

Q: What about DocBook admonitions (note, warning, tip)?

A: DocBook admonitions map directly to AsciiDoc admonition blocks. Elements like <note>, <warning>, <tip>, <caution>, and <important> are converted to their AsciiDoc equivalents (NOTE:, WARNING:, TIP:, CAUTION:, IMPORTANT:), preserving both the type and content of each admonition.

Q: Does DocBook 4 content work with this converter?

A: Yes, the converter handles both DocBook 4 (DTD-based) and DocBook 5 (namespace-based) content. While DocBook 5 uses XML namespaces and RELAX NG schemas, DocBook 4 uses SGML-style DTDs. Both versions are parsed and converted to equivalent AsciiDoc output.

Q: How are DocBook entities and XIncludes handled?

A: XML entities are resolved during parsing, and the expanded text appears in the AsciiDoc output. XInclude directives can be converted to AsciiDoc include directives (include::file.adoc[]), preserving the modular structure of the documentation. Complex entity definitions may need manual review.