psgml-mode.xml
Delivered as text/xml
[ hide source ] | [ make this the default ]
File Contents
<?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' 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'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's
docbook-tools</ulink> and install it as usual.</para></listitem>
<listitem><para>On other systems: Get the tarball from the <ulink url="https://www.emacswiki.org/emacs/PsgmlMode">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 <docbook XML DTD zip archive>
</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 "docbook-xml/docbook.cat"
</programlisting>
<para>
in it. By maintaining your own <computeroutput>CATALOG</computeroutput>, it is easy to add more
DTD'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'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 'load-path "/some/dir/that/contains/psgml.elc")
</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 '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")
</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 '((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)
</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 would start with
the line</para>
<programlisting>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "docbookx.dtd">
</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>
<!--
Local Variables:
sgml-parent-document: ("top.xml" "book" "sect1")
End:
-->
</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'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'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.9.2.1 2021/09/02 16:56:02 gustafn Exp $)</phrase></para>
</sect2>
</sect1>
