HELP(1)

NAME
help - user-friendly documentation reader

SYNOPSIS
help [ -dlqCn [ option-args ] ] [ topic-path ]

DESCRIPTION
Help is a documentation reader based roughly on the VMS(tm) help facility. Documentation texts are arranged in a tree, and the user reads them with more(1). Help allows documentation to be treated as an n-tree, the structure of the help tree is the structure of the directory tree in which the help files reside. Further, help supports a user-translucent cross-reference facility.

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:

d   Next argument is the help root directory. Default is /usr/help.

l   Use list-only mode. Only the list of subtopics for the command-line help path is printed. Interactive mode is not used.

q   Use text-only mode. Only the text of the help path is printed. Interactive mode is not used.

C   Forces multi-column output of subtopic lists. This is the default for interactive mode.

n   Force one-topic-per-line output of the subtopics lists. This is the default for list mode.

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:

?   Print current help and subtopic-list again.

.<topic-name>
    Do a UNIX Programmer's Manual lookup (if possible). If other characters follow the dot, they are taken as the filename for the .MANUAL file. (e.g. command '.who' looks for file who.MANUAL)

Return <CR>
    Exit this level of help. If at top level, goes back to calling program.

<subtopic-name>
    Read the documentation for this subtopic, or all subtopics for which this is a legal abbreviation. Wildcards are not permitted, but a short abbreviation matches everything longer.

#   List the available subtopics again. This lists the subtopics of this node, and re-prompts the user. The help text is NOT re-printed.

$<topicname>
    List some information on the files that make up this topic. Files that match the abbreviation of `topicname' are looked up with file(1).

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.

AUTHOR
Neal Ziring with George Robbert, Washington University in St. Louis.

FILES
/usr/local/bin/help
/usr/help*
/usr/ucb/more
/bin/sh

SEE ALSO
more(1), man(1), sh(1), system(2), access(2)

DIAGNOSTICS
Error messages are printed whenever a request is made to get documentation that does not exists, or is not accessible.

Signals are not trapped.

BUGS
The file naming conventions are somewhat strict.

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.