From Fedora Project Wiki

Revision as of 19:54, 8 February 2011 by Pfrields (talk | contribs) (Fix markup burp)

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[1].

Set up schemas

What to do

Make a ~/.schema directory:

mkdir ~/.schema
cd ~/.schema

Now get a RelaxNG Compact schema for Mallard:

curl -O

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

mkdir ~/.schema/docbook-xml-4.5
cd ~/.schema/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="">
  <namespace ns="" 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"/>

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[2].

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:


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.

Adding other schemas

You can add other XML document types. For example, say you want to manually edit the XML file that defines a virtual guest domain using libvirt. To allow nXML to deal with its schema, you need to locate a RelaxNG schema or DTD file. Fortunately libvirt provides these, so you just need to turn that schema into a RelaxNG Compact schema (.rnc) and add it to ~/.schema/schemas.xml. Note that the libvirt in this example is 0.8.3:

cd ~/.schema
mkdir libvirt-0.8.3
cd libvirt-0.8.3
trang /usr/share/libvirt/schemas/domain.rng domain.rnc

Then edit the ~/.schema/schemas.xml file to add the following additional rule inside the locatingRules element:

<documentElement prefix="" localName="domain" uri="libvirt-0.8.3/domain.rnc">

Now you can perform the same nXML magic with a libvirt domain!

  1. You may not know what RelaxNG schemas are. That's OK, don't panic. For now, just note that they help Emacs figure out what tags are allowed where in your document. In other words, this helps Emacs and nXML help you!
  2. Of course, you can modify this to use a different DocBook version if needed.