2. Emacs+PSGML

2. Emacs+PSGML
Prev	Chapter 5. Borges and XML Editors	Next

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")
     End:
     -->

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.

Tip

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.

Note

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.

Tip

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

Command	Keyboard Shortcut or Menu Entry	Description
Insert Element	Ctrl-C-Ctrl-E	Inserts 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 File	Ctrl-C-Ctrl-V	Loads 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 Spot	Ctrl-C-Ctrl-O	This 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 Element	Ctrl-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 Tags	Ctrl-C-Ctrl-T	Lists all the valid tags that can be inserted at the current cursor position. This is useful when working with “complex”DTDs (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 DTD“reminder”.
Fold Element	Ctrl-C-Ctrl-F-Ctrl-E	Folds 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 Element	Ctrl-C-Ctrl-U-Ctrl-E	Unfolds the folded element the cursor is at.
Insert Attribute	Markup->Insert Attribute	Shows 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.