Tools for editing DocBook 5 bannerA long time ago I used to edit SGML and XML in GNU Emacs. GNU Emacs was a good SGML/XML editor. I’m willing to bet 0.05 bitcoins it still works. By works, I mean not only that you can edit XML text directly (duh, Windows Notepad can do that), but that you get validation, tag completion, maybe syntax highlighting, reformatting… the sort of features that make it easy to manage documents.

I am looking at alternatives for those who develop in IDEs as well as for people who want to use other editors. If you want to write in DocBook XML, it appears the list of possible tools goes on and on. (Though the DocBook Wiki list of authoring tools seems to have been zapped when the backup was lost a while ago.) My list below is hardly exhaustive. I would appreciate comments about your experiences.

IDEs tried so far:

  • Eclipse 3.6.2 (Mac OS X and Ubuntu): My editor of choice right now, especially since I’m also fiddling with Maven. Validation’s essentially instantaneous. Tag completion’s almost quick enough, though I still need to learn how to show allowed attributes on an element. Formatting works, just reformat the active element, not the whole document. Reformatting the whole document seems to wreak havoc with the comments for me.
  • NetBeans 6.9.1 (Mac OS X): Not usable. Validation of a single file (28 KB), takes maybe 10 seconds. Then I went in a section after a <para> and typed <. Well over 10 seconds to get a tag completion list. I typed p. Another 10 seconds to get that list narrowed. When I selected <para>, I got no corresponding </para>. Maybe that’s a feature rather than a bug. Earlier this year I tried 7.0 beta 1 and 2, and it was the same story basically. I’m giving up on NetBeans as a DocBook 5 editor for now.

Editors tried so far:

  • Dashcode (Mac OS X): Appears limited to syntax highlighting. The completion list doesn’t seem to be aware of the document type.
  • JEdit (Mac OS X): Good deal! Need to install a few plugins, including XML which depends on other stuff. When you get the EclipseIcons plugin, avoid just the binary version as it seems to be missing the EclipseIcons.jar file. Validation seems quick, with JEdit downloading copies of the .xsd files needed. It doesn’t seem to handle <xinclude:include href=”preface.xml” /> by default, however. (Need to add notes as described in the doc.) Tag completion feels quick and natural, as does attribute completion. (Just hit the spacebar for attribute completion inside an element. Cool!)  Syntax highlighting is sober and functional by default. Unfortunately I ruined my install trying to get reformatting/reindenting with the Beauty plug-in. Now jEdit won’t start… but a reinstall was very quick, including the download. Will have to take a look later. Could be a keeper.
  • LibreOffice (Ubuntu): Could’t figure out how to open DocBook XML directly as something other than ASCII. I found a docbook2odf package. docbook2odf claimed it wrote an .odt file. But then I couldn’t find the .odt anywhere. Perhaps something is on the way at least to allow DocBook XML to be imported into LibreOffice.
  • Notepad (Windows 7): If you just have to edit an XML file to change a few characters to fix an error, you can use it in a pinch. Unless you have UNIX line ending.
  • Vim (Mac OS X): Well, there’s an xml.vim plugin… I’m too lazy to RTFM just to see if I can do validation or tag completion.
  • XML Copy Editor (Ubuntu):  Validation seemed to hang for the 2 documents I tried. The completion list comes up quickly, apparently precompiled so I only have to wait once. (Thank you, XML Copy Editor project folks.)

7 thoughts on “Tools for editing DocBook 5

  1. Hi,
    Nice to see someone else looking for structured editors.
    You can also test:
    – Serna :
    – XMLMind Editor (if licence is OK)

    There is an interesting project also:
    – maybe too basic
    – a wiki to edit docbook with comments and all, very good concept, but very few code to run it …
    – the same with running code and demo, but not far enough on the road to DocBook :
    => I really think that an online docbook editor (or at least a structured editor) would be great

    Finally, there are many wiki2docbook translators and tons of stuff:

  2. More chat about this lately on the docbook-apps alias, which led me to notice that LibreOffice does export and import DocBook XML. In LibreOffice 3.5, it appears to be DocBook 4.1.2. For example:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" “”>
    <article lang="">
    <title>Test Document</title>
    <para>This is a test.</para>

    I tried importing a test DocBook 5 XML book as well, which resulted in:

    “General Error.
    General input/output error.”

    Could be the DTD. Changing to 5 in the above document results in the same error.

    1. I just copy-pasted your test document into a text editor, and it wouldn’t validate. I saw it uses “curly” quotation marks around the oasis-open url. When I changed those to “straight” quotation marks, it opened fine in LibreOffice

      1. Thanks, Tommy. I cannot remember whether the curly quotes here were in the original, or whether they’re an artifact of WordPress. Will have to try again.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s