Notes from the Mousepad

As I mentioned in a recent post, gedit snippets can help you write code more quickly, and with fewer errors, than writing all of your code manually. Snippets work by expanding small chunks of text into complete combinations of code boilerplate and variable/attribute placeholders. Using these pre-configured combinations of boilerplate and placeholders frees you to focus on the bits of code and text that are materially relevant to your work at hand.

You can enable the gedit snippets plugin by selecting Edit > Preferences > Plugins > Snippets.

There are four components to using snippets: confirming the language or syntax setting, entering the snippet ID, activating the snippet, and completing the snippet by entering the appropriate attributes or variables into the placeholder text areas.

The first thing is to make sure that the file type is set to correspond with the type of file you’re working on. If you’re starting from an existing file, gedit will attempt to set the file type for you automatically. If you’re starting a brand new file, or if gedit hasn’t correctly identified the file type, you can also manually set or change the file type.

Once you have that in place, the most difficult part is actually remembering the snippets that are available. You can view, edit, and create snipppets using the Manage Snippets window (see Tools > Manage Snippets). Once you know the relevant snippet IDs, all you need to do is type a snippet ID, and press the tab key. The tab key is what activates the snippet.

After you press the tab key, gedit converts that brief snippet of text into a combination of boilerplate text and appropriate variable or attribute placeholders. Pressing the tab key again will move the cursor to the next placeholder area.

Here’s an example. I’m starting from a blank page, and am writing a new Mallard XML file. The snippet ID to start a new Mallard page file is just the word, “page.”

Simple enough! Just enter the snippet ID, press the tab key, watch as gedit inserts the boilerplate text, and then use the tab key to maneuver through the placeholder areas.

There are currently snippets for numerous languages and syntaxes, but coverage of each language varies, and some snippets may not include the most recent language features. Give gedit snippets a try. If you don’t see a snippet feature that you’d like to use, file a bug in the gedit bug tracker.

I’ve been maintaining the gedit documentation since the run-up to the gedit 3.0 release, and doing so has helped me to get to know some of the ins-and-outs of the program. What can I say, it’s one of the perks of writing documentation – you get to know the software that you’re documenting.

With that, though, I thought I’d pass along some of the basic configurations that help me to write documentation more quickly, and in a more consistently-formatted way.

Here’s a quick run-down of some settings that you may find helpful:

View Preferences – Edit > Preferences > View:

• Check the following items:
• Display line numbers (this helps with locating validation errors)
• Display right margin at column (80 characters) (breaking lines at 80 characters makes diffs look prettier)
• Highlight the current line
• Highlight matching brackets (optional: I don’t use this feature, but some people prefer it)
• Uncheck:
• Enable text wrapping (not needed if you’re breaking lines at 80 characters)

Editor Preferences: Edit > Preferences > Editor

• Tab Width: 2
• Check
• Insert spaces instead of tabs
• Enable automatic indentation
• Uncheck
• Create a backup copy of files before saving (not needed if you’re using revision control, like git or bzr)

With regards to plugins, I recommend enabling the dashboard plugin (which will be available as part of gedit 3.4, included in Ubuntu 12.04, Fedora 17, OpenSUSE 12.2, etc.), and the gedit snippets plugin. In the near future I’ll be writing up a post about using gedit snippets.

One other neat feature that I often use with gedit is the keyboard shortcut for moving a line up or down within the text. If you position your mouse cursor on any point in a line, and then press Alt + Up Arrow, it will move the entirety of that line up within the text. Pressing Alt + Down Arrow will move that line down within the text. Simple enough! (The complete list of gedit shortcut keys is available in the user help, by the way. Just open up gedit and press F1.)

Do you have any suggestions or tips for using gedit to write documentation? If so, I’d appreciate you sharing them with me in the comments.

I ran into a couple of roadblocks in trying to use entities with Mallard recently, and thought I would share how I worked around them in case anyone else needed to do the same thing. Although my examples deal with Mallard, what I note here will also work for entities in DocBook 5 documents, or any other RelaxNG-based XML documents.

Entities?

Before I start, though, if anyone is wondering what I’m talking about when I say, “entities,” they are a handy variable-like feature of XML and a couple of other markup languages. For example, they allow you to type something like &exaile; into your document, and then have it magically parsed as:

<guiseq><gui>Applications</gui><gui>Multimedia</gui><gui>Exaile</gui><guiseq>

The final, rendered result would be a familiar GUI click-path like, "Click Applications > Multimedia > Exaile." While entities have their limitations and are not ideal for all use-cases, they serve a purpose. This web page gives a good overview of entities and how to use them.

Using Entities in Mallard / RelaxNG documents

To set up and use entities in your XML-based document, you basically need three things. You need a file that contains the entities you want to use*, you need to declare where those entities are tracked, and you need to actually use the entities in your document.

The Entities File

Previously, step one was very easy. You would just create a file that contained values like this:

<?xml version="1.0" encoding="UTF-8"?>
<!-- MENUS -->
<!ENTITY abiword '<guiseq><gui>Applications</gui><gui>Office</gui>
<gui>AbiWord</gui></guiseq>'>
<!ENTITY about-me '<guiseq><gui>Applications</gui><gui>System</gui>
<gui>Users and Groups</gui></guiseq>'>

However a somewhat recent change in libxml** prevents these entities from being parsed as they used to be, making things slightly more involved. (If you’ve been bitten by this bug, libxml will throw up a, “Namespace default prefix was not found” error message.) To resolve this, you need to include the relevant XML namespace in the entity. For Mallard-based documents, the resulting changes look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!-- MENUS -->
<!ENTITY abiword '<guiseq xmlns="http://projectmallard.org/1.0/"><gui>Applications</gui>
<gui>Office</gui><gui>AbiWord</gui></guiseq>'>
<!ENTITY about-me '<guiseq xmlns="http://projectmallard.org/1.0/"><gui>Applications</gui>
<gui>System</gui><gui>Users and Groups</gui></guiseq>'>

Out of the Woods

Once you make it past step one, the rest is a walk in the park.

Step two is to declare your entities in the start of your documentation files. I modified a DocBook 5 example to come up with this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE page [
<!ENTITY % entities-xubuntu SYSTEM "libs/xubuntu.ent">
%entities-xubuntu;
]>
<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="task"
      id="music">

Wrapping Things Up

Step three, using your entities in your documents, is no different than what you would have done with DocBook 4 or any other XML-based syntax. For example, typing &abiword; will be parsed as:

<guiseq><gui>Applications</gui><gui>Office</gui><gui>AbiWord</gui></guiseq>

and will cause “Application > Office > Abiword,” to magically appear in your rendered documentation.

If you have any questions, corrections, or suggestions (as I’m sure you’re all keen to be chatting about XML entities), feel free to leave me a note in the comments.

* I’m using external entities, which requires a separate file, but you can also use named or charater entities.
** Apparently the namespace of the parent node is no longer inherited by the entities, so you need to declare the namespace in the entity itself.

Edit: I recommend checking out Paul Frields’ post about Emacs and nXML mode, and also looking at the Fedora wiki page that he created.  I think his approach is a bit simpler and cleaner than what I’ve provided below.  Feel free to peruse what I’ve written, though, as some of my links to “getting started” references should still be helpful.

---

I’ve been doing some documentation work with Mallard and DocBook 5 recently, and have been looking for software that supports them well.  The trick is that both Mallard and DocBook 5 are based on RelaxNG schemas, and while there are many XML tools out there, there are few that are open source, and fewer still that support RelaxNG.

After perusing my options, I decided to try Emacs with nXML-mode.  Emacs’ nXML-mode provides real-time validation for RelaxNG-based documents, something which no other open source authoring tool provides. But while nXML-mode can validate XML documents on-the-fly, the default installation is not set up to validate against the recently-developed Mallard and DocBook 5 schemas.

Thus, to take full advantage of the latest in duck-based documentation technologies, I needed to modify my .emacs file and the nxml-mode files themselves.  What follows is an overview of exactly what I did in the hopes that others can make use of the same changes, too.

An nXML-mode foundation

Before we get started, though, you should know that much of what follows is derived from information on this website.  I encourage you to visit the site, as it provides an introduction to how nXML-mode is configured, and enough of an introduction to using nXML-mode to make you at least modestly productive right away.

Part One: Setting up your .emacs file

The first step in setting up nXML-mode for Mallard and DocBook 5 is to make a few changes to your .emacs file.  If you are new to Emacs, your .emacs file sits in your home directory, and serves as a personalized Emacs configuration file.  You may need to create the .emacs file if it doesn’t already exist.

;; /usr/share/emacs/site-lisp/tcc-nxml-emacs:  Add these lines
;;      to your .emacs to use nxml-mode.  For documentation of
;;      this mode, see http://www.nmt.edu/tcc/help/pubs/nxml/
;;--
;; Add the nxml files to emacs's search path for loading:
;;--
(setq load-path
      (append load-path
              '("/usr/share/emacs/site-lisp/nxml/")))
;;--
;; Make sure nxml-mode can autoload
;;--
(load "/usr/share/emacs/site-lisp/nxml/rng-auto.el")

;;--
;; Load nxml-mode for files ending in .xml, .xsl, .rng, .xhtml .page
;;--
(setq auto-mode-alist
      (cons '("\.\(xml\|xsl\|rng\|xhtml\|page\)\'" . nxml-mode)
            auto-mode-alist))

The above .emacs configuration tells Emacs where to look for detailed XML processing instructions, and also causes Emacs to automatically use nXML-mode for XML-related files.  (Did I tell you that Emacs might have a bit of a learning curve?  Yeah, that’s true.)

Part Two: Modifying the nXML-mode configuration files

The second step is to modify the nXML-mode configuration files themselves. This will add the appropriate nXML-mode secret sauce to handle Mallard and DocBook 5 documents.

Fortunately for you, I grabbed the latest nXML-mode source files from the nXML-mode website, and made the appropriate modifications myself.  You can download my customized nXML-mode files from this archive.

Here’s what I changed from the default setup:

• I added the docbookxi.rnc and mallard-1.0.rnc schemas to the schemas directory
• I modified the schemas.xml file, thus including the docbookxi.rnc and mallard-1.0.rnc schemas as part of the XML-validation process.

Note that I have used the DocBook 5 “docbookxi.rnc” schema which allows for xinclude functionality.  If you want to use the schema that does not allow for use of xinclude features, you’ll need to adjust the files accordingly.  The current DocBook 5 schemas are available here.

Part Three: Copy your nXML-mode files to the proper location
The final step is to copy the nXML-mode files to the proper location on your file system.  As indicated in our .emacs file, that location is:  /usr/share/emacs/site-lisp/nxml/.  Thus, you should copy all of the files in the downloaded “nxml” folder into that directory.  You will need administrative privileges (using root or sudo) to do this.

Wrapping up

That’s it, though.  You should now have a functioning nXML-mode environment that will allow you to fire-up Emacs and start writing Relax-NG-based documents, getting all of the real-time-validation features that Emacs provides. If you can think of any ways in which I could improve my approach, please let me know.  Otherwise, I encourage you to head-on over to the nXML-mode website, and view some of the nXML-mode information and resources that are available as you get started.