help \- an easy way to find and use information
\fB] [ \-i ] [ \-n ] [ \-q ] [\fP
is to provide easy access to on-line documentation.
In response to the command
the user is placed in an interactive
setting and presented with a list of topics and a set of instructions
To bypass the interactive part and just display what is known about
a topic, enter the topic name on the command line after \fBhelp\fP.
A topic is displayed by typing its name or a unique abbreviation,
and topics may be requested and listed with numbers.
Topics may be saved in a file or printed on the lineprinter.
When you request a topic not on its list,
can search a set of indexes into its own files,
the Unix Programmer's Manual, and various optional off-line sources.
References found in this way can be displayed if material is available on-line.
All topic requests, including ones which yield no useful information,
are automatically recorded for later analysis by system maintainers.
Any user may effectively add topics to \fBhelp\fP's knowledge base
from that user's point of view by suitably defining the environment
Thus each user can have a private cache of topic files accessible with
In general the purpose of
is to provide a way to move around easily in a set of
hierarchical databases, namely, one or more Unix file system subtrees.
Although an inherent disadvantage of such databases is that data may be
hidden within the hierarchies, the program
overcomes this to some extent with its indexing feature.
can be made to serve in special purpose
applications without programmer intervention.
The following technical description may be of little interest to casual users.
The default knowledge base consists of the files and directories in
the subtree /usr/lib/help/cat.
If the environment variable HELPPOOL contains a list of directories
(separated by spaces or colons), their contents are merged with the
default list to form the knowledge base.
The entire directory pool may be overridden by giving a
The interactive user prompt is by default the tail of argument zero from
usually ``help'', followed by a list of directories leading
to the current subtopic directory.
A different prompt may be specified by making a link with a name of your
choice to /usr/ucb/help or by specifying a name after the
A special prompt is used in help-index mode,
which is entered when the user initiates an index search
The string ``-index'' and the keyword are added to the prompt
may be invoked with any number of
etc., arguments, which may be abbreviated.
Starting at the top directory level
tries to change to each directory named by successive arguments,
interactively resolving non-unique abbreviations along the way.
When a name corresponds to a file, the file is displayed and, unless
was specified, the program exits.
If the standard output is not a terminal,
refuses to be interactive unless the
If the last valid name is a directory, or no topics were requested,
lists the topics at the current level and prompts for user input.
knowledge bases can use the
option to perform various custodial functions using shell scripts.
Permission to use this option is restricted to those users who
have write permission for one of the directories in the list specified
If such a directory exists, it (the first one) becomes the value
of the variable $subtree, and the local maintenance configuration
is sourced from $subtree/../maint/config before most functions are performed.
The function name, given as
may be followed by other arguments (but no topic abbreviations
are recognized here), in which case the script
$subtree/../maint/do.\fIkey\fP is invoked.
the word ``default'' is used, usually causing
the valid function choices to be listed.
A simple macro package called
is used by authors to format
Its purpose is to standardize somewhat the display format for topic files,
create a hook for the index generating script, and
guarantee page headers and footers of a fixed length so that
will not strip out too much or too little of a topic file
when displaying it without pagination.
The only macro call required is the initializing macro,
followed by a filename and an optional date on the same line,
and by a keyword-rich title (to be useful for the index) on the next line.
A handful of other macros are provided for compatibility with other packages,
though they are usually unnecessary.
topics may make topic files into shell scripts by entering a # or :
at the beginning of the first line.
This causes help to run the script when that topic is requested,
allowing programs to be demonstrated, questions asked, etc.
There are maintenance scripts which will convert a script with embedded
source text into a script with embedded formatted text, provided
the lines to be formatted appear between the special
lines ``##nroff'' and ``##''.
Similarly, authors may use programs as topic files, the source
being written in an aribtrary programming language.
option causes topics to be listed and accessible by numbers
(and still accessible by unique abbreviations).
option suppresses the instruction line appearing before each prompt,
including the prompt printed by the
through which long output is piped after multiple
blank lines in a row are reduced to one.
Both of these features are available as instructions from within
The internal instructions are described below.
Quit from help and return to the shell.
may be the shortest unique name
abbreviating a topic at the current level.
prompts for more characters if a non-unique name is given,
and asks to look in the index if the name abbreviates no topic.
If a name is given as = in any context other than index mode,
the current topic is used,
where the current topic is defined to be the one most recently accessed.
In index mode, a name of = has no special significance, and if
is a unique abbreviation for a reference, that reference
Enter index mode and see what more is known about
by looking in the indexes.
A missing topic is taken to be =.
A missing topic is taken to be =, and a missing
file is taken to be ``helpsave''.
exists the topic file is appended to it.
preserving headers and footers.
Normally, topics are stored as
text files, the headers and footers of
which are suppressed when displayed on a terminal.
on the lineprinter, preserving headers and footers.
string may be replaced with another program name (such as
followed by one optional argument.
is taken to be the current topic, and a missing
List the internal instructions and describe them briefly.
List topics at the current level, indicating the current
topic, if any, with an =.
In index mode, list references for the current subject.
Back up to and list the next higher level of topics.
From index mode, this means leave index mode and continue
at the previous topic level.
Back up to and list the top level of topics.
From index mode, this means leave index mode and continue
at the top level of topics.
Send comments or other input to the maintainer of
All occurrences of = inside
will be replaced by the current topic, if any.
\fB\(**\fP flag \fBon\fP/\fBoff\fP
to adjust the behavior of the program.
means invert its current value, and \fB\(**\fP by itself
means display the current flags, their settings, and
There are currently two flags,
which control the same things as the
/usr/lib/help/cat root of system \fIhelp\fP files
/usr/lib/help/src nroff sources for system \fIhelp\fP files
/usr/lib/help/log log of user requests; can be removed
/usr/lib/help/maint maintenance scripts
/usr/lib/help/cat/general general introduction to \fIhelp\fP
/usr/lib/help/cat/index_\(** used to locate further references
/usr/lib/tmac/tmac.ayday macro package for \fIhelp\fP files
environ(7), exec(3), learn(1), lpr(1), more(1), nroff(1)
Pathnames inside topic names are not recognized.
is really just a weak, friendly shell.
Strengthening it might be more painful and less useful
than civilizing the shell.