mkhelpdb: Make (compile) a help database

Package: softools

Usage

mkhelpdb helpdir helpdb

Parameters

helpdir = "lib$root.hd"

The filename of the root help directory file (".hd" file) defining the help tree to be updated. By convention this is root.hd in some directory.

helpdb = "lib$helpdb.mip"

The filename of the help database file to be written. By convention this is helpdb.mip in some directory (the ".mip" signifies that the file format is machine independent).

verbose = no

If this switch is enabled, mkhelpdb will print a detailed description of the help database as it is being compiled. A more concise summary listing only the packages and the number of help modules in each package is printed by default.

Description

The mkhelpdb task descends a tree of help directory (".hd") files and compiles a binary help database from the information therein. The help database is used to speed global searches when help is requested for a module, the ".hlp" file for which might be anywhere in the system. The help database defines the packages and modules in the help database, and stores the filenames of the associated help files. No actual help text is stored in the help database, only sufficient index information to find the help files when the help task is run. The help directory files are text files which define the packages and modules in the help database. The format of these files is self explanatory hence is documented by example only.

By default, mkhelpdb recompiles the standard IRAF help database, although any other similar database may be recompiled by changing the values of the parameters helpdir and helpdb. The standard IRAF help database is rooted in the file lib$root.hd.

The help database must be updated whenever a new help module (e.g., manual page) is added, deleted, or renamed. It is also necessary for sites receiving a source only version of IRAF to run mkhelpdb to rebuild the help database once the system is up, since the database is a binary file and is not included in a source only distribution. It is not necessary to rerun mkhelpdb when an existing manual page is edited, since only index information is stored in the database.

The help utilities make use of the following types of files. Examples of these files will be found throughout the IRAF directories.

.hd             help directory file (tree structured)
.hlp            manual page
.men            package menu (module listing)

Examples

1. Update the standard IRAF help database.

cl> softools
so> mkhelpdb helpdir=lib$root.hd helpdb=lib$helpdb.mip

2. Update the NOAO package help database.

so> mkhelpdb helpdir=noao$lib/root.hd helpdb=noao$lib/helpdb.mip

See also

hdbexamine, help