Index: openacs-4/packages/acs-core-docs/www/psgml-mode.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-mode.html,v diff -u -r1.44 -r1.44.2.1 --- openacs-4/packages/acs-core-docs/www/psgml-mode.html 12 Jul 2009 01:08:29 -0000 1.44 +++ openacs-4/packages/acs-core-docs/www/psgml-mode.html 18 Jun 2010 21:29:35 -0000 1.44.2.1 @@ -1,53 +1,53 @@ - -Using PSGML mode in Emacs

Using PSGML mode in Emacs

By David Lutterkort

+ +Using PSGML mode in Emacs

Using PSGML mode in Emacs

By David Lutterkort

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Note: nxml mode replaces and/or complements psgml mode. More information.

What it is

PSGML Mode is a mode for editing, umm, SGML and XML documents in emacs. It +

Note: nxml mode replaces and/or complements psgml mode. More information.

What it is

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.

Where to get it

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.

Where to get it

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:

  1. On Linux: Get the -psgml rpm from RedHat's -docbook-tools and install it as usual.

  2. On other systems: Get the tarball from the PSGML Website. -Unpack it and follow the install instructions.

Using CATALOG files

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.

  1. Get the Docbook XML DTD -zip archive from docbook.org

  2. Go somewhere in your working directory and do

    +things you can do:

    1. On Linux: Get the +psgml rpm from RedHat's +docbook-tools and install it as usual.

    2. On other systems: Get the tarball from the PSGML Website. +Unpack it and follow the install instructions.

Using CATALOG files

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.

  1. Get the Docbook XML DTD +zip archive from docbook.org

  2. Go somewhere in your working directory and do

           mkdir -p dtd/docbook-xml
           cd dtd/docbook-xml
           unzip -a <docbook XML DTD zip archive>
        
    -
  3. Create a file with the name CATALOG in the dtd +

  4. 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

What to tell emacs

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

What to tell emacs

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)
    
-

What is a DOCTYPE ?

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 +

What is a DOCTYPE ?

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.

How to use it

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:

KeyCommand
C-c C-eInsert an element. Uses completion and only lets you insert elements that -are valid
C-c C-aEdit attributes of enclosing element.
C-c C-x C-iShow information about the document's DTD.
C-c C-x C-eDescribe element. Shows for one element which elements can be parents, -what its contents can be and lists its attributes.

Further reading

Start with the the section called “OpenACS Documentation Guide”

($Id$)
View comments on this page at openacs.org
+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.

How to use it

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:

KeyCommand
C-c C-eInsert an element. Uses completion and only lets you insert elements that +are valid
C-c C-aEdit attributes of enclosing element.
C-c C-x C-iShow information about the document's DTD.
C-c C-x C-eDescribe element. Shows for one element which elements can be parents, +what its contents can be and lists its attributes.

Further reading

Start with the Section , “OpenACS Documentation Guide”

($Id$)
View comments on this page at openacs.org