2. Emacs+PSGML

As mentioned before, Emacs with its PSGML module makes your life easier when working with XML files. We will explain some basic PSGML commands and DTD features in the following sections.

2.1. Installing PSGML

You can download PSGML from the PSGML home page or, if you are a Mandrake Linux user and have the “contribs” source or CD configured in the Software Manager, simply issuing urpmi psgml will install PSGML.

2.2. DTD-Awareness

PSGML mode is DTD-aware. This means that when using PSGML you will always produce well-formed and valid XML files. Please refer to The XML FAQ for more information about the meaning of the terms “well-formed” and “valid”.

PSGML should be told somehow about the DTD your module intends to conform to, in order to be “aware” of it. To do so, Borges inserts the following at the end of every module's XML source file:

     <!-- Keep this comment at the end of the file
     Local variables:
     mode: xml
     sgml-parent-document: ("../../manuals/module/en/psgml-top.xml" "root_element")

where mode: xml guarantees that Emacs will enter XML mode after auto-loading PSGML when you open the module's source XML file with it, and root_element should be replaced by the module's root element, for example chapter if the module in question is a chapter.


In case you are wondering, the psgml-top.xml filename is automatically created under the manuals/module/ directory when configuring Borges.

2.3. Basic PSGML Commands

PSGML mode adds powerful commands which take the burden of typing element tags and/or element attributes when working with plain-text XML files.


The following table lists some PSGML commands without any order nor preference, please refer to the PSGML documentation for a complete list of available commands.


When you see something like Ctrl-C-Ctrl-E it means that you have to press the Control key plus the C key, and right afterwards the Control key plus the E key.

Table 5.1. PSGML Commands

CommandKeyboard Shortcut or Menu EntryDescription
Insert ElementCtrl-C-Ctrl-EInserts an element constrained by the DTD. That is, only elements allowed by the DTD can be inserted. If you press the Tab key, a list of valid elements is shown in Emacs' mini-buffer. If the element to be inserted requires attributes you will be prompted to enter their values in Emacs' mini-buffer.
Validate FileCtrl-C-Ctrl-VLoads the DTD, parses it (if not already parsed), and then presents the external validation command in Emacs' mini-buffer. Pressing Enter will proceed to validate the file showing a list of validation errors.
Next Trouble SpotCtrl-C-Ctrl-OThis one includes the validation one, but instead of showing a list of errors it stops when encounters the first error and shows the error message in Emacs' mini-buffer. This is the preferred way to validate files.
End ElementCtrl-C-/Ends the current open element. Actually, the Insert Element command inserts opening and ending tags where appropriate, but if you type the element name and want to close it without typing the whole closing tag, then this one comes handy.
List Valid TagsCtrl-C-Ctrl-TLists all the valid tags that can be inserted at the current cursor position. This is useful when working with “complexDTDs (like DocBook) where some elements can have dozens of elements inside them, and you cannot expect to know them all by heart. It can be used as a quick DTDreminder”.
Fold ElementCtrl-C-Ctrl-F-Ctrl-EFolds the element the cursor is at. This is very handy when working with big files to have a quick view of the document's (or part of a document's) structure. The effect of folding an element is that only the opening tag and one line of content ending in ellipsis (...) is shown.
Unfold ElementCtrl-C-Ctrl-U-Ctrl-EUnfolds the folded element the cursor is at.
Insert AttributeMarkup->Insert AttributeShows a list of the attributes valid for the element the cursor is at from where you can chose the one you want to insert. If the attribute selected requires a value you will be prompted for it in Emacs' mini-buffer.