Convert DOCBOOK to ORG

Why Convert DocBook to Org-mode?

Converting DocBook to Org-mode transforms static XML documentation into a dynamic, interactive format that combines documentation, executable code, task management, and outlining in a single file. Org-mode is the Swiss Army knife of plain-text formats, and Emacs users worldwide rely on it for technical writing, research, and knowledge management.

DocBook and Org-mode share a focus on structured, hierarchical documentation. DocBook uses XML elements (chapter, section) to create a document tree, while Org-mode uses asterisk-based headings (*, **, ***) for the same purpose. This structural correspondence makes the conversion natural and preserves the logical organization of your content.

One of Org-mode's most powerful features is Babel, which allows code blocks to be executed directly within the document. When DocBook documentation containing code examples is converted to Org-mode, those code blocks become executable -- readers can run the examples, see the output, and experiment with modifications, turning static documentation into interactive tutorials.

Org-mode also supports export to HTML, LaTeX, PDF, ODT, and even back to DocBook. This means converting your documentation to Org-mode does not lock you into a single format -- instead, it gives you a powerful authoring environment from which you can generate output in any format you need, including the original DocBook XML.

Key Benefits of Converting DocBook to Org-mode:

• Interactive Docs: Code blocks become executable with Org Babel
• Outline Navigation: Fold and expand sections for easy navigation
• Multi-Format Export: Export to HTML, PDF, LaTeX, ODT from a single source
• Task Integration: Add TODO items and deadlines within documentation
• Plain Text: Version-control friendly with excellent Git diffs
• Literate Programming: Mix prose and executable code seamlessly
• Knowledge Base: Build interconnected notes with org-roam or Logseq

Practical Examples

Example 1: Technical Guide with Code

Input DocBook file (guide.xml):

<article xmlns="http://docbook.org/ns/docbook">
  <title>Python Setup Guide</title>
  <section>
    <title>Virtual Environment</title>
    <para>Create an isolated environment:</para>
    <programlisting language="bash">
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt</programlisting>
  </section>
</article>

Output Org file (guide.org):

#+TITLE: Python Setup Guide

* Virtual Environment

Create an isolated environment:

#+BEGIN_SRC bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
#+END_SRC

Example 2: Reference with Table

Input DocBook file (reference.xml):

<section xmlns="http://docbook.org/ns/docbook">
  <title>Environment Variables</title>
  <table>
    <tgroup cols="3">
      <thead><row>
        <entry>Variable</entry>
        <entry>Default</entry>
        <entry>Description</entry>
      </row></thead>
      <tbody>
        <row><entry>PORT</entry>
        <entry>3000</entry>
        <entry>Server port</entry></row>
        <row><entry>LOG_LEVEL</entry>
        <entry>info</entry>
        <entry>Logging verbosity</entry></row>
      </tbody>
    </tgroup>
  </table>
</section>

Output Org file (reference.org):

* Environment Variables

| Variable  | Default | Description       |
|-----------+---------+-------------------|
| PORT      | 3000    | Server port       |
| LOG_LEVEL | info    | Logging verbosity |

Example 3: Notes with Admonitions

Input DocBook file (notes.xml):

<section xmlns="http://docbook.org/ns/docbook">
  <title>Deployment Checklist</title>
  <orderedlist>
    <listitem><para>Run test suite</para></listitem>
    <listitem><para>Update version number</para></listitem>
    <listitem><para>Deploy to staging</para></listitem>
  </orderedlist>
  <warning>
    <para>Always back up the database first.</para>
  </warning>
</section>

Output Org file (notes.org):

* Deployment Checklist

1. Run test suite
2. Update version number
3. Deploy to staging

#+BEGIN_WARNING
Always back up the database first.
#+END_WARNING

Frequently Asked Questions (FAQ)

Q: Do I need Emacs to use Org-mode files?

A: While Emacs provides the richest Org-mode experience (folding, execution, export), Org files are plain text and can be read and edited in any text editor. VS Code has an Org Mode extension, Vim has vim-orgmode and orgmode.nvim, and tools like Logseq and org-roam provide alternative interfaces.

Q: Can I execute the code blocks in the converted Org file?

A: Yes, if you use Emacs with Org Babel. Code blocks from DocBook <programlisting> elements become #+BEGIN_SRC blocks that can be executed with C-c C-c in Emacs. The output appears directly below the code block, making documentation interactive and verifiable.

Q: How are DocBook tables converted to Org tables?

A: DocBook tables are converted to Org-mode pipe tables, which use | to separate columns and |- for horizontal rules. Emacs provides powerful table editing with TAB-based navigation and automatic alignment. Org tables also support spreadsheet formulas for computed values.

Q: Can I export the Org file back to DocBook?

A: Yes. Org-mode has a built-in DocBook exporter (ox-docbook) that can generate DocBook XML from an Org file. This makes Org-mode a viable authoring format for DocBook-based publishing workflows, with the added benefits of executable code and interactive editing.

Q: How are DocBook cross-references handled?

A: DocBook <xref> elements are converted to Org internal links using [[target][description]] syntax. Section targets become anchor links. External <ulink> elements become [[url][description]] links. Org-mode's linking system supports file links, web URLs, and internal anchors.

Q: Are DocBook metadata and attributes preserved?

A: DocBook metadata (title, author, date) is converted to Org-mode header keywords: #+TITLE:, #+AUTHOR:, #+DATE:. Document attributes can be stored as Org properties using property drawers (:PROPERTIES: blocks) attached to headings.

Q: Can I use the Org file with Logseq or org-roam?

A: Yes. Logseq and org-roam are knowledge management tools that work with .org files. Converted DocBook documents can be added to a Logseq graph or org-roam directory, making them part of a searchable, interconnected knowledge base with bidirectional linking.

Q: How are DocBook admonitions represented in Org-mode?

A: DocBook admonitions (<note>, <warning>, <tip>, etc.) are converted to Org special blocks: #+BEGIN_NOTE / #+END_NOTE, #+BEGIN_WARNING / #+END_WARNING, etc. These blocks can be styled during export and rendered with distinctive formatting in HTML and PDF output.