Building The Documentation

PostgreSQL 8.4.2 Documentation
Prev | Fast Backward | Appendix I. Documentation | Fast Forward | Next

# I.3. Building The Documentation

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.)

## I.3.1. HTML

To build the HTML version of the documentation:

    doc/src/sgml$ gmake html

This is also the default target.

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$ gmake draft

To allow for easier handling in the final distribution, the files comprising the HTML documentation can be 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`.

## I.3.2. Manpages

We use the docbook2man-sgmlspl utility from the DocBook2X project 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
    gmake man D2MDIR=directory

Use the `D2MDIR` variable to specify the name of the directory where the file `docbook2man-spec.pl` from the docbook2man-sgmlspl package resides. There is no default for that. Since that package is not available or outdated in many packaging systems, you might want to just download the source code tarball and unpack it. No building is required. Then the path is something like `D2MDIR=/home/you/somewhere/docbook2man-sgmlspl-1.0/perl`. You may get warnings like this:

    Warning: unrecognized SDATA '[scaron]': please add definition to docbook2man-spec.pl
    Warning: unrecognized SDATA '[ouml  ]': please add definition to docbook2man-spec.pl

which can ignore if (and only if) you are using the latest version of `docbook2man-spec.pl` and you are not seeing any other SDATA warnings besides those.

To create the man page package for a release, use the following commands:

    cd doc/src
    gmake man.tar.gz D2MDIR=directory

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

## I.3.3. Print Output via JadeTeX

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$ gmake postgres-A4.ps

  In U.S. letter format:

      doc/src/sgml$ gmake postgres-US.ps

- To make a PDF:

      doc/src/sgml$ gmake postgres-A4.pdf

  or:

      doc/src/sgml$ gmake 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

## I.3.4. Print Output via RTF

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 might 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.

1. Generate the RTF version by typing:

       doc/src/sgml$ gmake postgres.rtf

2. 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`.

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

4. Generate a new table of contents (ToC) using Applixware.

   1. Select the existing ToC lines, from the beginning of the first character on the first line to the last character of the last line.

   2. 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.

   3. 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`

5. Work through the document to:

   - Adjust page breaks.

   - Adjust table column widths.

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

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

8. Regenerate and adjust the table of contents.

   1. Select the ToC field.

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

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

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

9. Save the document as native Applixware Words format to allow easier last minute editing later.

10. "Print" the document to a file in PostScript format.

## I.3.5. Plain Text Files

Several files are distributed as plain text, for reading during the installation process. The `INSTALL` file corresponds to Chapter 15, 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`.

## I.3.6. Syntax Check

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:

    doc/src/sgml$ gmake check

Prev | Home | Next
Tool Sets | Up | Documentation Authoring