Convert DOCBOOK to Textile

Why Convert DocBook to Textile?

Converting DocBook to Textile transforms complex XML-based technical documentation into a lightweight, human-readable markup format suitable for web publishing and project management platforms. Textile's clean syntax makes content easier to read and edit while maintaining essential formatting capabilities for headings, lists, tables, and inline styles.

Textile, created by Dean Allen in 2002, is particularly popular in the Redmine project management ecosystem, where it serves as the default markup language for wiki pages, issue descriptions, and project documentation. By converting DocBook to Textile, teams can publish their technical documentation directly to Redmine without manual reformatting.

The conversion process maps DocBook's XML elements to Textile syntax. Section titles become h1. through h6. headings. Bold and italic text use asterisks and underscores. Tables are rendered using Textile's pipe-based syntax with header markers. Lists use asterisks and hash marks for unordered and ordered items. Code blocks are wrapped in bc. or <pre> tags.

This conversion is valuable for organizations that maintain authoritative documentation in DocBook for publishing purposes but need to share the same content on Textile-powered platforms. It is also useful for migrating documentation from XML-based systems to lighter-weight web-based content management systems that use Textile as their primary markup language.

Key Benefits of Converting DocBook to Textile:

• Redmine Integration: Publish documentation directly on Redmine wikis and issues
• Human-Readable: Textile is much easier to read and edit than raw XML
• CSS Support: Textile allows inline CSS classes and styles
• Web-Ready: Textile converts cleanly to HTML for web publishing
• Quick Editing: Non-technical users can edit Textile without XML knowledge
• Table Support: Textile provides good table formatting capabilities
• Footnotes: Textile supports footnotes for documentation references

Practical Examples

Example 1: Documentation Page

Input DocBook file (docs.xml):

<section xmlns="http://docbook.org/ns/docbook">
  <title>Configuration Guide</title>
  <para>Modify the <emphasis role="bold">config.yml</emphasis>
    file to customize settings.</para>
  <table>
    <title>Settings</title>
    <tgroup cols="3">
      <thead>
        <row>
          <entry>Key</entry>
          <entry>Default</entry>
          <entry>Description</entry>
        </row>
      </thead>
      <tbody>
        <row>
          <entry>port</entry>
          <entry>8080</entry>
          <entry>HTTP port</entry>
        </row>
        <row>
          <entry>debug</entry>
          <entry>false</entry>
          <entry>Debug mode</entry>
        </row>
      </tbody>
    </tgroup>
  </table>
</section>

Output Textile file (docs.textile):

h2. Configuration Guide

Modify the *config.yml* file to customize settings.

|_. Key |_. Default |_. Description |
| port | 8080 | HTTP port |
| debug | false | Debug mode |

Example 2: Code Documentation

Input DocBook file (code-docs.dbk):

<section xmlns="http://docbook.org/ns/docbook">
  <title>API Authentication</title>
  <para>Use a <emphasis>Bearer token</emphasis>
    in the Authorization header:</para>
  <programlisting language="bash">
curl -H "Authorization: Bearer TOKEN" \
     https://api.example.com/users
  </programlisting>
  <note>
    <para>Tokens expire after 24 hours.</para>
  </note>
</section>

Output Textile file (code-docs.textile):

h2. API Authentication

Use a _Bearer token_ in the Authorization header:

bc. curl -H "Authorization: Bearer TOKEN" \
     https://api.example.com/users

p(note). Tokens expire after 24 hours.

Example 3: Feature List with Links

Input DocBook file (features.xml):

<section xmlns="http://docbook.org/ns/docbook">
  <title>Key Features</title>
  <itemizedlist>
    <listitem><para>Real-time collaboration</para></listitem>
    <listitem><para>Version control integration</para></listitem>
    <listitem><para>Custom templates</para></listitem>
  </itemizedlist>
  <para>See <link xlink:href="https://docs.example.com">
    full documentation</link> for details.</para>
</section>

Output Textile file (features.textile):

h2. Key Features

* Real-time collaboration
* Version control integration
* Custom templates

See "full documentation":https://docs.example.com for details.

Frequently Asked Questions (FAQ)

Q: What is Textile markup?

A: Textile is a lightweight markup language created by Dean Allen in 2002. It uses concise symbols for formatting: *bold*, _italic_, h1.-h6. for headings, and pipe-separated tables. Textile is primarily used in Redmine, Textpattern CMS, and Ruby on Rails applications. It generates clean HTML output and supports CSS class and style attributes inline.

Q: How does DocBook structure map to Textile?

A: DocBook sections map to Textile headings (h1. through h6.). Paragraphs become plain text blocks. Bold uses asterisks (*bold*), italic uses underscores (_italic_). Lists use asterisks for unordered and hash marks for ordered. Tables use the pipe syntax with |_. for headers. Code listings use bc. (block code) or @inline code@. Links use "text":URL syntax.

Q: Can I use the output in Redmine?

A: Yes, Redmine uses Textile as its default markup language for wiki pages, issue descriptions, and project documentation. The converted output can be pasted directly into Redmine's text editor and will render correctly. Tables, code blocks, links, and formatting all work natively in Redmine's Textile renderer.

Q: How are DocBook tables converted to Textile?

A: DocBook tables are converted to Textile's pipe-based table syntax. Header cells use |_. prefix, and regular cells use |. Each row is a single line with pipe-separated values. Column spans and row spans are supported using Textile's \2 (colspan) and /2 (rowspan) modifiers where applicable.

Q: What happens to DocBook admonitions?

A: DocBook admonitions (note, warning, tip, important, caution) are converted to styled paragraphs in Textile using the p(classname). syntax. For example, a DocBook <note> becomes p(note). in Textile. When rendered with appropriate CSS, these produce visually distinct notification blocks similar to the original admonition styling.

Q: Does the converter handle DocBook code listings?

A: Yes, DocBook <programlisting> elements are converted to Textile block code (bc.) for multi-line code or @inline@ for inline code snippets. The content is preserved exactly, including indentation and special characters. If a language attribute is specified, it is noted in a comment or HTML class attribute for syntax highlighting.

Q: How does Textile compare to Markdown?

A: Textile and Markdown are both lightweight markup languages, but they use different syntax conventions. Textile uses *bold* and _italic_ while Markdown uses **bold** and *italic*. Textile has better built-in table support and allows inline CSS classes, while Markdown has a larger ecosystem and broader platform support. Textile is preferred in Redmine environments.

Q: Can I convert Textile back to DocBook?

A: Yes, our converter supports Textile to DocBook conversion. The reverse process parses Textile markup and generates corresponding DocBook elements. Headings become sections, tables become formal tables with proper tgroup structures, and formatted text is wrapped in emphasis elements. Pandoc can also assist with this conversion direction.