How to use Emacs for XML editing

With the right customizations, editing DocBook XML, Mallard, XSLT, or other markup is a breeze with GNU Emacs. This page is not meant to be a tutorial for Emacs; there's one built into the program and plenty other stuff like that on the Web. But this page will show you how to customize Emacs to be a stunning editor for markup.

Install your tools

What to do

Run the following commands to install a set of DocBook schemas and documentation tools along with Emacs:

su -c 'yum shell'
> groupinstall 'Authoring and Publishing'
> install emacs
> install trang
> run

(After the transaction completes, type 'exit' and hit Enter, or hit Ctrl+D, to exit the yum shell.)

What this means

Using the yum shell just makes this step a little more efficient, doing both the installation of the "Authoring and Publishing" group and the other packages in one transaction.

Edit your ~/.emacs

What to do

Add the following lines to your ~/.emacs file:

(setq auto-mode-alist (cons '("\\.xml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xsl$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xhtml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.page$" . nxml-mode) auto-mode-alist))

(autoload 'xml-mode "nxml" "XML editing mode" t)

(eval-after-load 'rng-loc
  '(add-to-list 'rng-schema-locating-files "~/.schema/schemas.xml"))

What this means

These Lisp commands tell Emacs:

• When you open up a file with one of the listed extensions, whether it exists or not, Emacs should put itself in nxml-mode. This uses the nXML extension (which is included with your Fedora system's Emacs editor) to provide automatic validation and lots of other helpful functions for editing.
• If some other tool is calling xml-mode, use nxml-mode to satisfy that request.
• Add ~/.schema/schemas.xml to the list of places that nXML will look when it tries to locate RelaxNG schemas.

Set up schemas

What to do

Make a ~/.schema directory:

mkdir ~/.schema
cd ~/.schema

Now get a RelaxNG Compact schema for Mallard:

curl -O http://projectmallard.org/1.0/mallard-1.0.rnc

Make a folder for DocBook 4.5 and generate a RelaxNG Compact schema for it:

mkdir docbook-xml-4.5
cd docbook-xml-4.5
trang /usr/share/sgml/docbook/xml-dtd-4.5/docbookx.dtd docbook.rnc

Make a file ~/.schema/schemas.xml and use the following content:

<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
  <namespace ns="http://projectmallard.org/1.0/" uri="mallard-1.0.rnc"/>
  <documentElement prefix="" localName="article" typeId="DocBook"/>
  <documentElement prefix="" localName="book" typeId="DocBook"/>
  <typeId id="DocBook" uri="docbook-xml-4.5/docbook.rnc"/>
</locatingRules>

What this means

This might seem a little voodoo-like if you're not familiar with schemas and/or RelaxNG. Basically, nXML mode can read in RelaxNG Compact schemas and use them to help you edit your documents -- it can tell you what elements and attributes are valid as you go. It can even prompt you for what to do next so you don't have to manually consult a reference.

The steps above ensure that:

• You have the schemas you need
• Mallard files, as long as we set their XML namespace, are set to automatically validate against the Mallard schema
• XML files with an <article> or <book> element are set to validate against the DocBook 4.5 schema.

Try out the results

First, you'll need a fresh copy of Emacs running. Start Emacs and open a new file test.xml. Make the root element a book by adding the following content:

<book>
</book>

Now from the Emacs menu, select XML > Set Schema > Automatically. You'll see a message in the message bar that says "Using schema ~/.schema/docbook-xml-4.5/docbook.rnc".

Add a blank line between the opening and closing book tags, and you can start enjoying nXML mode. Type a < character and hit Ctrl+Enter for a list of valid tags. You can type a few letters and hit Tab to use auto-completion. Hit Enter to insert the given tag. This also works with attributes: simply add a space after the tag, and hit Ctrl+Enter for attribute auto-completion. If attribute values are declared in the schema, you can also auto-complete those by hitting Ctrl+Enter after the double quote. You'll see the message "No completions available" if you've misspelled the beginning, or if there are not a finite set of choices that nXML can display.

---