<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Documentation Authoring</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 8.0.11 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Documentation"
HREF="docguide.html"><LINK
REL="PREVIOUS"
TITLE="Building The Documentation"
HREF="docguide-build.html"><LINK
REL="NEXT"
TITLE="Style Guide"
HREF="docguide-style.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2007-02-02T03:57:22"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
>PostgreSQL 8.0.11 Documentation</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="docguide-build.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="docguide.html"
>Fast Backward</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Appendix G. Documentation</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="top"
><A
HREF="docguide.html"
>Fast Forward</A
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="top"
><A
HREF="docguide-style.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="DOCGUIDE-AUTHORING"
>G.4. Documentation Authoring</A
></H1
><P
> <ACRONYM
CLASS="ACRONYM"
>SGML</ACRONYM
> and <SPAN
CLASS="PRODUCTNAME"
>DocBook</SPAN
> do
not suffer from an oversupply of open-source authoring tools. The
most common tool set is the
<SPAN
CLASS="PRODUCTNAME"
>Emacs</SPAN
>/<SPAN
CLASS="PRODUCTNAME"
>XEmacs</SPAN
>
editor with appropriate editing mode. On some systems
these tools are provided in a typical full installation.
</P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN75267"
>G.4.1. Emacs/PSGML</A
></H2
><P
> <SPAN
CLASS="PRODUCTNAME"
>PSGML</SPAN
> is the most common and most
powerful mode for editing <ACRONYM
CLASS="ACRONYM"
>SGML</ACRONYM
> documents.
When properly configured, it will allow you to use
<SPAN
CLASS="APPLICATION"
>Emacs</SPAN
> to insert tags and check markup
consistency. You could use it for <ACRONYM
CLASS="ACRONYM"
>HTML</ACRONYM
> as
well. Check the <A
HREF="http://www.lysator.liu.se/projects/about_psgml.html"
TARGET="_top"
>PSGML
web site</A
> for downloads, installation instructions, and
detailed documentation.
</P
><P
> There is one important thing to note with
<SPAN
CLASS="PRODUCTNAME"
>PSGML</SPAN
>: its author assumed that your
main <ACRONYM
CLASS="ACRONYM"
>SGML</ACRONYM
> <ACRONYM
CLASS="ACRONYM"
>DTD</ACRONYM
> directory
would be <TT
CLASS="FILENAME"
>/usr/local/lib/sgml</TT
>. If, as in the
examples in this chapter, you use
<TT
CLASS="FILENAME"
>/usr/local/share/sgml</TT
>, you have to
compensate for this, either by setting
<TT
CLASS="ENVAR"
>SGML_CATALOG_FILES</TT
> environment variable, or you
can customize your <SPAN
CLASS="PRODUCTNAME"
>PSGML</SPAN
> installation
(its manual tells you how).
</P
><P
> Put the following in your <TT
CLASS="FILENAME"
>~/.emacs</TT
>
environment file (adjusting the path names to be appropriate for
your system):
</P><PRE
CLASS="PROGRAMLISTING"
>; ********** for SGML mode (psgml)
(setq sgml-omittag t)
(setq sgml-shorttag t)
(setq sgml-minimize-attributes nil)
(setq sgml-always-quote-attributes t)
(setq sgml-indent-step 1)
(setq sgml-indent-data t)
(setq sgml-parent-document nil)
(setq sgml-default-dtd-file "./reference.ced")
(setq sgml-exposed-tags nil)
(setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))
(setq sgml-ecat-files nil)
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )</PRE
><P>
and in the same file add an entry for <ACRONYM
CLASS="ACRONYM"
>SGML</ACRONYM
>
into the (existing) definition for
<TT
CLASS="VARNAME"
>auto-mode-alist</TT
>:
</P><PRE
CLASS="PROGRAMLISTING"
>(setq
auto-mode-alist
'(("\\.sgml$" . sgml-mode)
))</PRE
><P>
</P
><P
> Currently, each <ACRONYM
CLASS="ACRONYM"
>SGML</ACRONYM
> source file has the
following block at the end of the file:
</P><PRE
CLASS="PROGRAMLISTING"
><!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
--></PRE
><P>
This will set up a number of editing mode parameters even if you
do not set up your <TT
CLASS="FILENAME"
>~/.emacs</TT
> file, but it is
a bit unfortunate, since if you followed the installation
instructions above, then the catalog path will not match your
location. Hence you might need to turn off local variables:
</P><PRE
CLASS="PROGRAMLISTING"
>(setq inhibit-local-variables t)</PRE
><P>
</P
><P
> The <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> distribution includes a
parsed DTD definitions file <TT
CLASS="FILENAME"
>reference.ced</TT
>.
You may find that when using <SPAN
CLASS="PRODUCTNAME"
>PSGML</SPAN
>, a
comfortable way of working with these separate files of book
parts is to insert a proper <TT
CLASS="LITERAL"
>DOCTYPE</TT
>
declaration while you're editing them. If you are working on
this source, for instance, it is an appendix chapter, so you
would specify the document as an <SPAN
CLASS="QUOTE"
>"appendix"</SPAN
> instance
of a DocBook document by making the first line look like this:
</P><PRE
CLASS="PROGRAMLISTING"
><!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN"></PRE
><P>
This means that anything and everything that reads
<ACRONYM
CLASS="ACRONYM"
>SGML</ACRONYM
> will get it right, and I can verify the
document with <TT
CLASS="COMMAND"
>nsgmls -s docguide.sgml</TT
>. (But
you need to take out that line before building the entire
documentation set.)
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN75303"
>G.4.2. Other Emacs modes</A
></H2
><P
> <SPAN
CLASS="PRODUCTNAME"
>GNU Emacs</SPAN
> ships with a different
<ACRONYM
CLASS="ACRONYM"
>SGML</ACRONYM
> mode, which is not quite as powerful as
<SPAN
CLASS="PRODUCTNAME"
>PSGML</SPAN
>, but it's less confusing and
lighter weight. Also, it offers syntax highlighting (font lock),
which can be very helpful.
</P
><P
> Norm Walsh offers a major <A
HREF="http://nwalsh.com/emacs/docbookide/index.html"
TARGET="_top"
>mode
specifically for DocBook</A
> which also has font-lock and a
number of features to reduce typing.
</P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="docguide-build.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="docguide-style.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Building The Documentation</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="docguide.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Style Guide</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
