PostgreSQL 7.1.3 Documentation
Prev | Appendix DG2. Documentation | Next

# DG2.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 DG2.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.

## DG2.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.

## DG2.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.

## DG2.3.3. Hardcopy Generation

The hardcopy Postscript documentation is generated by converting the SGML source code to RTF, then importing into ApplixWare-4.4.1. 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. The field can be added using vi or the following small sed procedure:

       #!/bin/sh
       # fixrtf.sh
       # Utility to repair slight damage in RTF files generated by jade
       # Thomas Lockhart <lockhart@alumni.caltech.edu>
       #
       for i in $* ; do
         mv $i $i.orig
         cat $i.orig | sed 's#\\stylesheet#\\stylesheet{\\s0 Normal;}#' > $i
       done

       exit

   where the script is adding `{\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.

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 DG2-1. Indent Formatting for Table of Contents

      Style | First Indent (inches) | Left Indent (inches)
      --- | --- | ---
      `TOC-Heading 1` | `0.6` | `0.6`
      `TOC-Heading 2` | `1.0` | `1.0`
      `TOC-Heading 3` | `1.4` | `1.4`

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. If a bibliography is present, remove the short form reference title from each entry. The DocBook stylesheets from Norm Walsh seem to print these out, even though this is a subset of the information immediately following.

8. Save the document as native Applix Words format to allow easier last minute editing later.

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

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

## DG2.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`. The table of contents should be removed manually from the resulting text file.

Since it does not change very often, the generation of the file `src/test/regress/README` is not fully automated. After building the HTML version of the Administrator's Guide, convert the resulting files `regress.html` and `regress-platform.html` to text, using Netscape. Then paste the text files together and edit them to taste (e.g., remove the navigation bars, remove the references to other chapters).

Prev | Home | Next
Toolsets | Up | Documentation Authoring