| Prev | Chapter�15.�Documentation Standards | Next |
|---|
By David Lutterkort
+ +Note: nxml mode replaces and/or complements psgml mode. More information.
Note: nxml mode replaces and/or complements psgml mode. More information.
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
+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:
On Linux: Get the psgml rpm from RedHat's docbook-tools and install it as usual.
On other systems: Get the tarball from the PSGML Website. -Unpack it and follow the install instructions.
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.
Get the Docbook XML DTD zip archive from docbook.org
Go somewhere in your working directory and do
mkdir -p dtd/docbook-xml
cd dtd/docbook-xml
unzip -a <docbook XML DTD zip archive>
-Create a file with the name CATALOG in the dtd
+
Create a file with the name CATALOG in the dtd directory and put the line
- CATALOG "docbook-xml/docbook.cat" + CATALOG "docbook-xml/docbook.cat"
-in it. By maintaining your own CATALOG, it is easy to add more
+in it. By maintaining your own CATALOG, it is easy to add more
DTD's without changing your emacs settings. (How about that HTML 4.01 DTD you
always wanted to get from W3C ? The
DTD is in the zip archives and tarballs available on the site.)
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") +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:
+
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 '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")
+ (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:
+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)
@@ -58,28 +59,28 @@
(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)
+ (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
+
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">
+ <!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")
+ 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:
| Key | Command |
|---|---|
C-c C-e | Insert an element. Uses completion and only lets you insert elements that -are valid |
C-c C-a | Edit attributes of enclosing element. |
C-c C-x C-i | Show information about the document's DTD. |
C-c C-x C-e | Describe element. Shows for one element which elements can be parents, -what its contents can be and lists its attributes. |
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:
| Key | Command |
|---|---|
| C-c C-e | Insert an element. Uses completion and only lets you insert elements that +are valid |
| C-c C-a | Edit attributes of enclosing element. |
| C-c C-x C-i | Show information about the document's DTD. |
| C-c C-x C-e | Describe element. Shows for one element which elements can be parents, +what its contents can be and lists its attributes. |