| Prev | Chapter 12. 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
+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
+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)
@@ -59,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.4//EN" "docbookx.dtd">
+ <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//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. |