The preceding sections of this chapter explained how the Hackystat Documentation framework is designed, how to invoke the documentation generation system via the Ant build process, how the individual components of the documentation are distributed among the modules, how to define and structure an individual component, and the "vocabulary" (i.e. tags) to use for writing the documentation.
None of this says how you actually sit down and compose the XML documents. This section provides an overview of the method and tool support we currently recommend.
First off, there is, of course, no real limitation on what tool you use to create the documentation files. You could use Notepad, although that would be unspeakably sad. There are a great many XML editors available, and some of them might be quite appropriate. In our experience, we have found that there are two major problems with finding an XML-aware editor for the purpose of Hackystat documentation generation:
Some WYSIWYG editors try to "prettify" the underlying XML document by doing significant amounts of indentation. For the public modules, where the underlying XML will be edited by hand on occasion, this is unacceptable.
Many XML editors simply blow up when they try to read in a Hackystat XML docbook document, since it refers to entities and files that aren't "there" yet, and won't be there until the docbook files are aggregated together during the build process.
After a certain amount of trial and error, we have found that Good Old Emacs, while not the perfect solution, is better suited to the task of Hackystat XML document editing than any other tool we have tried. The remainder of this section provides some tips on getting up to speed with Emacs and installing some helpful customizations.
Emacs is an open source, extensible editor that runs on virtually all platforms. Emacs does have a learning curve, but there are many, many online resources available to help get you up to speed. Some of our favorites include:
Emacs Tutorial (best used inside Emacs)
Emacs Cheat Sheet (short)
Emacs RefCard (short)
Emacs RefCard (official, pdf)
Emacs for Mac OS (links)
Effective Emacs (rant, humorous, insightful)
For use in editing XML documents, there is an Emacs package called XAE (XML Authoring Environment ). This package provides a mode called "XAE" that is automatically invoked when you edit a document with a .xml extension.
To simplify the process of setting up an Emacs environment using XAE (and some homegrown Emacs utilities), you can download a module called "csdl-emacs" from our CSDL subversion repository at: svn://www.hackystat.org/csdl/csdl-emacs/. Consult the README.html file at the top-level of this module after downloading. It will provide instructions on how to (a) install a copy of Emacs 21.3 for Windows (included in this csdl-emacs package); (b) configure your .emacs file to load some useful CSDL Emacs customizations, and (c) install and invoke the XAE package (also included in this csdl-emacs package) when you run Emacs. If you are using Linux or Mac OS/X rather than Windows, the only change is that you will have to download Emacs separately if it is not already available in your environment.
Once you have installed Emacs and configured it properly, when you edit an XML document it will enter XAE mode. Figure 18.3, “ Editing docbook using Emacs with XAE ” illustrates this.
There are several things to note in this image. First, you can see that there is an "XAE" menu at the top of the window, and "(XAE)" appears in the mode line. This indicates that you are in XAE mode. You can see that XML tags are fontified, which is helpful.
There are two extremely useful key commands that your configured Emacs environment makes available to you once it is configured. The first is "control-c /", which is an abbreviation for the "sgml-insert-end-tag" command. What this does is insert the end tag associated with the immediately preceding open tag. So, for example, right now I am in the middle of a <para> environment. If I were to invoke "control-c /" right now, the </para> tag would be inserted into the buffer. If I invoked it again, the </section> tag would be inserted. If I did it again, another </section> tag would be inserted. After that, the </chapter> tag, and then it would finally signal an error since I would have closed all of the open tags all the way to the "top" of the buffer.
This sgml-insert-end-tag command is just ridiculously helpful, since it gives you a way to easily "figure out where you are" within the nested XML document. One of the prime problems with writing XML in a vanilla editor is ensuring that you have closed off all of your tags, and this command makes it much easier to do so.
The second useful key command is called "escape-xml-tags-in-region", and it is a simple Emacs function that we wrote in order to facilitate the development of this docbook documentation. It turns out that inside a <programlisting> environment, for example, you have to "escape" any XML tag characters such as <, >, and &, substituting for them the strings "<", ">", and "&", respectively. To simplify this substitution process, we wrote the escape-xml-tags-in-region command, and bound it to the key sequence "control-c x". The way it works is that you must first select a region in Emacs (using either the mouse to select the region, or the more old school "control-space" to set the mark, followed by moving the cursor to the end of the region). After the region is selected, invoke "control-c x". This invokes the substitution process on the text in the region.