I spent last few days searching for tools that would facilitate process of writing few articles using Docbook. I analyzed few solutions - mainly XMLmind XML Editor, Vim with various plugins and Asciidoc. This post presents the result of this research.

Docbook

For those who are not familiar with Docbook let me cite its website (see links at the end of this text):

DocBook is a schema (available in several languages including RELAX NG, SGML and XML DTDs, and W3C XML Schema) maintained by the DocBook Technical Committee of OASIS. It is particularly well suited to books and papers about computer hardware and software (though it is by no means limited to these applications).

A Docbook XML document can be later transformed into HTML (single or chunked), PDF, RTF, ePub, DIV and other formats using various free tools.

Editors

Firstly, I intended to write articles using Docbook markup tags directly. I did it few years ago and Docbook elements are not new to me, so I wanted to refresh my knowledge of Docbook and use it directly. I checked out two solutions:

• XMLmind XML Editor (Personal Edition)
• Vim

Docbook with XMLmind XML Editor

XMLmind XML Editor (Personal Edition) is a powerful editor for working with structured documents. Its free version seemed to be capable of everything I expected in terms of functionality. Alas, its usability is questionable (for me). Somehow I couldn't make friends with it. I felt like I can't move freely within the document, and this distracted me. So I decided I need a different tool.

(Still I think that XXE might be very useful if working with some very complex XML documents. But I can't use it for writing. It distracts me too much from the real task.)

Docbook with Vim

After the failure of using XXE I turned into the opposite direction and tried to write Docbook documents using Vim.

First of all I tried few XML-enabling plugins of Vim. They can help. They can reformat your document, close unclosed tags etc.

Then I searched some more and found a lot of macros that help you enter Docbook tags much quicker. I liked them more than the plugins. And I would have probably stopped my search here if I hadn't discovered Asciidoc.

Asciidoc with Vim

Even with the help of macros I spent too much time inserting markup elements and worrying if <para> could go into the <itemlist> or such.

While all the plugins and macros described in the previous part of the post help you to enter elements of Docbook markup quicker, Asciidoc takes different approach and replaces XML markup with simple wiki-like syntax.

With Asciidoc your Docbook document is a simple txt file that gets translated into valid Docbook file and later into desired output format.

As far as I know (but my knowledge of Asciidoc is still limited) not all elements of Docbook can be expressed using Asciidoc syntax. In such cases you can include Docbook elements directly into Asciidoc text file (using "passthrough" blocks.

The beauty of this approach lies in much simpler notation. The most common elements (i.e. paragraphs, lists) are easily created with use of new lines or simple symbols. Please consider this example of bullet list from Docbook and Asciidoc:

Bullet List - Docbook Version

Bullet List - Asciidoc Version

Vim Highlight

Asciidoc provides necessary files to teach Vim how to highlight some important elements. This makes working with Vim and Asciidoc a pleasant experience.

And the Winner is...

Right now I decided to use Asciidoc. Its wiki-like syntax lets me forget about the complexity of Docbook elements and concentrate on writing.

I'm not sure yet what are the shortcomings of Asciidoc. Since now, I'm very happy using it.

Links

• Docbook
• Vim
• Asciidoc
• Vim Asciidoc highlighting
• a2x manual page
• asciidoc manual page
• XMLmind XML Editor