<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Using PSGML mode in Emacs</title><meta name="generator" content="DocBook XSL Stylesheets V1.66.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="doc-standards.html" title="Chapter�15.�Documentation Standards"><link rel="previous" href="docbook-primer.html" title="OpenACS Documentation Guide"><link rel="next" href="nxml-mode.html" title="Using nXML mode in Emacs"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="docbook-primer.html">Prev</a> </td><th width="60%" align="center">Chapter�15.�Documentation Standards</th><td width="20%" align="right"> <a accesskey="n" href="nxml-mode.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="psgml-mode"></a>Using PSGML mode in Emacs</h2></div></div></div><div class="authorblurb"><p>By David Lutterkort</p> OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. </div><p>Note: <tt class="computeroutput">nxml</tt> mode replaces and/or complements psgml mode. <a href="http://www.xmlhack.com/read.php?item=2061" target="_top">More information</a>.</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-whatisit"></a>What it is</h3></div></div></div><p>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. <span class="emphasis"><em>If</em></span> you give it the right DTD, that is. But even without a DTD, it can save you some typing since pressing <tt class="computeroutput">C-c/</tt> will close an open tag automatically.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-getit"></a>Where to get it</h3></div></div></div><p>Most newer emacsen come with PSGML mode preinstalled. You can find out whether your emacs has it with the <tt class="computeroutput">locate-library</tt> command. In Emacs, type <tt class="computeroutput">M-x locate-library</tt> and enter <tt class="computeroutput">psgml</tt>. Emacs will tell you if it found it or not.</p><p>If you don't have PSGML preinstalled in your Emacs, there are two things you can do:</p><div class="orderedlist"><ol type="1"><li><p>On Linux: Get the <a href="ftp://sourceware.cygnus.com:/pub/docbook-tools/docware/RPMS/noarch/psgml-1.2.1-1.noarch.rpm" target="_top"> psgml rpm</a> from <a href="http://sources.redhat.com/docbook-tools/" target="_top">RedHat's docbook-tools</a> and install it as usual.</p></li><li><p>On other systems: Get the tarball from the <a href="http://www.lysator.liu.se/~lenst/about_psgml/" target="_top">PSGML Website.</a> Unpack it and follow the install instructions.</p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-catalogs"></a>Using <tt class="computeroutput">CATALOG</tt> files</h3></div></div></div><p>The easiest way to teach PSGML mode about a DTD is by adding it to your own <tt class="computeroutput">CATALOG</tt>. Here is an example of how you can set that up for the Docbook XML DTD.</p><div class="orderedlist"><ol type="1"><li><p>Get the <a href="http://docbook.org/xml/index.html" target="_top">Docbook XML DTD</a> zip archive from <a href="http://docbook.org/" target="_top">docbook.org</a></p></li><li><p>Go somewhere in your working directory and do </p><pre class="programlisting"> mkdir -p dtd/docbook-xml cd dtd/docbook-xml unzip -a <docbook XML DTD zip archive> </pre></li><li><p>Create a file with the name <tt class="computeroutput">CATALOG</tt> in the <tt class="computeroutput">dtd</tt> directory and put the line </p><pre class="programlisting"> CATALOG "docbook-xml/docbook.cat" </pre><p> in it. By maintaining your own <tt class="computeroutput">CATALOG</tt>, it is easy to add more DTD's without changing your emacs settings. (<span class="emphasis"><em>How about that HTML 4.01 DTD you always wanted to get from <a href="http://www.w3.org/TR/html4/" target="_top">W3C</a> ? The DTD is in the zip archives and tarballs available on the site.</em></span>)</p></li></ol></div><p>That's it. Now you are ready to tell emacs all about PSGML mode and that funky <tt class="computeroutput">CATALOG</tt></p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-tell-emacs"></a>What to tell emacs</h3></div></div></div><p>If you installed PSGML mode in a non-standard location, e.g., somewhere in your home directory, you need to add this to the <tt class="computeroutput">load-path</tt> by adding this line to your <tt class="computeroutput">.emacs</tt> file:</p><pre class="programlisting"> (add-to-list 'load-path "/some/dir/that/contains/psgml.elc") </pre><p>To let PSGML mode find your <tt class="computeroutput">CATALOG</tt> and to enable PSGML mode for all your editing, add these lines to your <tt class="computeroutput">.emacs</tt>:</p><pre class="programlisting"> (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") </pre><p>If you want font-locking and indentation, you can also add these lines into the <tt class="computeroutput">.emacs</tt> file:</p><pre class="programlisting"> (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) </pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-doctype"></a>What is a <tt class="computeroutput">DOCTYPE</tt> ?</h3></div></div></div><p>All SGML and XML documents that should conform to a DTD have to declare a doctype. For the docbook XML, all your <tt class="computeroutput">.xml</tt> files whould start with the line</p><pre class="programlisting"> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "docbookx.dtd"> </pre><p>If your document is only part of a larger XML document, you can tell PSGML mode about it by <span class="emphasis"><em>appending</em></span> the following lines to your file. In this case, do <span class="emphasis"><em>not</em></span> include a DOCTYPE declaration in your file.</p><pre class="programlisting"> <!-- Local Variables: sgml-parent-document: ("top.xml" "book" "sect1") End: --> </pre><p>Which says that the parent of this document can be found in the file <tt class="computeroutput">top.xml</tt>, that the element in the parent that will enclose the current document is a <tt class="computeroutput">book</tt> and that the current file's topmost element is a <tt class="computeroutput">sect1</tt>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-usage"></a>How to use it</h3></div></div></div><p>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:</p><div class="informaltable"><table cellspacing="0" border="0"><colgroup><col><col></colgroup><thead><tr><th>Key</th><th>Command</th></tr></thead><tbody><tr><td><tt class="computeroutput">C-c C-e</tt></td><td>Insert an element. Uses completion and only lets you insert elements that are valid</td></tr><tr><td><tt class="computeroutput">C-c C-a</tt></td><td>Edit attributes of enclosing element.</td></tr><tr><td><tt class="computeroutput">C-c C-x C-i</tt></td><td>Show information about the document's DTD.</td></tr><tr><td><tt class="computeroutput">C-c C-x C-e</tt></td><td>Describe element. Shows for one element which elements can be parents, what its contents can be and lists its attributes.</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-reading"></a>Further reading</h3></div></div></div><p>Start with the <a href="docbook-primer.html" title="OpenACS Documentation Guide">the section called “OpenACS Documentation Guide”</a></p><div class="cvstag">($Id: psgml-mode.html,v 1.31.2.10 2005/03/01 00:15:52 joel Exp $)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="docbook-primer.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="nxml-mode.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Documentation Guide </td><td width="20%" align="center"><a accesskey="u" href="doc-standards.html">Up</a></td><td width="40%" align="right"> Using nXML mode in Emacs</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/current/psgml-mode.html#comments">View comments on this page at openacs.org</a></center></body></html>