Chapter 1. Picking an XML Editor

Which XML Editor Should I Use?

To get right to the point: you can use whatever tool you’d like to write DocBook, but we recommend you use some kind of XML editor. A short-but-sweet list of authoring tools is available on the DocBook wiki. The editor best suited to you depends on your background and personal preferences. Some authors prefer the word processing–type of experience found in an editor like XMLmind, while others are more comfortable working directly in the markup using a text editor like vi or Emacs. The O’Reilly Tools and Production staff work with some combination of the following:

oXygen XML Author

A free trial version of oXygen is available to authors. If you decide you’d like to use oXygen, please write to and we will provide you with a floating license. oXygen has several features that make it an attractive choice:

  • Validation on the fly

  • Built-in SVN client

  • Text editor and word processing–type views

  • Now supports XIncludes by default

XMLmind XML Editor (XXE)

The production editors at O’Reilly continue to favor XXE for its word processor–like interface and ease of use. Some of the advantages of using XXE include:

  • Validation on the fly

  • GUI interface is similar to popular word-processing programs

  • O’Reilly-customized CSS and keyboard shortcuts, which may enhance the manuscript writing process

More details on using XXE can be found in O’Reilly’s XMLmind Editor Tutorial. Please note that we ask that you use a slightly older version of XMLmind Professional (version 3.5.2), which is free and permits commercial use, unlike newer versions that require a license.

Vim with key bindings

The “Vim as XML Editor” tutorial helps you customize Vim so it can function as an XML editor. Vim lets you map keys to execute frequently used key sequences or to invoke functions and commands, which means you can map DocBook element entries to key bindings. The advantages of using Vim with key bindings are that you don’t have to learn a new editor if you already know Vim; it’s fast and available for many platforms; and it offers a vast range of functionality for text editing. The disadvantages are that it offers no validation on the fly, no WYSIWYG view, and no tree view. More resources here and here.

Emacs nXML mode

nXML mode is an XML editing module for the Emacs text editor. Like Vim with key bindings, the big advantage is that all your favorite Emacs text editing commands can be used with nXML mode without restriction, saving you from having to learn a new editor. It shares some downsides with Vim: no WYSIWYG view and no tree view. However, nXML does provide a mechanism for identifying validity errors (though if you’re using XIncludes, enabling validation on the fly requires some extra config) as well as customizable syntax highlighting. Get more information on nXML mode here.

The choice of editor is yours, but we urge you to use an XML editor that will help you maintain valid DocBook 4.5 as you go. Validation is not difficult (see “Validating Your XML”). Please keep in mind that invalid documents will not be accepted into Production.

Validating Your XML

The XML files you submit to Production should be valid DocBook 4.5. Many XML editors (like XXE or oXygen) will validate your XML for you on the fly. If you’d prefer to validate via the command line, you can use xmllint. This tool is preinstalled on Mac OS X and is available for a wide range of operating systems as part of the libxml2 package from xmlsoft.

To validate a book.xml file using xmllint, run the following command:

$ xmllint --postvalid --xinclude --noout book.xml

Any validity errors will be printed to standard output. If the files are valid, no output will be printed.

Validating Locally

By default, xmllint validates over the Internet against the DTD located at the URL listed in the XML file’s DOCTYPE declaration. If validating over the Internet is undesirable, you can set up a local copy of the DocBook 4.5 DTD and a local XML catalog for validation purposes.

The easiest way to install a copy of the DocBook 4.5 DTD is via your favorite package manager. It is available via MacPorts and Cygwin, among other packaging systems.

Many packaging systems will create the necessary catalog file for you, but if you need to write one yourself, you can find more details on doing so at http://www.sagehill.net/docbookxsl/WriteCatalog.html and a sample catalog file at http://www.sagehill.net/docbookxsl/ExampleCatalog.html.

The default location where xmllint will look for the catalog file is /etc/xml/catalog. Alternatively, you can set the environment variable XML_CATALOG_FILES to define another default location for catalog files. Once you’ve got the DTD and catalog set up locally, you can validate as before:

$ xmllint --postvalid --xinclude --noout book.xml