Emacs and Psgml
Prev
Next

Emacs and Psgml

The venerable Emacs editor has a powerful SGML and XML editing mode called psgml. The price of this power is a steeper learning curve than the other editors, so if you haven't used Emacs before, you will probably want to try the other editors first. If, on the other hand, you're already familiar with Emacs, then psgml is your best choice.

Installation of psgml is beyond the scope of this document, but it should simply be a case of installing appropriate packages for your distribution. The relevant configuration for TDE-related documentation is simple. Just tell psgml where the TDE catalog files are located with the following line in your .emacs file:

(setq sgml-catalog-files 
  (list "CATALOG" "TDEDIR/share/apps/ksgmltools2/customization/catalog"))
where you should replace TDEDIR with the path to your TDE installation. You might also want to use the following line to instruct Emacs to use psgml to open all .docbook files:
(setq auto-mode-alist
      (cons '("\\.docbook$" . sgml-mode) auto-mode-alist))

There are of course plenty of other settings in psgml mode which you can change to your taste: see the psgml info documentation for more details. A sample .emacs file, with some customizations useful for writing TDE documentation, can be found at http://people.fruitsalad.org/phil/kde/dot-emacs-psgml.

Some basic keystrokes in psgml are:

Ctrl+C /

End current element. This inserts an end tag for the currently open element.

Meta+Tab

Completes the current tag or entity, context-sensitively. This will only complete on tags that are allowed at the current point in the document. Note that, because indentation is rarely used in TDE documentation, it is generally safe to remap this function to just the Tab key.

Ctrl+C Ctrl+F Ctrl+E

Fold current element. This compresses the current element so that only the starting tag appears. One use of this is to fold all the chapter elements in a document, to get an overview of the document on one screen, and make navigation around a long document easier. You can unfold elements with the shortcut Ctrl+C Ctrl+U Ctrl+E.

One particularly useful psgml feature that isn't well documented is the sgml-parent-document variable. Setting this variable appropriately tells psgml that this file is part of a larger document. This enables the full range of psgml features for this file, such as context-sensitive element completion. To use this feature, place the following in a comment at the end of the child file (with the arguments adjusted appropriately):


The first argument is the name of the parent file (which will almost
always be index.docbook in TDE
documentation). The second argument is the top-level (or
“root”) element of the whole document (that is,, in the parent
file). The third argument is the top-level element in this file.

Prev
Next
Home


Would you like to comment or contribute an update to this page?
Send feedback to the TDE Development Team