884 lines
28 KiB
Plaintext
884 lines
28 KiB
Plaintext
<!-- doc/src/sgml/docguide.sgml -->
|
|
|
|
<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>
|
|
PDF, for printing
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
man pages, for quick reference.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
Additionally, a number of plain-text <filename>README</filename> files can
|
|
be found throughout the <productname>PostgreSQL</productname> source tree,
|
|
documenting various implementation issues.
|
|
</para>
|
|
|
|
<para>
|
|
<acronym>HTML</acronym> documentation and man pages are part of a
|
|
standard distribution and are installed by default. PDF
|
|
format documentation is available separately for
|
|
download.
|
|
</para>
|
|
|
|
<sect1 id="docguide-docbook">
|
|
<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 <acronym>SGML</acronym> are both
|
|
used, but technically they are not interchangeable.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
The PostgreSQL documentation is currently being transitioned from DocBook
|
|
SGML and DSSSL style sheets to DocBook XML and XSLT style sheets. Be
|
|
careful to look at the instructions relating to the PostgreSQL version you
|
|
are dealing with, as the procedures and required tools will change.
|
|
</para>
|
|
</note>
|
|
|
|
<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 group</ulink>. 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://newbiedoc.sourceforge.net/metadoc/docbook-guide.html">
|
|
NewbieDoc Docbook Guide</ulink> is very helpful for beginners.
|
|
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="docguide-toolsets">
|
|
<title>Tool Sets</title>
|
|
|
|
<para>
|
|
The following tools are used to process the documentation. Some
|
|
might be optional, as noted.
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><ulink url="http://www.oasis-open.org/docbook/">DocBook DTD</ulink></term>
|
|
<listitem>
|
|
<para>
|
|
This is the definition of DocBook itself. We currently use version
|
|
4.2; you cannot use later or earlier versions. You need
|
|
the <acronym>SGML</acronym> and the <acronym>XML</acronym> variant of
|
|
the DocBook DTD of the same version. These will usually be in separate
|
|
packages.
|
|
</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 SGML but are distributed separately
|
|
because they are maintained by ISO.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><ulink url="http://wiki.docbook.org/DocBookXslStylesheets">DocBook XSL Stylesheets</ulink></term>
|
|
<listitem>
|
|
<para>
|
|
These contain the processing instructions for converting the
|
|
DocBook sources to other formats, such as
|
|
<acronym>HTML</acronym>.
|
|
</para>
|
|
|
|
<para>
|
|
The minimum required version is currently 1.77.0, but it is recommended
|
|
to use the latest available version for best results.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><ulink url="http://openjade.sourceforge.net">OpenSP</ulink></term>
|
|
<listitem>
|
|
<para>
|
|
This is the base package of <acronym>SGML</acronym> processing. Note
|
|
that we no longer need OpenJade, the <acronym>DSSSL</acronym>
|
|
processor, only the OpenSP package for converting SGML to XML.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><ulink url="http://xmlsoft.org/">Libxml2</ulink> for <command>xmllint</command></term>
|
|
<listitem>
|
|
<para>
|
|
This library and the <command>xmllint</command> tool it contains are
|
|
used for processing XML. Many developers will already
|
|
have <application>Libxml2</application> installed, because it is also
|
|
used when building the PostgreSQL code. Note, however,
|
|
that <command>xmllint</command> might need to be installed from a
|
|
separate subpackage.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><ulink url="http://xmlsoft.org/XSLT/">Libxslt</ulink> for <command>xsltproc</command></term>
|
|
<listitem>
|
|
<para>
|
|
<command>xsltproc</command> is an XSLT processor, that is, a program to
|
|
convert XML to other formats using XSLT stylesheets.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><ulink url="https://xmlgraphics.apache.org/fop/">FOP</ulink></term>
|
|
<listitem>
|
|
<para>
|
|
This is a program for converting, among other things, XML to PDF.
|
|
</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 might be some other packaged
|
|
distributions for these tools. Please report package status to the
|
|
documentation mailing list, and we will include that information
|
|
here.
|
|
</para>
|
|
|
|
<para>
|
|
You can get away with not installing DocBook XML and the DocBook XSLT
|
|
stylesheets locally, because the required files will be downloaded from the
|
|
Internet and cached locally. This may in fact be the preferred solution if
|
|
your operating system packages provide only an old version of especially
|
|
the stylesheets or if no packages are available at all. See
|
|
the <option>--nonet</option> option for <command>xmllint</command>
|
|
and <command>xsltproc</command> for more information.
|
|
</para>
|
|
|
|
<sect2>
|
|
<title>Installation on Fedora, RHEL, and Derivatives</title>
|
|
|
|
<para>
|
|
To install the required packages, use:
|
|
<programlisting>
|
|
yum install docbook-dtds docbook-style-xsl fop libxslt opensp
|
|
</programlisting>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Installation on FreeBSD</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/docbook-sgml</filename></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><filename>textproc/docbook-xml</filename></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><filename>textproc/docbook-xsl</filename></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><filename>textproc/dsssl-docbook-modular</filename></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><filename>textproc/libxslt</filename></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><filename>textproc/fop</filename></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><filename>textproc/opensp</filename></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
To install the required packages with <command>pkg</command>, use:
|
|
<programlisting>
|
|
pkg install docbook-sgml docbook-xml docbook-xsl fop libxslt opensp
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
When building the documentation from the <filename>doc</filename>
|
|
directory you'll need to use <command>gmake</command>, because the
|
|
makefile provided is not suitable for FreeBSD's <command>make</command>.
|
|
</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 docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltproc
|
|
</programlisting>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>macOS</title>
|
|
|
|
<para>
|
|
If you use MacPorts, the following will get you set up:
|
|
<programlisting>
|
|
sudo port install docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl fop libxslt opensp
|
|
</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 OpenSP</title>
|
|
|
|
<para>
|
|
The installation of OpenSP offers a GNU-style
|
|
<literal>./configure; make; make install</literal> build process.
|
|
Details can be found in the OpenSP source distribution. In a nutshell:
|
|
<synopsis>
|
|
./configure --enable-default-catalog=/usr/local/etc/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 any programs from OpenSP later on. (This
|
|
method is also an option if OpenSP is already installed and you want to
|
|
install the rest of the toolchain locally.)
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>
|
|
Obtain the <ulink url="http://www.docbook.org/sgml/4.2/docbook-4.2.zip">
|
|
DocBook V4.2 distribution</ulink>.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Create the directory
|
|
<filename>/usr/local/share/sgml/docbook-4.2</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/docbook-4.2</userinput>
|
|
<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput>
|
|
</screen>
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Unpack the archive:
|
|
<screen>
|
|
<prompt>$ </prompt><userinput>unzip -a ...../docbook-4.2.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 "docbook-4.2/docbook.cat"
|
|
</programlisting>
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Download the <ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">
|
|
ISO 8879 character entities archive</ulink>, 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/docbook-4.2</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>
|
|
</sect2>
|
|
|
|
<sect2 id="docguide-toolsets-configure">
|
|
<title>Detection by <command>configure</command></title>
|
|
|
|
<para>
|
|
Before you can build the documentation you need to run the
|
|
<filename>configure</filename> script as you would when building
|
|
the <productname>PostgreSQL</productname> 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 DocBook V4.2... yes
|
|
checking for dbtoepub... dbtoepub
|
|
checking for xmllint... xmllint
|
|
checking for xsltproc... xsltproc
|
|
checking for osx... osx
|
|
checking for fop... fop
|
|
</computeroutput>
|
|
</screen>
|
|
If neither <filename>onsgmls</filename> nor
|
|
<filename>nsgmls</filename> were found then some of the following tests
|
|
will be skipped. <filename>nsgmls</filename> is part of the OpenSP
|
|
package. You can pass the environment variable
|
|
<envar>NSGMLS</envar> to configure to point
|
|
to the programs if they are not found automatically. If
|
|
<quote>DocBook V4.2</quote> was not found then you did not install
|
|
the DocBook DTD kit in a place where OpenSP can find it, or you have
|
|
not set up the catalog files correctly. See the installation hints
|
|
above.
|
|
</para>
|
|
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="docguide-build">
|
|
<title>Building The Documentation</title>
|
|
|
|
<para>
|
|
Once you have everything set up, change to the directory
|
|
<filename>doc/src/sgml</filename> and run one of the commands
|
|
described in the following subsections to build the
|
|
documentation. (Remember to use GNU make.)
|
|
</para>
|
|
|
|
<sect2>
|
|
<title>HTML</title>
|
|
|
|
<para>
|
|
To build the <acronym>HTML</acronym> version of the documentation:
|
|
<screen>
|
|
<prompt>doc/src/sgml$ </prompt><userinput>make html</userinput>
|
|
</screen>
|
|
This is also the default target. The output appears in the
|
|
subdirectory <filename>html</filename>.
|
|
</para>
|
|
|
|
<para>
|
|
To produce HTML documentation with the stylesheet used on <ulink
|
|
url="https://www.postgresql.org/docs/current">postgresql.org</> instead of the
|
|
default simple style use:
|
|
<screen>
|
|
<prompt>doc/src/sgml$ </prompt><userinput>make STYLE=website html</userinput>
|
|
</screen>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Manpages</title>
|
|
|
|
<para>
|
|
We use the DocBook XSL stylesheets 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
|
|
pages, use the commands:
|
|
<screen>
|
|
<prompt>doc/src/sgml$ </prompt><userinput>make man</userinput>
|
|
</screen>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>PDF</title>
|
|
|
|
<para>
|
|
To produce a PDF rendition of the documentation
|
|
using <productname>FOP</productname>, you can use one of the following
|
|
commands, depending on the preferred paper format:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
For A4 format:
|
|
<screen>
|
|
<prompt>doc/src/sgml$ </prompt><userinput>make postgres-A4.pdf</userinput>
|
|
</screen>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
For U.S. letter format:
|
|
<screen>
|
|
<prompt>doc/src/sgml$ </prompt><userinput>make postgres-US.pdf</userinput>
|
|
</screen>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
Because the PostgreSQL documentation is fairly
|
|
big, <productname>FOP</productname> will require a significant amount of
|
|
memory. Because of that, on some systems, the build will fail with a
|
|
memory-related error message. This can usually be fixed by configuring
|
|
Java heap settings in the configuration
|
|
file <filename>~/.foprc</filename>, for example:
|
|
<programlisting>
|
|
# FOP binary distribution
|
|
FOP_OPTS='-Xmx1000m'
|
|
# Debian
|
|
JAVA_ARGS='-Xmx1000m'
|
|
# Red Hat
|
|
ADDITIONAL_FLAGS='-Xmx1000m'
|
|
</programlisting>
|
|
There is a minimum amount of memory that is required, and to some extent
|
|
more memory appears to make things a bit faster. On systems with very
|
|
little memory (less than 1 GB), the build will either be very slow due to
|
|
swapping or will not work at all.
|
|
</para>
|
|
|
|
<para>
|
|
Other XSL-FO processors can also be used manually, but the automated build
|
|
process only supports FOP.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Plain Text Files</title>
|
|
|
|
<para>
|
|
The installation instructions are also distributed as plain text,
|
|
in case they are needed in a situation where better reading tools
|
|
are not available. The <filename>INSTALL</filename> file
|
|
corresponds to <xref linkend="installation">, 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>make INSTALL</userinput>.
|
|
</para>
|
|
|
|
<para>
|
|
In the past, the release notes and regression testing instructions
|
|
were also distributed as plain text, but this practice has been
|
|
discontinued.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Syntax Check</title>
|
|
|
|
<para>
|
|
Building the documentation can take very long. But there is a
|
|
method to just check the correct syntax of the documentation
|
|
files, which only takes a few seconds:
|
|
<screen>
|
|
<prompt>doc/src/sgml$ </prompt><userinput>make check</userinput>
|
|
</screen>
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="docguide-authoring">
|
|
<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-exposed-tags nil)
|
|
(setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))
|
|
|
|
(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>
|
|
You might find that when using <productname>PSGML</productname>, 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 V4.2//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
|
|
<acronym>SGML</acronym> 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.
|
|
<filename>src/tools/editors/emacs.samples</filename> contains
|
|
sample settings for this mode.
|
|
</para>
|
|
|
|
<para>
|
|
Norm Walsh offers a
|
|
<ulink url="http://nwalsh.com/emacs/docbookide/index.html">major mode</ulink>
|
|
specifically for DocBook which also has font-lock and a number of features to
|
|
reduce typing.
|
|
</para>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="docguide-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
|
|
can 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 can 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>Author</term>
|
|
<listitem>
|
|
<para>
|
|
Author (only used in the contrib section)
|
|
</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,
|
|
Outputs, 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 Outputs section is only needed if the command returns
|
|
something other than a default command-completion tag. 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>
|