Building The Documentation

PostgreSQL 7.2 Documentation
Prev | Appendix B. Documentation | Next

# B.3. 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

  > Note: The official Postscript format documentation is generated differently. See Section B.3.3 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.

## B.3.1. 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.

## B.3.2. 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.

## B.3.3. Hardcopy Generation

The hardcopy Postscript documentation is generated by converting the SGML source code to RTF, then importing into ApplixWare. 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.

1. Generate the RTF input by typing (for example):

       % cd doc/src/sgml
       % make tutorial.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:

       % cd doc/src/sgml
       % fixrtf tutorial.rtf

   or

       % cd doc/src/sgml
       % fixrtf --refentry reference.rtf

   The script adds `{\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. For repairing `REFENTRY` sections, the script replaces `\keepn` tags with `\keep`.

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

4. Generate a new 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.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.

   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:

      Table B-1. Indent Formatting for Table of Contents

      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.

   - Insert figures into the document. Center each figure on the page using the centering margins button on the ApplixWare toolbar.

     > Note: 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.

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 per document.

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 Applix Words format to allow easier last minute editing later.

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

11. Compress the Postscript file using gzip. Place the compressed file into the `doc` directory.

## B.3.4. 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`. For the file `src/test/regress/README` the command is `gmake regress_README`.

Prev | Home | Next
Toolsets | Up | Documentation Authoring