psgml-mode.xml
Delivered as text/xml
[ hide source ]
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>