$Header: /tmp/.n/n/macke/disk2/sam/flexkit/gman/RCS/README-INDEX,v 1.2 91/07/08 15:06:39 sam Exp $

Building A Database From Scratch
--------------------------------
A set of rules for doing this for /usr/catman is in the Makefile, look
under catman-db; as in,

    % make catman-db

You must create a "db" directory at the top of the manual tree.  For
example,

    % mkdir /usr/catman/db

Next, setup the file that describes how the man pages in the tree are
to be divided into sections.  A section is a logical grouping that's
used to limit searching and for obtaining table-of-contents listings.
A prototypical section description file exists in the PROTO-DB
directory,

    % cp PROTO-DB/Sections /usr/catman/db/Sections

If your Sections file defines sections other than those listed in
PROTO-DB/Sections, you may want to install icons for the section -- one
for the section button (66x60) and one for the small scrolling list
(~20x20).  The convention is to name button faces with a .but suffix
and small section icons with a .sec suffix.  Samples of the builtin
images can be found in PROTO-DB/SectionIcons.  Note that you should NOT
install these images -- they are built into gman.  Doing so will not
hurt anything, but it will make gman's take longer to startup.  Note
also, that you can override any of the builtin images simply by
installing images w/ the appropriate name in the SecionIcons
directory.

Last, create a ``stop list database''.  This database contains words
that you do NOT want to be included in the inverted keyword indexes.
The mkstop program is used to build a stop list.  To recreate the
default stop list database,

    % cat PROTO-DB/{connectives,manualstops} | mkstop /usr/catman/db/stop

Finally, create the databases ....

Creating the databases is a two step process.  First you must create a
table of contents file for each manual section defined in the Sections
file.  This file must be built first because the second database (the
keyword index) references files through the toc database.

The maketoc shell script can be used to create toc files for
catman-style manual trees.  It's designed to be run from the top of the
tree (e.g.  /usr/catman) and takes one or more section names, e.g.
cat1, as arguments (if no arguments are given, it creates a toc for all
sections).  Note that maketoc uses the tocman program from *this*
directory; it'll need to be in your search path.

The tocman program does the actual work in updating/creating toc
database files.  It's usage is (but see also the manual page):

    tocman [-d database-name] [-v]

Tocman expects a list of pathnames on its standard input that it should
examine.  The specified pathnames should be pre-nroffed "pcat"-able or
"zcat"-able manual pages, or troff source that is formatted with the
standard manual (-man) macros.  A sample use is:

    % cd /usr/catman
    % tocman -d db/cat1
    ./cat1/a_man/clri.z
    ./cat1/a_man/bootp.z
    ...

Once the toc has been setup you can, if you want, create a keyword
index for each section.  This database is not necessary, but it makes
the browser much more useful and also makes it run faster.  To create a
keyword index you can use the makeix shell script.  It works just like
the maketoc script; for example:

    % cd /usr/catman
    % makeix cat1 cat3

Similar to the tocman program, there is an ixman program.  Read the
manual page for a complete decription of its operation and options.
