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:

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.

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

We use the docbook2man
utility to convert DocBookREFENTRY 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.

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.

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.

Select the ToC field.

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

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

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

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.