PSGML Mode is a mode for editing, umm, SGML and XML documents in emacs. It can parse a DTD and help you insert the right tags in the right place, knows about tags' attributes and can tell you in which contexts a tag can be used. If you give it the right DTD, that is. But even without a DTD, it can save you some typing since pressing C-c/ will close an open tag automatically.

Most newer emacsen come with PSGML mode preinstalled. You can find out whether your emacs has it with the locate-library command. In Emacs, type M-x locate-library and enter psgml. Emacs will tell you if it found it or not.

If you don't have PSGML preinstalled in your Emacs, there are two things you can do:

The easiest way to teach PSGML mode about a DTD is by adding it to your own CATALOG. Here is an example of how you can set that up for the Docbook XML DTD.

That's it. Now you are ready to tell emacs all about PSGML mode and that funky CATALOG

If you installed PSGML mode in a non-standard location, e.g., somewhere in your home directory, you need to add this to the load-path by adding this line to your .emacs file:

      (add-to-list 'load-path "/some/dir/that/contains/psgml.elc")
   

To let PSGML mode find your CATALOG and to enable PSGML mode for all your editing, add these lines to your .emacs:

      (require 'psgml)

      (add-to-list 'auto-mode-alist '("\\.html" . sgml-mode))
      (add-to-list 'auto-mode-alist '("\\.adp" . xml-mode))
      (add-to-list 'auto-mode-alist '("\\.xml" . xml-mode))
      (add-to-list 'auto-mode-alist '("\\.xsl" . xml-mode))
      
      (add-to-list 'sgml-catalog-files "/path/to/your/dtd/CATALOG")
   

If you want font-locking and indentation, you can also add these lines into the .emacs file:

      (setq sgml-markup-faces '((start-tag . font-lock-function-name-face)
                                (end-tag . font-lock-function-name-face)
                (comment . font-lock-comment-face)
                (pi . bold)
                (sgml . bold)
                (doctype . bold)
                (entity . font-lock-type-face)
                (shortref . font-lock-function-name-face)))
      (setq sgml-set-face t)
      (setq-default sgml-indent-data t)
      ;; Some convenient key definitions:
      (define-key sgml-mode-map "\C-c\C-x\C-e" 'sgml-describe-element-type)
      (define-key sgml-mode-map "\C-c\C-x\C-i" 'sgml-general-dtd-info)
      (define-key sgml-mode-map "\C-c\C-x\C-t" 'sgml-describe-entity)
   

All SGML and XML documents that should conform to a DTD have to declare a doctype. For the docbook XML, all your .xml files whould start with the line

      <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "docbookx.dtd">
   

If your document is only part of a larger XML document, you can tell PSGML mode about it by appending the following lines to your file. In this case, do not include a DOCTYPE declaration in your file.

      <!--
       Local Variables:
       sgml-parent-document: ("top.xml" "book" "sect1")
       End:
      -->
   

Which says that the parent of this document can be found in the file top.xml, that the element in the parent that will enclose the current document is a book and that the current file's topmost element is a sect1.

Of course, you should read the emacs texinfo pages that come with PSGML mode from start to finish. Barring that, here are some handy commands:

Start with the the section called “OpenACS Documentation Guide”