| PostgreSQL 8.0.1 Documentation | ||||
|---|---|---|---|---|
| Prev | Fast Backward | Appendix G. Documentation | Fast Forward | Next |
G.4. Documentation Authoring
SGML and DocBook do not suffer from an oversupply of open-source authoring tools. The most common tool set is the Emacs/XEmacs editor with appropriate editing mode. On some systems these tools are provided in a typical full installation.
G.4.1. Emacs/PSGML
PSGML is the most common and most powerful mode for editing SGML documents. When properly configured, it will allow you to use Emacs to insert tags and check markup consistency. You could use it for HTML as well. Check the PSGML web site for downloads, installation instructions, and detailed documentation.
There is one important thing to note with PSGML: its author assumed that your main SGML DTD directory would be /usr/local/lib/sgml. If, as in the examples in this chapter, you use /usr/local/share/sgml, you have to compensate for this, either by setting SGML_CATALOG_FILES environment variable, or you can customize your PSGML installation (its manual tells you how).
Put the following in your ~/.emacs environment file (adjusting the path names to be appropriate for your system):
and in the same file add an entry for SGML into the (existing) definition for auto-mode-alist:
Currently, each SGML source file has the following block at the end of the file:
This will set up a number of editing mode parameters even if you do not set up your ~/.emacs file, but it is a bit unfortunate, since if you followed the installation instructions above, then the catalog path will not match your location. Hence you might need to turn off local variables:
The PostgreSQL distribution includes a parsed DTD definitions file reference.ced. You may find that when using PSGML, a comfortable way of working with these separate files of book parts is to insert a proper DOCTYPE declaration while you're editing them. If you are working on this source, for instance, it is an appendix chapter, so you would specify the document as an "appendix" instance of a DocBook document by making the first line look like this:
This means that anything and everything that reads SGML will get it right, and I can verify the document with nsgmls -s docguide.sgml. (But you need to take out that line before building the entire documentation set.)
G.4.2. Other Emacs modes
GNU Emacs ships with a different SGML mode, which is not quite as powerful as PSGML, but it's less confusing and lighter weight. Also, it offers syntax highlighting (font lock), which can be very helpful.
Norm Walsh offers a major mode specifically for DocBook which also has font-lock and a number of features to reduce typing.
