<HTML
><HEAD
><TITLE
>Documentation Authoring</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.73
"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 7.3.2 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Documentation"
HREF="docguide.html"><LINK
REL="PREVIOUS"
TITLE="Building The Documentation"
HREF="doc-build.html"><LINK
REL="NEXT"
TITLE="Style Guide"
HREF="doc-style.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
NAME="creation"
CONTENT="2003-02-03T20:17:34"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>PostgreSQL 7.3.2 Documentation</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="doc-build.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Appendix B. Documentation</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="doc-style.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="DOC-SOURCES"
>B.4. Documentation Authoring</A
></H1
><P
> <SPAN
CLASS="ACRONYM"
>SGML</SPAN
> 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="AEN56749"
>B.4.1. Emacs/PSGML</A
></H2
><P
> <SPAN
CLASS="PRODUCTNAME"
>PSGML</SPAN
> is the most common and most
powerful mode for editing <SPAN
CLASS="ACRONYM"
>SGML</SPAN
> 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 <SPAN
CLASS="ACRONYM"
>HTML</SPAN
> 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 <SPAN
CLASS="ACRONYM"
>SGML</SPAN
> <SPAN
CLASS="ACRONYM"
>DTD</SPAN
> 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 <SPAN
CLASS="ACRONYM"
>SGML</SPAN
>
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 <SPAN
CLASS="ACRONYM"
>SGML</SPAN
> 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 PSGML, 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 V3.1//EN"></PRE
><P>
This means that anything and everything that reads
<SPAN
CLASS="ACRONYM"
>SGML</SPAN
> 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="AEN56784"
>B.4.2. Other Emacs modes</A
></H2
><P
> <SPAN
CLASS="PRODUCTNAME"
>GNU Emacs</SPAN
> ships with a different SGML
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="doc-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="doc-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
>
