Documentation
PostgreSQL has four primary documentation
formats:
Plain text, for pre-installation information
HTML, for on-line browsing and reference
Postscript, for printing
man pages, for quick reference.
Additionally, a number of plain-text README-type files can be found
throughout the PostgreSQL source tree,
documenting various implementation issues.
The documentation is organized into several books
:
Tutorial: introduction for new users
User's Guide: documents the query language environment
Reference Manual: documents the query language
Administrator's Guide: installation and server maintenance
Programmer's Guide: programming client
applications and server extensions
Developer's Guide: assorted information
for developers of PostgreSQL proper
All books are available as HTML and Postscript. The
Reference Manual contains reference entries which
are also shipped as man pages.
HTML documentation and man pages are part of a
standard distribution and are installed by default. Postscript
format documentation is available separately for download.
DocBook
The documentation sources are written in
DocBook, which is a markup language
superficially similar to HTML. Both of these
languages are applications of the Standard Generalized
Markup Language, SGML, 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.
DocBook 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 OASIS group. The official DocBook
site has good introductory and reference documentation and
a complete O'Reilly book for your online reading pleasure. The
FreeBSD
Documentation Project also uses DocBook and has some good
information, including a number of style guidelines that might be
worth considering.
Toolsets
The following tools are used to process the documentation. Some
may be optional, as noted.
DocBook DTD
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 XML version of DocBook
-- do not use that.
ISO 8879 character entities
These are required by DocBook but are distributed separately
because they are maintained by ISO.
Jade
This is the base package of SGML processing.
It contains an SGML parser, a
DSSSL processor (that is, a program to
convert SGML to other formats using
DSSSL stylesheets), as well as a number of
related tools. Jade is now being
maintained by the OpenJade group, no longer by James Clark.
Norm Walsh's Modular DocBook Stylesheets
These contain the processing instructions for converting the
DocBook sources to other formats, such as
HTML.
DocBook2X tools
This optional package is used to create man pages. It has a
number of prerequisite packages of its own. Check the web
site.
JadeTeX
If you want to, you can also install
JadeTeX to use
TeX as a formatting backend for
Jade. This will generate printed
output that is inferior to what you get from the
RTF backend. Tables are a particular
problem area. Also, there is no opportunity to manually polish
the results. Still, it works all right, especially for simpler
documents that don't use tables, and as both
JadeTeX and the style sheets are
under continuous improvement, it will certainly get better over
time.
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.
Linux RPM Installation
Many vendors provide a complete RPM set for DocBook processing in
their distribution, which is usually based on the docbook-tools
effort at Red Hat Software. Look for an SGML
option while installing, or the following packages:
sgml-common, docbook,
stylesheets, openjade
(or jade). Possibly
sgml-tools 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 large, reasonably compatible vendor.
FreeBSD Installation
The FreeBSD Documentation Project is itself a heavy user of
DocBook, so it comes as no surprise that there is a full set of
ports
of the documentation tools available on
FreeBSD. The following ports need to be installed to build the
documentation on FreeBSD.
textproc/sp
textproc/openjade
textproc/docbook-310
textproc/iso8879
textproc/dsssl-docbook-modular
A number of things from /usr/ports/print
(tex, jadetex) might
also be of interest.
It's possible that the ports do not update the main catalog file
in /usr/local/share/sgml/catalog. Be sure to
have the following line in there:
CATALOG "/usr/local/share/sgml/docbook/3.1/catalog"
If you do not want to edit the file you can also set the
environment variable SGML_CATALOG_FILES to a
colon-separated list of catalog files (such as the one above).
More information about the FreeBSD documentation tools can be
found in the FreeBSD
Documentation Project's instructions.
Debian Packages
There is a full set of packages of the documentation tools
available for Debian GNU/Linux.
To install, simply use:
apt-get install jade
apt-get install docbook
apt-get install docbook-stylesheets
Manual Installation from Source
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 reasonabley standard
installation paths, and no fancy
features. For
details, you should study the documentation of the respective
package, and read SGML introductory material.
Installing Jade
The installation of OpenJade offers a GNU-style
./configure; make; make install build process.
Details can be found in the OpenJade source distribution. In a
nutshell:
./configure --enable-default-catalog=/usr/local/share/sgml/catalog
make
make install
Be sure to remember where you put the default
catalog
; you will need it below. You can also leave it
off, but then you will have to set the environment variable
SGML_CATALOG_FILES to point to the file whenever
you use jade later on.
Additionally, you should install the files
dsssl.dtd, fot.dtd,
style-sheet.dtd, and
catalog from the dsssl
directory somewhere, perhaps into
/usr/local/share/sgml/dsssl. (Or just copy
the entire directory.)
Installing the DocBook DTD Kit
Obtain the DocBook
V3.1 distribution.
Unpack the archive.
$ unzip -a docbk31.zip
Place the files into the directory
/usr/local/share/sgml/docbook31. (The
exact location is irrelevant, but this one is fairly standard.)
Create a file
/usr/local/share/sgml/catalog (or whatever
you told jade during installation) and put a line like this
into it:
CATALOG "docbook31/docbook.cat"
Optionally, you can edit the file
docbook.cat and comment out or remove the
line containing DTDDECL. If you do not then
you will get warnings from jade, but
there is no further harm.
Download the ISO 8879
character entities archive, unpack it, and put the
files in the same directory you put the DocBook files in.
Installing Norman Walsh's DSSSL Style Sheets
To install the style sheets, simply unzip the distribution kit in
a suitable place, for example
/usr/local/share/sgml/stylesheets. (The
archive will automatically create a docbook
subdirectory.)
Installing JadeTeX
To install and use JadeTeX, you will
need a working installation of TeX and
LaTeX2e, including the supported
tools and
graphics packages,
Babel,
AMS fonts and
AMS-LaTeX, the
PSNFSS extension
and companion kit of the 35 fonts
, the
dvips program for generating
PostScript, the macro packages
fancyhdr,
hyperref,
minitoc,
url and
ot2enc, and of course
JadeTeX itself. All of these can be
found on your friendly neighborhood CTAN site.
JadeTeX does not at the time of
writing come with much of an installation guide, but there is a
makefile that shows what is needed. It
also includes a directory cooked, wherein
you'll find some of the macro packages it needs, but not all, and
not complete -- at least last we looked.
Before building the jadetex.fmt format file,
you'll probably want to edit the jadetex.ltx
file, to change the configuration of
Babel to suit your locality. The line
to change looks something like
\RequirePackage[german,french,english]{babel}[1997/01/23]
and you should obviously list only the languages you actually need,
and have configured Babel for.
It is quite likely that when you use
JadeTeX with
PostgreSQL documentation sources, that
TeX will stop during the second run,
and tell you that its capacity has been exceeded. This is, as
far as we can tell, because of the way
JadeTeX generates cross referencing
information. TeX can, of course, be
compiled with larger data structure sizes. The details of this
will vary according to your installation.
Building The Documentation
Before you can build the documentation you need to run the
configure script as you would when building
the programs themselves. Check the output near the end of the run,
it should look something like this:
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
If neither onsgmls nor
nsgmls were found then you will not see the
remaining 4 lines. nsgmls is part of the Jade
package. If DocBook V3.1
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
DOCBOOKSTYLE to the location and rerun
configure afterwards.
Once you have everything set up, change to the directory
doc/src/sgml and run one of the following
commands: (Remember to use GNU make.)
To build the HTML version of the
Administrator's Guide:
doc/src/sgml$ gmake admin.html
For the RTF version of the same:
doc/src/sgml$ gmake admin.rtf
To get a DVI version via
JadeTeX:
doc/src/sgml$ gmake admin.dvi
And Postscript from the DVI:
doc/src/sgml$ gmake admin.ps
The official Postscript format documentation is generated
differently. See below.
The other books can be built with analogous commands by replacing
admin with one of developer,
programmer, tutorial, or
user. Using postgres 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.
HTML
When building HTML documentation in
doc/src/sgml, 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 HTML documentation packages
use the commands
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
In the distribution, these archives live in the
doc directory and are installed by default
with gmake install.
Manpages
We use the docbook2man utility to
convert DocBook
REFENTRY pages to *roff output suitable for man
pages. The man pages are also distributed as a tar archive,
similar to the HTML version. To create the man page package, use the commands
cd doc/src
gmake man
which will result in a tar file being generated in the
doc/src directory.
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.
Hardcopy Generation
The hardcopy Postscript documentation is generated by converting the
SGML source code to RTF, then
importing into ApplixWare-4.4.1.
After a little cleanup (see the following
section) the output is "printed" to a postscript file.
Several areas are addressed while generating Postscript
hardcopy, including RTF repair, ToC generation, and page break
adjustments.
Applixware RTF Cleanup
jade, 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 ApplixWare folks the symptom was diagnosed and a
workaround is available.
Generate the RTF input by typing (for example):
% cd doc/src/sgml
% make tutorial.rtf
Repair the RTF file to correctly specify all
styles, in particular the default style. The field can be added
using vi or the following small
sed procedure:
#!/bin/sh
# fixrtf.sh
# Utility to repair slight damage in RTF files generated by jade
# Thomas Lockhart <lockhart@alumni.caltech.edu>
#
for i in $* ; do
mv $i $i.orig
cat $i.orig | sed 's#\\stylesheet#\\stylesheet{\\s0 Normal;}#' > $i
done
exit
where the script is adding {\s0 Normal;} as
the zero-th style in the document. According to ApplixWare, the
RTF standard would prohibit adding an implicit zero-th style,
though M$Word happens to handle this case.
Open a new document in Applix Words and
then import the RTF file.
Generate a new ToC using ApplixWare.
Select the existing ToC lines, from the beginning of the first
character on the first line to the last character of the last
line.
Build a new ToC using
Tools.BookBuilding.CreateToC. 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
ApplixWare ToC.
Adjust the ToC formatting by using
Format.Style, selecting each of the three
ToC styles, and adjusting the indents for First and
Left. Use the following values:
Indent Formatting for Table of Contents
Style
First Indent (inches)
Left Indent (inches)
TOC-Heading 1
0.6
0.6
TOC-Heading 2
1.0
1.0
TOC-Heading 3
1.4
1.4
Work through the document to:
Adjust page breaks.
Adjust table column widths.
Insert figures into the document. Center each figure on the page using
the centering margins button on the ApplixWare toolbar.
Not all documents have figures.
You can grep the SGML source files for
the string "graphic" to identify those parts of the
documentation that may have figures. A few figures are replicated in
various parts of the documentation.
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.
If a bibliography is present, remove the short
form reference title from each entry. The
DocBook stylesheets from Norm Walsh
seem to print these out, even though this is a subset of the
information immediately following.
Save the document as native Applix Words format to allow easier last
minute editing later.
"Print" the document
to a file in Postscript format.
Compress the Postscript file using gzip.
Place the compressed file into the doc directory.
Plain Text Files
Several files are distributed as plain text, for reading during
the installation process. The INSTALL file
corresponds to the chapter in the Administrator's
Guide, with some minor changes to account for the
different context. To recreate the file, change to the directory
doc/src/sgml and enter gmake
INSTALL. This will create a file
INSTALL.html that can be saved as text with
Netscape Navigator and put into the
place of the existing file. Netscape
seems to offer the best quality for HTML to
text conversions (over lynx and
w3m).
The file HISTORY can be created similarly,
using the command gmake HISTORY. The table
of contents should be removed manually from the resulting text
file.
Since it does not change very often, the generation of the file
src/test/regress/README is not fully
automated. After building the HTML version of
the Administrator's Guide, convert the
resulting files regress.html and
regress-platform.html to text, using
Netscape. Then paste the text files
together and edit them to taste (e.g., remove the navigation
bars, remove the references to other chapters).
Documentation Authoring
SGML and DocBook do
not suffer from an oversupply of open-source authoring tools. The
most common toolset is the
Emacs/XEmacs
editor with appropriate editing mode. On some systems
(e.g., RedHat Linux) these tools are provided in a typical full
installation.
Emacs/PSGML
PSGML is the most common and most
powerful mode for editing SGML documents.
When properly configured, it will allow you to use
Emacs to insert tags and check markup
consistancy. You could use it for HTML as
well. Check the PSGML
web site for downloads, installation instructions, and
detailed documentation.
There is one important thing to note with
PSGML: its author assumed that your
main SGML DTD directory
would be /usr/local/lib/sgml. If, as in the
examples in this chapter, you use
/usr/local/share/sgml, you have to
compensate for this, either by setting
SGML_CATALOG_FILES environment variable, or you
can customize your PSGML installation
(its manual tells you how).
Put the following in your ~/.emacs
environment file (adjusting the path names to be appropriate for
your system):
; ********** 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 )
and in the same file add an entry for SGML
into the (existing) definition for
auto-mode-alist:
(setq
auto-mode-alist
'(("\\.sgml$" . sgml-mode)
))
Currently, each SGML source file has the
following block at the end of the file:
<!-- 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:
-->
This will set up a number of editing mode parameters even if you
do not set up your ~/.emacs 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:
(setq inhibit-local-variables t)
The PostgreSQL distribution includes a
parsed DTD definitions file reference.ced.
You may find that when using PSGML, a comfortable way of working
with these separate files of book parts is to insert a proper
DOCTYPE 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
appendix
instance of a DocBook document by making
the first line look like this:
<!doctype appendix PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
This means that anything and everything that reads
SGML will get it right, and I can verify the
document with nsgmls -s docguide.sgml. (But
you need to take out that line before building the entire
documentation set.)
Other Emacs modes
GNU Emacs ships with a different SGML
mode, which is not quite as powerful as
PSGML, but it's less confusing and
lighter weight. Also, it offers syntax highlighting (font lock),
which can be very helpful.
Norm Walsh offers a major mode
specifically for DocBook which also has font-lock and a
number of features to reduce typing.