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.)