<?xml version='1.0' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
               "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % myvars SYSTEM "../variables.ent">
%myvars;
]>
<sect1 id="psgml-mode" xreflabel="Using PSGML mode in Emacs">
<title>Using PSGML mode in Emacs</title>

<authorblurb>
<para>By David Lutterkort</para>
</authorblurb>

  <para>Note: <computeroutput>nxml</computeroutput> mode replaces and/or complements psgml mode.  <ulink url="http://www.xmlhack.com/read.php?item=2061">More information</ulink>.</para>

<sect2 id="psgml-mode-whatisit">
<title>What it is</title>


<para>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&#39; attributes and can tell you in which contexts a tag can be
used. <emphasis>If</emphasis> you give it the right DTD, that is. But even without a DTD,
it can save you some typing since pressing <computeroutput>C-c/</computeroutput> will close an open
tag automatically.</para>

</sect2>

<sect2 id="psgml-mode-getit">
<title>Where to get it</title>


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

<para>If you don&#39;t have PSGML preinstalled in your Emacs, there are two
things you can do:</para>

<orderedlist>
<listitem><para>On Linux: Get the <ulink url="ftp://sourceware.cygnus.com:/pub/docbook-tools/docware/RPMS/noarch/psgml-1.2.1-1.noarch.rpm">
psgml rpm</ulink> from <ulink url="http://sources.redhat.com/docbook-tools/">RedHat&#39;s
docbook-tools</ulink> and install it as usual.</para></listitem>

<listitem><para>On other systems: Get the tarball from the <ulink url="http://www.lysator.liu.se/~lenst/about_psgml/">PSGML Website.</ulink>
Unpack it and follow the install instructions.</para></listitem>
</orderedlist>

</sect2>

<sect2 id="psgml-mode-catalogs">
<title>Using <computeroutput>CATALOG</computeroutput> files</title>


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

<orderedlist>
<listitem><para>Get the <ulink url="http://docbook.org/xml/index.html">Docbook XML DTD</ulink>
zip archive from <ulink url="http://docbook.org/">docbook.org</ulink></para></listitem>

<listitem><para>Go somewhere in your working directory and do </para>

<programlisting>
      mkdir -p dtd/docbook-xml
      cd dtd/docbook-xml
      unzip -a &lt;docbook XML DTD zip archive&gt;
   
</programlisting>
</listitem>

<listitem><para>Create a file with the name <computeroutput>CATALOG</computeroutput> in the <computeroutput>dtd</computeroutput>
directory and put the line </para>

<programlisting>
      CATALOG &quot;docbook-xml/docbook.cat&quot;
</programlisting>

<para>
in it. By maintaining your own <computeroutput>CATALOG</computeroutput>, it is easy to add more
DTD&#39;s without changing your emacs settings. (<emphasis>How about that HTML 4.01 DTD you
always wanted to get from <ulink url="http://www.w3.org/TR/html4/">W3C</ulink> ? The
DTD is in the zip archives and tarballs available on the site.</emphasis>)</para></listitem>
</orderedlist>

<para>That&#39;s it. Now you are ready to tell emacs all about PSGML mode and
that funky <computeroutput>CATALOG</computeroutput></para>

</sect2>

<sect2 id="psgml-mode-tell-emacs">
<title>What to tell emacs</title>


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

<programlisting>
      (add-to-list &#39;load-path &quot;/some/dir/that/contains/psgml.elc&quot;)
   
</programlisting>

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

<programlisting>
      (require &#39;psgml)

      (add-to-list &#39;auto-mode-alist &#39;(&quot;\\.html&quot; . sgml-mode))
      (add-to-list &#39;auto-mode-alist &#39;(&quot;\\.adp&quot; . xml-mode))
      (add-to-list &#39;auto-mode-alist &#39;(&quot;\\.xml&quot; . xml-mode))
      (add-to-list &#39;auto-mode-alist &#39;(&quot;\\.xsl&quot; . xml-mode))
      
      (add-to-list &#39;sgml-catalog-files &quot;/path/to/your/dtd/CATALOG&quot;)
   
</programlisting>

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

<programlisting>
      (setq sgml-markup-faces &#39;((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 &quot;\C-c\C-x\C-e&quot; &#39;sgml-describe-element-type)
      (define-key sgml-mode-map &quot;\C-c\C-x\C-i&quot; &#39;sgml-general-dtd-info)
      (define-key sgml-mode-map &quot;\C-c\C-x\C-t&quot; &#39;sgml-describe-entity)
   
</programlisting>

</sect2>

<sect2 id="psgml-mode-doctype">
<title>What is a <computeroutput>DOCTYPE</computeroutput> ?</title>


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

<programlisting>
      &lt;!DOCTYPE book PUBLIC &quot;-//OASIS//DTD DocBook XML V4.4//EN&quot; &quot;docbookx.dtd&quot;&gt;
   
</programlisting>

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

<programlisting>
      &lt;!--
       Local Variables:
       sgml-parent-document: (&quot;top.xml&quot; &quot;book&quot; &quot;sect1&quot;)
       End:
      --&gt;
   
</programlisting>

<para>Which says that the parent of this document can be found in the file
<computeroutput>top.xml</computeroutput>, that the element in the parent that will enclose the
current document is a <computeroutput>book</computeroutput> and that the current file&#39;s topmost
element is a <computeroutput>sect1</computeroutput>.</para>

</sect2>

<sect2 id="psgml-mode-usage">
<title>How to use it</title>


<para>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:</para>

 
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Key</entry>
<entry>Command</entry>
</row>
</thead>

<tbody>
<row>
<entry><computeroutput>C-c C-e</computeroutput></entry>
<entry>Insert an element. Uses completion and only lets you insert elements that
are valid</entry>
</row>

<row>
<entry><computeroutput>C-c C-a</computeroutput></entry>
<entry>Edit attributes of enclosing element.</entry>
</row>

<row>
<entry><computeroutput>C-c C-x C-i</computeroutput></entry>
<entry>Show information about the document&#39;s DTD.</entry>
</row>

<row>
<entry><computeroutput>C-c C-x C-e</computeroutput></entry>
<entry>Describe element. Shows for one element which elements can be parents,
what its contents can be and lists its attributes.</entry>
</row>
</tbody></tgroup></informaltable>

</sect2>

<sect2 id="psgml-mode-reading">
<title>Further reading</title>


<para>Start with the <xref linkend="docbook-primer"/></para>

<para><phrase role="cvstag">($Id: psgml-mode.xml,v 1.8 2006/07/17 05:38:37 torbenb Exp $)</phrase></para>

</sect2>

</sect1>
