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$
make html
This is also the default target. The output appears in the
subdirectory html
.
To create a proper index, the build might process several identical
stages. If you do not care about the index, and just want to
proof-read the output, use draft
:
doc/src/sgml$
make draft
To build the documentation as a single HTML page, use:
doc/src/sgml$
make postgres.html
We use the DocBook XSL stylesheets 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
pages, use the commands:
cd doc/src/sgml make man
If you want to use JadeTex to produce a printable rendition of the documentation, you can use one of the following commands:
To generate PostScript via DVI in A4 format:
doc/src/sgml$
make postgres-A4.ps
In U.S. letter format:
doc/src/sgml$
make postgres-US.ps
To make a PDF:
doc/src/sgml$
make postgres-A4.pdf
or:
doc/src/sgml$
make postgres-US.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.)
When using JadeTeX to build the PostgreSQL documentation, you will
probably need to increase some of TeX's internal parameters. These
can be set in the file texmf.cnf
. The following
settings worked at the time of this writing:
hash_extra.jadetex = 200000 hash_extra.pdfjadetex = 200000 pool_size.jadetex = 2000000 pool_size.pdfjadetex = 2000000 string_vacancies.jadetex = 150000 string_vacancies.pdfjadetex = 150000 max_strings.jadetex = 300000 max_strings.pdfjadetex = 300000 save_size.jadetex = 15000 save_size.pdfjadetex = 15000
Occasionally text is too wide for the printed margins, and in
extreme cases, too wide for the printed page, e.g. non-wrapped
text, wide tables. Overly wide text generates “Overfull
hbox” messages in the TeX log output file, e.g.
postgres-US.log
or postgres-A4.log
.
There are 72 points in an inch so anything reported as over 72
points too wide will probably not fit on the printed page (assuming
one inch margins). To find the SGML text
causing the overflow, find the first page number mentioned above
the overflow message, e.g. [50 ###]
(page 50), and
look at the page after that (e.g. page 51) in the PDF
file to see the overflow text and adjust the SGML
accordingly.
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 might have hit that problem. (But keep in mind that a normal build takes 5 to 10 minutes, so don't abort too soon.)
Procedure J.1. 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$
make 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.
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 INSTALL
file
corresponds to Chapter 15, Installation from Source Code, with some minor
changes to account for the different context. To recreate the
file, change to the directory doc/src/sgml
and enter make INSTALL
.
In the past, the release notes and regression testing instructions were also distributed as plain text, but this practice has been discontinued.