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.

Generate the RTF input by typing (for example):

% cd doc/src/sgml
% make tutorial.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:
```
% 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.
Open a new document in Applixware Words and then import the RTF file.

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

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`

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.
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.
Delete the index section from the document if it is empty.
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.
Save the document as native Applixware Words format to allow easier last minute editing later.
"Print" the document to a file in Postscript format.
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.