When the HTML documentation is built, the process also
generates the linking information for the index entries. Thus,
if you want your documentation to have a concept index at the
end, you need to build the HTML documentation once, and then
build the documentation again in whatever format you like.

To allow for easier handling in the final distribution, the
files comprising the HTML documentation are stored in a tar
archive that is unpacked at installation time. To create the
HTML documentation package,
use the commands

cd doc/src
gmake postgres.tar.gz

In the distribution, these archives live in the doc directory and are installed by default with
gmake install.

We use the docbook2man
utility to convert DocBookrefentry 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.tar.gz

which will result in a tar file being generated in the
doc/src directory.

To generate quality man pages, it might be necessary to use
a hacked version of the conversion utility or do some manual
postprocessing. All man pages should be manually inspected
before distribution.

You can also create a printable version of the PostgreSQL documentation by converting it
to RTF and applying minor
formatting corrections using an office suite. Depending on the
capabilities of the particular office suite, you can then
convert the documentation to Postscript of PDF. The procedure below illustrates this
process using Applixware.

Note: It appears that current versions of the
PostgreSQL documentation
trigger some bug in or exceed the size limit of OpenJade.
If the build process of the RTF version hangs for a long time and
the output file still has size 0, then you may have hit
that problem. (But keep in mind that a normal build takes 5
to 10 minutes, so don't abort too soon.)

ApplixwareRTF Cleanup

OpenJade omits specifying
a default style for body text. In the past, this undiagnosed
problem led to a long process of table of contents
generation. However, with great help from the Applixware folks the symptom was
diagnosed and a workaround is available.

Generate the RTF
version by typing:

doc/src/sgml$ gmake postgres.rtf

Repair the RTF file to correctly specify all styles,
in particular the default style. If the document contains
refentry sections, one must
also replace formatting hints which tie a preceding
paragraph to the current paragraph, and instead tie the
current paragraph to the following one. A utility,
fixrtf, is available in
doc/src/sgml to accomplish
these repairs:

doc/src/sgml$ ./fixrtf --refentry postgres.rtf

The script adds {\s0 Normal;}
as the zeroth style in the document. According to
Applixware, the RTF
standard would prohibit adding an implicit zeroth style,
though Microsoft Word happens to handle this case. For
repairing refentry sections,
the script replaces \keepn tags
with \keep.

Open a new document in Applixware Words and then import the
RTF file.

Generate a new table of contents (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->Book Building->Create Table of Contents. 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:

Style

First Indent (inches)

Left Indent (inches)

TOC-Heading
1

0.4

0.4

TOC-Heading
2

0.8

0.8

TOC-Heading
3

1.2

1.2

Work through the document to:

Adjust page breaks.

Adjust table column widths.

Replace the right-justified page numbers in the
Examples and Figures portions of the ToC with correct
values. This only takes a few minutes.

Delete the index section from the document if it is
empty.

Regenerate and adjust the table of contents.

Select the ToC field.

Select Tools->Book Building->Create Table of Contents.

Unbind the ToC by selecting Tools->Field Editing->Unprotect.

Delete the first line in the ToC, which is an
entry for the ToC itself.

Several files are distributed as plain text, for reading
during the installation process. The INSTALL file corresponds to Chapter 14, 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. For the file src/test/regress/README the command is
gmake regress_README.

Submit correction

If you see anything in the documentation that is not correct, does not match
your experience with the particular feature or requires further clarification,
please use
this form
to report a documentation issue.