cde8bbc413
- more work from the SGML police - some grammar improvements: rewriting a paragraph or two, replacing contractions where (IMHO) appropriate - fix missing utility commands in lock mode docs - improve CLUSTER, REINDEX, SET SESSION AUTHORIZATION ref pages Neil Conway
1465 lines
45 KiB
Plaintext
1465 lines
45 KiB
Plaintext
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.43 2003/02/19 04:06:27 momjian Exp $ -->
|
|
|
|
<appendix id="docguide">
|
|
<title>Documentation</title>
|
|
|
|
<para>
|
|
<productname>PostgreSQL</productname> has four primary documentation
|
|
formats:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Plain text, for pre-installation information
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<acronym>HTML</acronym>, for on-line browsing and reference
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Postscript, for printing
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
man pages, for quick reference.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
Additionally, a number of plain-text README-type files can be found
|
|
throughout the <productname>PostgreSQL</productname> source tree,
|
|
documenting various implementation issues.
|
|
</para>
|
|
|
|
<para>
|
|
The documentation is organized into several <quote>books</quote>:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<citetitle>Tutorial</citetitle>: introduction for new users
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<citetitle>User's Guide</citetitle>: documents the SQL implementation
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<citetitle>Reference Manual</citetitle>: reference pages for programs and SQL commands
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<citetitle>Administrator's Guide</citetitle>: installation and server maintenance
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<citetitle>Programmer's Guide</citetitle>: programming client
|
|
applications and server extensions
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<citetitle>Developer's Guide</citetitle>: assorted information
|
|
for developers of <productname>PostgreSQL</> proper
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
All books are available as HTML and Postscript. The
|
|
<citetitle>Reference Manual</citetitle> contains reference entries which
|
|
are also shipped as man pages.
|
|
</para>
|
|
|
|
<para>
|
|
<acronym>HTML</acronym> documentation and man pages are part of a
|
|
standard distribution and are installed by default. Postscript
|
|
format documentation is available separately for download.
|
|
</para>
|
|
|
|
<sect1>
|
|
<title>DocBook</title>
|
|
<para>
|
|
The documentation sources are written in
|
|
<firstterm>DocBook</firstterm>, which is a markup language
|
|
superficially similar to <acronym>HTML</acronym>. Both of these
|
|
languages are applications of the <firstterm>Standard Generalized
|
|
Markup Language</firstterm>, <acronym>SGML</acronym>, which is
|
|
essentially a language for describing other languages. In what
|
|
follows, the terms DocBook and SGML are both used, but technically
|
|
they are not interchangeable.
|
|
</para>
|
|
|
|
<para>
|
|
<productname>DocBook</productname> allows an author to specify the
|
|
structure and content of a technical document without worrying
|
|
about presentation details. A document style defines how that
|
|
content is rendered into one of several final forms. DocBook is
|
|
maintained by the <ulink
|
|
url="http://www.oasis-open.org">OASIS</ulink> group. The <ulink
|
|
url="http://www.oasis-open.org/docbook">official DocBook
|
|
site</ulink> has good introductory and reference documentation and
|
|
a complete O'Reilly book for your online reading pleasure. The
|
|
<ulink url="http://www.freebsd.org/docproj/docproj.html">FreeBSD
|
|
Documentation Project</ulink> also uses DocBook and has some good
|
|
information, including a number of style guidelines that might be
|
|
worth considering.
|
|
</para>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="doc-toolsets">
|
|
<title>Tool Sets</title>
|
|
|
|
<para>
|
|
The following tools are used to process the documentation. Some
|
|
may be optional, as noted.
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><ulink url="http://www.oasis-open.org/docbook/sgml/">DocBook DTD</ulink></term>
|
|
<listitem>
|
|
<para>
|
|
This is the definition of DocBook itself. We currently use
|
|
version 3.1; you cannot use later or earlier versions. Note
|
|
that there is also an <acronym>XML</acronym> version of DocBook
|
|
-- do not use that.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO 8879 character entities</ulink></term>
|
|
<listitem>
|
|
<para>
|
|
These are required by DocBook but are distributed separately
|
|
because they are maintained by ISO.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><ulink url="http://openjade.sourceforge.net">OpenJade</ulink></term>
|
|
<listitem>
|
|
<para>
|
|
This is the base package of <acronym>SGML</acronym> processing.
|
|
It contains an <acronym>SGML</acronym> parser, a
|
|
<acronym>DSSSL</acronym> processor (that is, a program to
|
|
convert <acronym>SGML</acronym> to other formats using
|
|
<acronym>DSSSL</acronym> stylesheets), as well as a number of
|
|
related tools. <productname>Jade</productname> is now being
|
|
maintained by the OpenJade group, no longer by James Clark.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><ulink url="http://docbook.sourceforge.net/projects/dsssl/index.html">DocBook DSSSL Stylesheets</ulink></term>
|
|
<listitem>
|
|
<para>
|
|
These contain the processing instructions for converting the
|
|
DocBook sources to other formats, such as
|
|
<acronym>HTML</acronym>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><ulink url="http://docbook2x.sourceforge.net">DocBook2X tools</ulink></term>
|
|
<listitem>
|
|
<para>
|
|
This optional package is used to create man pages. It has a
|
|
number of prerequisite packages of its own. Check the web
|
|
site.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><ulink url="http://jadetex.sourceforge.net">JadeTeX</ulink></term>
|
|
<listitem>
|
|
<para>
|
|
If you want to, you can also install
|
|
<productname>JadeTeX</productname> to use
|
|
<productname>TeX</productname> as a formatting backend for
|
|
<productname>Jade</productname>.
|
|
<application>JadeTeX</application> can create Postscript or
|
|
<acronym>PDF</acronym> files (the latter with bookmarks).
|
|
</para>
|
|
|
|
<para>
|
|
However, the output from <application>JadeTeX</application> is
|
|
inferior to what you get from the <acronym>RTF</acronym>
|
|
backend. Particular problem areas are tables and various
|
|
artifacts of vertical and horizontal spacing. Also, there is
|
|
no opportunity to manually polish the results.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
We have documented experience with several installation methods for
|
|
the various tools that are needed to process the documentation.
|
|
These will be described below. There may be some other packaged
|
|
distributions for these tools. Please report package status to the
|
|
docs mailing list and we will include that information here.
|
|
</para>
|
|
|
|
<sect2>
|
|
<title><productname>Linux</productname> <acronym>RPM</acronym> Installation</title>
|
|
|
|
<para>
|
|
Many vendors provide a complete RPM set for DocBook processing in
|
|
their distribution, which is usually based on the <ulink
|
|
url="http://sources.redhat.com/docbook-tools/">docbook-tools</ulink>
|
|
effort at Red Hat Software. Look for an <quote>SGML</quote>
|
|
option while installing, or the following packages:
|
|
<filename>sgml-common</filename>, <filename>docbook</filename>,
|
|
<filename>stylesheets</filename>, <filename>openjade</filename>
|
|
(or <filename>jade</filename>). Possibly
|
|
<filename>sgml-tools</filename> will be needed as well. If your
|
|
distributor does not provide these then you should be able to make
|
|
use of the packages from some other, reasonably compatible vendor.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>FreeBSD Installation</title>
|
|
|
|
<para>
|
|
The FreeBSD Documentation Project is itself a heavy user of
|
|
DocBook, so it comes as no surprise that there is a full set of
|
|
<quote>ports</quote> of the documentation tools available on
|
|
FreeBSD. The following ports need to be installed to build the
|
|
documentation on FreeBSD.
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><filename>textproc/sp</filename></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><filename>textproc/openjade</filename></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><filename>textproc/docbook-310</filename></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><filename>textproc/iso8879</filename></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><filename>textproc/dsssl-docbook-modular</filename></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
A number of things from <filename>/usr/ports/print</filename>
|
|
(<filename>tex</filename>, <filename>jadetex</filename>) might
|
|
also be of interest.
|
|
</para>
|
|
|
|
<para>
|
|
It's possible that the ports do not update the main catalog file
|
|
in <filename>/usr/local/share/sgml/catalog</filename>. Be sure to
|
|
have the following line in there:
|
|
<programlisting>
|
|
CATALOG "/usr/local/share/sgml/docbook/3.1/catalog"
|
|
</programlisting>
|
|
If you do not want to edit the file you can also set the
|
|
environment variable <envar>SGML_CATALOG_FILES</envar> to a
|
|
colon-separated list of catalog files (such as the one above).
|
|
</para>
|
|
|
|
<para>
|
|
More information about the FreeBSD documentation tools can be
|
|
found in the <ulink
|
|
url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/tools.html">FreeBSD
|
|
Documentation Project's instructions</ulink>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Debian Packages</title>
|
|
|
|
<para>
|
|
There is a full set of packages of the documentation tools
|
|
available for <productname>Debian GNU/Linux</productname>.
|
|
To install, simply use:
|
|
<programlisting>
|
|
apt-get install jade
|
|
apt-get install docbook
|
|
apt-get install docbook-stylesheets
|
|
</programlisting>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Manual Installation from Source</title>
|
|
|
|
<para>
|
|
The manual installation process of the DocBook tools is somewhat
|
|
complex, so if you have pre-built packages available, use them.
|
|
We describe here only a standard setup, with reasonably standard
|
|
installation paths, and no <quote>fancy</quote> features. For
|
|
details, you should study the documentation of the respective
|
|
package, and read <acronym>SGML</acronym> introductory material.
|
|
</para>
|
|
|
|
<sect3>
|
|
<title>Installing OpenJade</title>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>
|
|
The installation of OpenJade offers a GNU-style
|
|
<literal>./configure; make; make install</literal> build
|
|
process. Details can be found in the OpenJade source
|
|
distribution. In a nutshell:
|
|
<synopsis>
|
|
./configure --enable-default-catalog=/usr/local/share/sgml/catalog
|
|
make
|
|
make install
|
|
</synopsis>
|
|
Be sure to remember where you put the <quote>default
|
|
catalog</quote>; you will need it below. You can also leave
|
|
it off, but then you will have to set the environment variable
|
|
<envar>SGML_CATALOG_FILES</envar> to point to the file
|
|
whenever you use <application>jade</application> later on.
|
|
(This method is also an option if OpenJade is already
|
|
installed and you want to install the rest of the toolchain
|
|
locally.)
|
|
</para>
|
|
</step>
|
|
|
|
<step id="doc-openjade-install">
|
|
<para>
|
|
Additionally, you should install the files
|
|
<filename>dsssl.dtd</filename>, <filename>fot.dtd</filename>,
|
|
<filename>style-sheet.dtd</filename>, and
|
|
<filename>catalog</filename> from the
|
|
<filename>dsssl</filename> directory somewhere, perhaps into
|
|
<filename>/usr/local/share/sgml/dsssl</filename>. It's
|
|
probably easiest to copy the entire directory:
|
|
<synopsis>
|
|
cp -R dsssl /usr/local/share/sgml
|
|
</synopsis>
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Finally, create the file
|
|
<filename>/usr/local/share/sgml/catalog</filename> and add
|
|
this line to it:
|
|
<programlisting>
|
|
CATALOG "dsssl/catalog"
|
|
</programlisting>
|
|
(This is a relative path reference to the file installed in
|
|
<xref linkend="doc-openjade-install">. Be sure to adjust it
|
|
if you chose your installation layout differently.)
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>
|
|
Obtain the <ulink
|
|
url="http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip">DocBook
|
|
V3.1</ulink> distribution.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Create the directory
|
|
<filename>/usr/local/share/sgml/docbook31</filename> and change
|
|
to it. (The exact location is irrelevant, but this one is
|
|
reasonable within the layout we are following here.)
|
|
<screen>
|
|
<prompt>$ </prompt><userinput>mkdir /usr/local/share/sgml/docbook31</userinput>
|
|
<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook31</userinput>
|
|
</screen>
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Unpack the archive.
|
|
<screen>
|
|
<prompt>$ </prompt><userinput>unzip -a ...../docbk31.zip</userinput>
|
|
</screen>
|
|
(The archive will unpack its files into the current directory.)
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Edit the file
|
|
<filename>/usr/local/share/sgml/catalog</filename> (or whatever
|
|
you told jade during installation) and put a line like this
|
|
into it:
|
|
<programlisting>
|
|
CATALOG "docbook31/docbook.cat"
|
|
</programlisting>
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Optionally, you can edit the file
|
|
<filename>docbook.cat</filename> and comment out or remove the
|
|
line containing <literal>DTDDECL</literal>. If you do not then
|
|
you will get warnings from <application>jade</application>, but
|
|
there is no further harm.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Download the <ulink
|
|
url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO 8879
|
|
character entities</ulink> archive, unpack it, and put the
|
|
files in the same directory you put the DocBook files in.
|
|
<screen>
|
|
<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook31</userinput>
|
|
<prompt>$ </prompt><userinput>unzip ...../ISOEnts.zip</userinput>
|
|
</screen>
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Run the following command in the directory with the DocBook and ISO files:
|
|
<programlisting>
|
|
perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
|
|
</programlisting>
|
|
(This fixes a mixup between the names used in the DocBook
|
|
catalog file and the actual names of the ISO character entity
|
|
files.)
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>Installing the DocBook <acronym>DSSSL</acronym> Style Sheets</title>
|
|
|
|
<para>
|
|
To install the style sheets, unzip and untar the distribution and
|
|
move it to a suitable place, for example
|
|
<filename>/usr/local/share/sgml</filename>. (The archive will
|
|
automatically create a subdirectory.)
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>gunzip docbook-dsssl-1.<replaceable>xx</>.tar.gz</userinput>
|
|
<prompt>$</prompt> <userinput>tar -C /usr/local/share/sgml -xf docbook-dsssl-1.<replaceable>xx</>.tar</userinput>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
The usual catalog entry in
|
|
<filename>/usr/local/share/sgml/catalog</filename> can also be
|
|
made:
|
|
<programlisting>
|
|
CATALOG "docbook-dsssl--1.<replaceable>xx</>/catalog
|
|
</programlisting>
|
|
Because stylesheets change rather often, and it's sometimes
|
|
beneficial to try out alternative versions,
|
|
<productname>PostgreSQL</productname> doesn't use this catalog
|
|
entry. See <xref linkend="doc-build"> for information about how
|
|
to select the stylesheets instead.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>Installing <productname>JadeTeX</productname></title>
|
|
|
|
<para>
|
|
To install and use <productname>JadeTeX</productname>, you will
|
|
need a working installation of <productname>TeX</productname> and
|
|
<productname>LaTeX2e</productname>, including the supported
|
|
<productname>tools</productname> and
|
|
<productname>graphics</productname> packages,
|
|
<productname>Babel</productname>,
|
|
<productname><acronym>AMS</acronym> fonts</productname> and
|
|
<productname>AMS-LaTeX</productname>, the
|
|
<productname><acronym>PSNFSS</acronym></productname> extension
|
|
and companion kit of <quote>the 35 fonts</quote>, the
|
|
<productname>dvips</productname> program for generating
|
|
<productname>PostScript</productname>, the macro packages
|
|
<productname>fancyhdr</productname>,
|
|
<productname>hyperref</productname>,
|
|
<productname>minitoc</productname>,
|
|
<productname>url</productname> and
|
|
<productname>ot2enc</productname>. All of these can be found on
|
|
your friendly neighborhood <ulink
|
|
url="http://www.ctan.org"><acronym>CTAN</acronym></ulink> site.
|
|
The installation of the <application>TeX</application> base
|
|
system is far beyond the scope of this introduction. Binary
|
|
packages should be available for any system that can run
|
|
<application>TeX</application>.
|
|
</para>
|
|
|
|
<para>
|
|
Before you can use <application>JadeTeX</application> with the
|
|
<productname>PostgreSQL</productname> documentation sources, you
|
|
will need to increase the size of
|
|
<application>TeX</application>'s internal data structures.
|
|
Details on this can be found in the <application>JadeTeX</application>
|
|
installation instructions.
|
|
</para>
|
|
|
|
<para>
|
|
Once that is finished you can install <application>JadeTeX</application>:
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>gunzip jadetex-<replaceable>xxx</replaceable>.tar.gz</userinput>
|
|
<prompt>$</prompt> <userinput>tar xf jadetex-<replaceable>xxx</replaceable>.tar</userinput>
|
|
<prompt>$</prompt> <userinput>cd jadetex</userinput>
|
|
<prompt>$</prompt> <userinput>make install</userinput>
|
|
<prompt>$</prompt> <userinput>mktexlsr</userinput>
|
|
</screen>
|
|
The last two need to be done as <systemitem>root</systemitem>.
|
|
</para>
|
|
|
|
</sect3>
|
|
|
|
</sect2>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="doc-build">
|
|
<title>Building The Documentation</title>
|
|
|
|
<para>
|
|
Before you can build the documentation you need to run the
|
|
<filename>configure</filename> script as you would when building
|
|
the programs themselves. Check the output near the end of the run,
|
|
it should look something like this:
|
|
<screen>
|
|
<computeroutput>
|
|
checking for onsgmls... onsgmls
|
|
checking for openjade... openjade
|
|
checking for DocBook V3.1... yes
|
|
checking for DocBook stylesheets... /usr/lib/sgml/stylesheets/nwalsh-modular
|
|
checking for sgmlspl... sgmlspl
|
|
</computeroutput>
|
|
</screen>
|
|
If neither <filename>onsgmls</filename> nor
|
|
<filename>nsgmls</filename> were found then you will not see the
|
|
remaining 4 lines. <filename>nsgmls</filename> is part of the Jade
|
|
package. If <quote>DocBook V3.1</quote> was not found then you did
|
|
not install the DocBook DTD kit in a place where jade can find it,
|
|
or you have not set up the catalog files correctly. See the
|
|
installation hints above. The DocBook stylesheets are looked for
|
|
in a number of relatively standard places, but if you have them
|
|
some other place then you should set the environment variable
|
|
<envar>DOCBOOKSTYLE</envar> to the location and rerun
|
|
<filename>configure</filename> afterwards.
|
|
</para>
|
|
|
|
<para>
|
|
Once you have everything set up, change to the directory
|
|
<filename>doc/src/sgml</filename> and run one of the following
|
|
commands: (Remember to use GNU make.)
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
To build the <acronym>HTML</acronym> version of the
|
|
<citetitle>Administrator's Guide</citetitle>:
|
|
<screen>
|
|
<prompt>doc/src/sgml$ </prompt><userinput>gmake admin.html</userinput>
|
|
</screen>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
For the RTF version of the same:
|
|
<screen>
|
|
<prompt>doc/src/sgml$ </prompt><userinput>gmake admin.rtf</userinput>
|
|
</screen>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
To get a <acronym>DVI</acronym> version via
|
|
<productname>JadeTeX</productname>:
|
|
<screen>
|
|
<prompt>doc/src/sgml$ </prompt><userinput>gmake admin.dvi</userinput>
|
|
</screen>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
And Postscript from the <acronym>DVI</acronym>:
|
|
<screen>
|
|
<prompt>doc/src/sgml$ </prompt><userinput>gmake admin.ps</userinput>
|
|
</screen>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
The official Postscript format documentation is generated
|
|
differently. See <xref linkend="doc-hardcopy"> below.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
The other books can be built with analogous commands by replacing
|
|
<literal>admin</literal> with one of <literal>developer</literal>,
|
|
<literal>programmer</literal>, <literal>tutorial</literal>, or
|
|
<literal>user</literal>. Using <literal>postgres</literal> builds
|
|
an integrated version of all 5 books, which is practical since the
|
|
browser interface makes it easy to move around all of the
|
|
documentation by just clicking.
|
|
</para>
|
|
|
|
<sect2>
|
|
<title>HTML</title>
|
|
|
|
<para>
|
|
When building <acronym>HTML</acronym> documentation in
|
|
<filename>doc/src/sgml</filename>, some of the resulting files
|
|
will possibly (or quite certainly) have conflicting names between
|
|
books. Therefore the files are not in that directory in the
|
|
regular distribution. Instead, the files belonging to each book
|
|
are stored in a tar archive that is unpacked at installation time.
|
|
To create a set of <acronym>HTML</acronym> documentation packages
|
|
use the commands
|
|
<programlisting>
|
|
cd doc/src
|
|
gmake tutorial.tar.gz
|
|
gmake user.tar.gz
|
|
gmake admin.tar.gz
|
|
gmake programmer.tar.gz
|
|
gmake postgres.tar.gz
|
|
gmake install
|
|
</programlisting>
|
|
In the distribution, these archives live in the
|
|
<filename>doc</filename> directory and are installed by default
|
|
with <command>gmake install</command>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="doc-manpages">
|
|
<title>Manpages</title>
|
|
|
|
<para>
|
|
We use the <application>docbook2man</application> utility to
|
|
convert <productname>DocBook</productname>
|
|
<sgmltag>REFENTRY</sgmltag> pages to *roff output suitable for man
|
|
pages. The man pages are also distributed as a tar archive,
|
|
similar to the <acronym>HTML</acronym> version. To create the man page package, use the commands
|
|
<programlisting>
|
|
cd doc/src
|
|
gmake man
|
|
</programlisting>
|
|
which will result in a tar file being generated in the
|
|
<filename>doc/src</filename> directory.
|
|
</para>
|
|
|
|
<para>
|
|
The man build leaves a lot of confusing output, and special care
|
|
must be taken to produce quality results. There is still room for
|
|
improvement in this area.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="doc-hardcopy">
|
|
<title>Hardcopy Generation</title>
|
|
|
|
<para>
|
|
The hardcopy Postscript documentation is generated by converting the
|
|
<acronym>SGML</acronym> source code to <acronym>RTF</acronym>, then
|
|
importing into <productname>Applixware</productname>.
|
|
After a little cleanup (see the following
|
|
section) the output is <quote>printed</quote> to a postscript file.
|
|
</para>
|
|
|
|
<!--
|
|
<para>
|
|
Some figures were redrawn to avoid having bitmap
|
|
<acronym>GIF</acronym> files in the hardcopy documentation. One
|
|
figure, of the system catalogs, was sufficiently complex that there
|
|
was not time to redraw it. It was converted to fit using the
|
|
following commands:
|
|
|
|
<programlisting>
|
|
% convert -monochrome -v -geometry 500x500'>' catalogs.ps catalogs.gif
|
|
% convert -v -crop 400x500 catalogs.gif catalogs-cropped.gif
|
|
</programlisting>
|
|
|
|
</para>
|
|
-->
|
|
|
|
<para>
|
|
Several areas are addressed while generating Postscript
|
|
hardcopy, including RTF repair, ToC generation, and page break
|
|
adjustments.
|
|
</para>
|
|
|
|
<procedure>
|
|
<title><productname>Applixware</productname> <acronym>RTF</acronym> Cleanup</title>
|
|
|
|
<para>
|
|
<application>jade</application>, an integral part of the
|
|
hardcopy procedure, omits specifying a default style for body
|
|
text. In the past, this undiagnosed problem led to a long process
|
|
of Table of Contents (ToC) generation. However, with great help
|
|
from the <productname>Applixware</productname> folks the symptom was diagnosed and a
|
|
workaround is available.
|
|
</para>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Generate the <acronym>RTF</acronym> input by typing (for example):
|
|
<programlisting>
|
|
% cd doc/src/sgml
|
|
% make tutorial.rtf
|
|
</programlisting>
|
|
</para>
|
|
</step>
|
|
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Repair the RTF file to correctly specify all
|
|
styles, in particular the default style. If the document
|
|
contains <sgmltag>REFENTRY</sgmltag> sections, one must also
|
|
replace formatting hints which tie a
|
|
<emphasis>preceding</emphasis> paragraph to the current
|
|
paragraph, and instead tie the current paragraph to the
|
|
following one. A utility, <application>fixrtf</application> is
|
|
available in
|
|
<filename>doc/src/sgml</filename> to accomplish these repairs:
|
|
|
|
<programlisting>
|
|
% cd doc/src/sgml
|
|
% fixrtf tutorial.rtf
|
|
</programlisting>
|
|
|
|
or
|
|
|
|
<programlisting>
|
|
% cd doc/src/sgml
|
|
% fixrtf --refentry reference.rtf
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
The script adds <literal>{\s0 Normal;}</literal> as
|
|
the zero-th style in the document. According to <productname>Applixware</productname>, the
|
|
RTF standard would prohibit adding an implicit zero-th style,
|
|
though M$Word happens to handle this case. For repairing
|
|
<sgmltag>REFENTRY</sgmltag> sections, the script replaces
|
|
<literal>\keepn</literal> tags with <literal>\keep</literal>.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Open a new document in <productname>Applixware Words</productname> and
|
|
then import the <acronym>RTF</acronym> file.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Generate a new ToC using <productname>Applixware</productname>.
|
|
</para>
|
|
|
|
<substeps>
|
|
<step>
|
|
<para>
|
|
Select the existing ToC lines, from the beginning of the first
|
|
character on the first line to the last character of the last
|
|
line.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Build a new ToC using
|
|
<literal>Tools.BookBuilding.CreateToC</literal>. Select the
|
|
first three levels of headers for inclusion in the ToC.
|
|
This will
|
|
replace the existing lines imported in the RTF with a native
|
|
<productname>Applixware</productname> ToC.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Adjust the ToC formatting by using
|
|
<literal>Format.Style</literal>, selecting each of the three
|
|
ToC styles, and adjusting the indents for <literal>First</literal> and
|
|
<literal>Left</literal>. Use the following values:
|
|
|
|
<table>
|
|
<title>Indent Formatting for Table of Contents</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
Style
|
|
</entry>
|
|
<entry>
|
|
First Indent (inches)
|
|
</entry>
|
|
<entry>
|
|
Left Indent (inches)
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<literal>TOC-Heading 1</literal>
|
|
</entry>
|
|
<entry>
|
|
<literal>0.4</literal>
|
|
</entry>
|
|
<entry>
|
|
<literal>0.4</literal>
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>
|
|
<literal>TOC-Heading 2</literal>
|
|
</entry>
|
|
<entry>
|
|
<literal>0.8</literal>
|
|
</entry>
|
|
<entry>
|
|
<literal>0.8</literal>
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>
|
|
<literal>TOC-Heading 3</literal>
|
|
</entry>
|
|
<entry>
|
|
<literal>1.2</literal>
|
|
</entry>
|
|
<entry>
|
|
<literal>1.2</literal>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
</step>
|
|
</substeps>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Work through the document to:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Adjust page breaks.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Adjust table column widths.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Insert figures into the document. Center each figure on the page using
|
|
the centering margins button on the <productname>Applixware</productname> toolbar.
|
|
|
|
<note>
|
|
<para>
|
|
Not all documents have figures.
|
|
You can grep the <acronym>SGML</acronym> source files for
|
|
the string <literal>graphic</literal> to identify those parts of the
|
|
documentation that may have figures. A few figures are replicated in
|
|
various parts of the documentation.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Replace the right-justified page numbers in the Examples and
|
|
Figures portions of the ToC with
|
|
correct values. This only takes a few minutes per document.
|
|
</para>
|
|
</step>
|
|
|
|
<!--
|
|
Later stylesheets seem to not need this adjustment - thomas 2001-11-29
|
|
<step performance="required">
|
|
<para>
|
|
If a bibliography is present, remove the <firstterm>short
|
|
form</firstterm> reference title from each entry. The
|
|
<productname>DocBook</productname> stylesheets from Norm Walsh
|
|
seem to print these out, even though this is a subset of the
|
|
information immediately following.
|
|
</para>
|
|
</step>
|
|
-->
|
|
|
|
<step performance="optional">
|
|
<para>
|
|
Delete the index section from the document if it is empty.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Regenerate and adjust the table of contents.
|
|
</para>
|
|
|
|
<substeps>
|
|
<step>
|
|
<para>
|
|
Select the ToC field.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Select
|
|
<literal>Tools->Book Building->Create Table of
|
|
Contents</literal>.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Unbind the ToC by selecting
|
|
<literal>Tools->Field Editing->Unprotect</literal>.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Delete the first line in the ToC, which is an entry for the
|
|
ToC itself.
|
|
</para>
|
|
</step>
|
|
</substeps>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Save the document as native <productname>Applixware Words</productname> format to allow easier last
|
|
minute editing later.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
<quote>Print</quote> the document
|
|
to a file in Postscript format.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Compress the Postscript file using <application>gzip</application>.
|
|
Place the compressed file into the <filename>doc</filename> directory.
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Plain Text Files</title>
|
|
|
|
<para>
|
|
Several files are distributed as plain text, for reading during
|
|
the installation process. The <filename>INSTALL</filename> file
|
|
corresponds to the chapter in the <citetitle>Administrator's
|
|
Guide</citetitle>, with some minor changes to account for the
|
|
different context. To recreate the file, change to the directory
|
|
<filename>doc/src/sgml</filename> and enter <userinput>gmake
|
|
INSTALL</userinput>. This will create a file
|
|
<filename>INSTALL.html</filename> that can be saved as text with
|
|
<productname>Netscape Navigator</productname> and put into the
|
|
place of the existing file. <productname>Netscape</productname>
|
|
seems to offer the best quality for <acronym>HTML</acronym> to
|
|
text conversions (over <application>lynx</application> and
|
|
<application>w3m</application>).
|
|
</para>
|
|
|
|
<para>
|
|
The file <filename>HISTORY</filename> can be created similarly,
|
|
using the command <userinput>gmake HISTORY</userinput>. For the
|
|
file <filename>src/test/regress/README</filename> the command is
|
|
<userinput>gmake regress_README</userinput>.
|
|
</para>
|
|
|
|
<!--
|
|
* This is how you can create text files via RTF and ApplixWare,
|
|
* for historical reference.
|
|
|
|
<procedure>
|
|
<title>Plain Text Generation</title>
|
|
|
|
<para>
|
|
Both <filename>INSTALL</filename> and
|
|
<filename>HISTORY</filename> are generated from existing
|
|
<acronym>SGML</acronym> sources. They are extracted from the same
|
|
intermediate <acronym>RTF</acronym> file.
|
|
</para>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Generate <acronym>RTF</acronym> by typing:
|
|
<programlisting>
|
|
% cd doc/src/sgml
|
|
% make installation.rtf
|
|
</programlisting>
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Import <filename>installation.rtf</filename> into
|
|
<productname>Applix Words</productname>.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Set the page width and margins.
|
|
</para>
|
|
|
|
<substeps>
|
|
<step performance="required">
|
|
<para>
|
|
Adjust the page width in File.PageSetup to 10 inches.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Select all text.
|
|
Adjust the right margin using the ruler to 9.5 inches. This
|
|
will give a maximum column width of 79 characters, within the
|
|
80 columns upper limit goal.
|
|
</para>
|
|
</step>
|
|
</substeps>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Lop off the parts of the document that are not needed.
|
|
</para>
|
|
|
|
<para>
|
|
For <filename>INSTALL</filename>, remove all release notes from
|
|
the end of the text, except for those from the current release.
|
|
For <filename>HISTORY</filename>, remove all text up to the
|
|
release notes, preserving and modifying the title and ToC.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Export the result as <literal>ASCII Layout</literal>.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Using emacs or vi, clean up the tabular information in
|
|
<filename>INSTALL</filename>. Remove the <literal>mailto</literal>
|
|
<acronym>URLs</acronym> for the porting contributors to shrink
|
|
the column heights.
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
-->
|
|
|
|
</sect2>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="doc-sources">
|
|
<title>Documentation Authoring</title>
|
|
|
|
<para>
|
|
<acronym>SGML</acronym> and <productname>DocBook</productname> do
|
|
not suffer from an oversupply of open-source authoring tools. The
|
|
most common tool set is the
|
|
<productname>Emacs</productname>/<productname>XEmacs</productname>
|
|
editor with appropriate editing mode. On some systems
|
|
these tools are provided in a typical full installation.
|
|
</para>
|
|
|
|
<sect2>
|
|
<title>Emacs/PSGML</title>
|
|
|
|
<para>
|
|
<productname>PSGML</productname> is the most common and most
|
|
powerful mode for editing <acronym>SGML</acronym> documents.
|
|
When properly configured, it will allow you to use
|
|
<application>Emacs</application> to insert tags and check markup
|
|
consistency. You could use it for <acronym>HTML</acronym> as
|
|
well. Check the <ulink
|
|
url="http://www.lysator.liu.se/projects/about_psgml.html">PSGML
|
|
web site</ulink> for downloads, installation instructions, and
|
|
detailed documentation.
|
|
</para>
|
|
|
|
<para>
|
|
There is one important thing to note with
|
|
<productname>PSGML</productname>: its author assumed that your
|
|
main <acronym>SGML</acronym> <acronym>DTD</acronym> directory
|
|
would be <filename>/usr/local/lib/sgml</filename>. If, as in the
|
|
examples in this chapter, you use
|
|
<filename>/usr/local/share/sgml</filename>, you have to
|
|
compensate for this, either by setting
|
|
<envar>SGML_CATALOG_FILES</envar> environment variable, or you
|
|
can customize your <productname>PSGML</productname> installation
|
|
(its manual tells you how).
|
|
</para>
|
|
|
|
<para>
|
|
Put the following in your <filename>~/.emacs</filename>
|
|
environment file (adjusting the path names to be appropriate for
|
|
your system):
|
|
|
|
<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 )
|
|
</programlisting>
|
|
|
|
and in the same file add an entry for <acronym>SGML</acronym>
|
|
into the (existing) definition for
|
|
<varname>auto-mode-alist</varname>:
|
|
<programlisting>
|
|
(setq
|
|
auto-mode-alist
|
|
'(("\\.sgml$" . sgml-mode)
|
|
))
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Currently, each <acronym>SGML</acronym> source file has the
|
|
following block at the end of the file:
|
|
|
|
<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:
|
|
-->
|
|
</programlisting>
|
|
This will set up a number of editing mode parameters even if you
|
|
do not set up your <filename>~/.emacs</filename> 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:
|
|
<programlisting>
|
|
(setq inhibit-local-variables t)
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
The <productname>PostgreSQL</productname> distribution includes a
|
|
parsed DTD definitions file <filename>reference.ced</filename>.
|
|
You may find that when using PSGML, a comfortable way of working
|
|
with these separate files of book parts is to insert a proper
|
|
<literal>DOCTYPE</literal> 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
|
|
<quote>appendix</quote> instance of a DocBook document by making
|
|
the first line look like this:
|
|
|
|
<programlisting>
|
|
<!doctype appendix PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
|
|
</programlisting>
|
|
|
|
This means that anything and everything that reads
|
|
<acronym>SGML</acronym> will get it right, and I can verify the
|
|
document with <command>nsgmls -s docguide.sgml</command>. (But
|
|
you need to take out that line before building the entire
|
|
documentation set.)
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Other Emacs modes</title>
|
|
|
|
<para>
|
|
<productname>GNU Emacs</productname> ships with a different SGML
|
|
mode, which is not quite as powerful as
|
|
<productname>PSGML</productname>, but it's less confusing and
|
|
lighter weight. Also, it offers syntax highlighting (font lock),
|
|
which can be very helpful.
|
|
</para>
|
|
|
|
<para>
|
|
Norm Walsh offers a major <ulink
|
|
url="http://nwalsh.com/emacs/docbookide/index.html">mode
|
|
specifically for DocBook</ulink> which also has font-lock and a
|
|
number of features to reduce typing.
|
|
</para>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="doc-style">
|
|
<title>Style Guide</title>
|
|
|
|
<sect2>
|
|
<title>Reference Pages</title>
|
|
|
|
<para>
|
|
Reference pages should follow a standard layout. This allows
|
|
users to find the desired information more quickly, and it also
|
|
encourages writers to document all relevant aspects of a command.
|
|
Consistency is not only desired among
|
|
<productname>PostgreSQL</productname> reference pages, but also
|
|
with reference pages provided by the operating system and other
|
|
packages. Hence the following guidelines have been developed.
|
|
They are for the most part consistent with similar guidelines
|
|
established by various operating systems.
|
|
</para>
|
|
|
|
<para>
|
|
Reference pages that describe executable commands should contain
|
|
the following sections, in this order. Sections that do not apply
|
|
may be omitted. Additional top-level sections should only be used
|
|
in special circumstances; often that information belongs in the
|
|
<quote>Usage</quote> section.
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>Name</term>
|
|
<listitem>
|
|
<para>
|
|
This section is generated automatically. It contains the
|
|
command name and a half-sentence summary of its functionality.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Synopsis</term>
|
|
<listitem>
|
|
<para>
|
|
This section contains the syntax diagram of the command. The
|
|
synopsis should normally not list each command-line option;
|
|
that is done below. Instead, list the major components of the
|
|
command line, such as where input and output files go.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Description</term>
|
|
<listitem>
|
|
<para>
|
|
Several paragraphs explaining what the command does.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Options</term>
|
|
<listitem>
|
|
<para>
|
|
A list describing each command-line option. If there are a
|
|
lot of options, subsections may be used.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Exit Status</term>
|
|
<listitem>
|
|
<para>
|
|
If the program uses 0 for success and non-zero for failure,
|
|
then you do not need to document it. If there is a meaning
|
|
behind the different non-zero exit codes, list them here.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Usage</term>
|
|
<listitem>
|
|
<para>
|
|
Describe any sublanguage or run-time interface of the program.
|
|
If the program is not interactive, this section can usually be
|
|
omitted. Otherwise, this section is a catch-all for
|
|
describing run-time features. Use subsections if appropriate.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Environment</term>
|
|
<listitem>
|
|
<para>
|
|
List all environment variables that the program might use.
|
|
Try to be complete; even seemingly trivial variables like
|
|
<envar>SHELL</envar> might be of interest to the user.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Files</term>
|
|
<listitem>
|
|
<para>
|
|
List any files that the program might access implicitly. That
|
|
is, do not list input and output files that were specified on
|
|
the command line, but list configuration files, etc.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Diagnostics</term>
|
|
<listitem>
|
|
<para>
|
|
Explain any unusual output that the program might create.
|
|
Refrain from listing every possible error message. This is a
|
|
lot of work and has little use in practice. But if, say, the
|
|
error messages have a standard format that the user can parse,
|
|
this would be the place to explain it.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Notes</term>
|
|
<listitem>
|
|
<para>
|
|
Anything that doesn't fit elsewhere, but in particular bugs,
|
|
implementation flaws, security considerations, compatibility
|
|
issues.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Examples</term>
|
|
<listitem>
|
|
<para>
|
|
Examples
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>History</term>
|
|
<listitem>
|
|
<para>
|
|
If there were some major milestones in the history of the
|
|
program, they might be listed here. Usually, this section can
|
|
be omitted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>See Also</term>
|
|
<listitem>
|
|
<para>
|
|
Cross-references, listed in the following order: other
|
|
<productname>PostgreSQL</productname> command reference pages,
|
|
<productname>PostgreSQL</productname> SQL command reference
|
|
pages, citation of <productname>PostgreSQL</productname>
|
|
manuals, other reference pages (e.g., operating system, other
|
|
packages), other documentation. Items in the same group are
|
|
listed alphabetically.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
Reference pages describing SQL commands should contain the
|
|
following sections: Name, Synopsis, Description, Parameters,
|
|
Usage, Diagnostics, Notes, Examples, Compatibility, History, See
|
|
Also. The Parameters section is like the Options section, but
|
|
there is more freedom about which clauses of the command can be
|
|
listed. The Compatibility section should explain to what extent
|
|
this command conforms to the SQL standard(s), or to which other
|
|
database system it is compatible. The See Also section of SQL
|
|
commands should list SQL commands before cross-references to
|
|
programs.
|
|
</para>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
</appendix>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode:sgml
|
|
sgml-omittag:nil
|
|
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:
|
|
-->
|