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

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