The help program is invoked from the shell as shown below.
help [ -dlqCn [option-args] ] topic sub-topic sub-sub-topic ...
Topic may be any top-level help file name. A topic-path is a path of topics and their subtopics, down into the tree. Topic and subtopic names may be abbreviated, but no wild-cards are recognized. If any switches are present they all must follow a single dash, and be the first option on the command line.
The options are:
The help interactive mode asks the user what help he would like next. The prompt looks like this:
Help Topic?
or like this:
vi commands deletion subtopic?
Where "vi commands deletion" is the topic-path followed to reach this prompt. The path is printed for each prompt, and as a header for each help text.
The following commands are meaningful in to the "topic?" prompt:
On 4.2BSD Unix systems, help supports a limited form of Twenex-style name-completion. The ESCape character invokes completion of a topic name, the ^D character produces an alphabetized list of possible completions. Completion is called ``limited'' because only a unique abbreviation can be filled out with the ESCape key (unlike the Twenex csh).
HELP FILES
Help files are the text and directories of the help documentation tree. There are four kinds of help files: topic directory, help file, subtopic file, and manual file.
A topic directory is a directory with the name of the subtopic it describes (e.g. /usr/help/ls/options is a topic directory about the topic of options for ls(1)).
A help file is a file of formatted text with the name ".HLP". It resides in the topic directory for which it is the description text.
A subtopic file has the name "subtopic-name.HLP". It contains the text for a subtopic which does not itself have any subtopics.
A manual file contains the commands to be given to
sh(1)
when the user gives the lookup manual command (.).
This file has name <topic>.MANUAL. Therefore the manual command
script for the current node is just ".MANUAL".
A manual file resides in the same topic directory as the help text
whose corresponding
manual it accesses.
The manual may be a shell script or a binary file, but it must be marked
executable by all users.
A help cross-reference file has the extension ".XREF". A cross-reference is not listed on the subtopics list, even though it resides in the same directories as the other help files. There are two kinds of cross reference files; direct references and apology reference. An apology reference is just some text, apologizing for the lack of documentation on a particular topic. A direct reference is a one-line file, the first character of which must be the flag '@'. The rest of the line is a sequence of words, separated by spaces, specifing the cross-reference help path. For instance, the file /usr/help/lpr.XREF might contain the text:
@ printing lpr
Therefore, lpr.XREF is a direct cross-reference file.
The usual way of calling help is to just type
% help
in the shell. This brings up help interactive mode at the top level of topics. The user can always abort with ctrl/D.
No wildcards allowed in topic names. (Could have made them reg. exp. but that would be confusing to novices.)
Terminal type is not checked, the display is assumed to be at least 76 columns wide.
There is no way for the user to specify another program for viewing files ("more -d" is always used.) This is coded into the header file.
The algorithm used for selecting amoung ambiguous help paths is non-obvious, and can be confusing when too-short abbreviations are used.