Once you have everything set up, change to the directory
doc/src/sgml
and run one of the commands
described in the following subsections to build the
documentation. (Remember to use GNU make.)
To build the HTML version of the documentation:
doc/src/sgml$
gmake html
This is also the default target.
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 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.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.
If you want to use JadeTex to produce a printable rendition of the documentation, you can use one of the following commands:
To make a DVI version:
doc/src/sgml$
gmake postgres.dvi
To generate Postscript from the DVI:
doc/src/sgml$
gmake postgres.ps
To make a PDF:
doc/src/sgml$
gmake postgres.pdf
(Of course you can also make a PDF version from the Postscript, but if you generate PDF directly, it will have hyperlinks and other enhanced features.)
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.
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.)
Applixware RTF 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 Applixware ToC.
→ → . 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 Adjust the ToC formatting by using
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
→ → .Unbind the ToC by selecting
→ → .Delete the first line in the ToC, which is an entry for the ToC itself.
Save the document as native Applixware Words format to allow easier last minute editing later.
“Print” the document to a file in Postscript format.
Several files are distributed as plain text, for reading during
the installation process. The INSTALL
file
corresponds to Chapter 14, Installation Instructions, 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
.