HELP(1MAN) COMMAND REFERENCE HELP(1MAN)
NAME
help - interactive manual page browser and general help
facility
SYNOPSIS
help [ -p ] [ [ section ] title ]
DESCRIPTION
With no title argument, help executes a special set of menus
which give general information about using commands in the
system.
When a title (and possibly a section argument) is given, the
command man(1man) is executed in order to get the name of
the file containing the formatted manual entry. Because of
this, the section argument can be in any of the valid forms
for the man command; this manual entry and its index format
table (see manindex(5man)) are used to display sections of
the manual page. The program has special facilities for
maintaining a stack during the session and for ``taking
notes'' on a manual entry.
Screen Formats
Help is a screen-oriented manual page browser with two
screen formats. The main screen is divided into three
sections: Commands/Information, NAME section, and Current
Section.
The Commands/Information section has three lines. The left
side of first line lists the current manual entry being
viewed; the right side of this line lists the top element on
the stack followed by the number of items on the stack in
brackets ([n]). The left side of the second line is where
commands are entered; the right side of this line lists the
available section commands for the current manual entry,
with the command for the section being viewed in standout
mode. The third line of the Commands/Information section is
used to print error and information messages. These
messages are printed in standout mode.
The NAME section of the main screen displays the NAME
section from the manual entry. This section lists the names
of the items described by the entry and a short description
of the items.
The Current Section portion of the main screen lists the
name of the section, the number of the screen page being
viewed, and the total number of screen pages in the section.
The other screen format is called the ``alternate screen''.
This screen has two sections: Help and Information.
Printed 4/6/89 1
HELP(1MAN) COMMAND REFERENCE HELP(1MAN)
The alternate screen Help section lists the commands
available in that screen on the first two lines, and error
messages on the third line.
The alternate screen Information section is used to describe
the commands in the help system (via the `?' command) and to
list the contents of the stack (using the `ps' command).
Commands
There are five types of commands in the help system: Section
commands, Movement commands, Notes commands, Stack commands,
and Other commands. Commands may be one or two characters
long and are not followed by a return (the system knows when
a valid command has been entered). Any character entered
that could not be part of a command will cause the terminal
bell to be rung. Once the first command character of a
two-character command is entered, a backspace will erase
that character.
Section Commands
The section commands cause the different sections of the
manual to be displayed. The only valid section commands for
a given manual entry are those listed on the right side of
the second line of the Command/Information screen section.
The following are the available section commands:
sy View SYNOPSIS section.
de View DESCRIPTION section.
op View OPTIONS section.
ex View EXAMPLES section.
fi View FILES section.
va View VARIABLES section.
rv View RETURN VALUE section.
di View DIAGNOSTICS section.
ca View CAVEATS section.
se View SEE ALSO section.
re View REFERENCES section.
no View notes on current entry (see Notes Commands below).
Printed 4/6/89 2
HELP(1MAN) COMMAND REFERENCE HELP(1MAN)
None of these commands are available in the alternate
screen.
Movement Commands
The movement commands are used to move around in a manual
entry section or go to the next or previous section in the
entry (the order of the sections is the order listed above
in the Section Commands list). Any attempt to move past the
start or end of a section causes an error message, except
where noted. Movement is limited to pages and half-pages.
A page is the number of lines available on the screen to
print the current section, and depends on the number of
lines on the screen and the number of lines in the NAME
section. The following are the available movement commands:
<CR>
Go to next section in order given above.
- Go to previous section in order given above.
<sp>
Go to next page in current section. If the current page
is the last page, go on to the next section in the order
given above.
^F Go forward one page.
^B Go back one page.
^D Go forward one half-page.
^U Go back one half-page.
1G Go to first page in section.
G Go to last page in section.
^L Redraw screen.
The following commands are also available in the alternate
screen:
<sp>, ^F, ^B, ^D, ^U, and ^L.
Notes Commands
The help system gives the user the ability to store and view
his/her own notes on a given manual entry, such as special
examples or known problems. The notes are stored in the
directory $HOME/.helpnotes (which is created if need be)
under the same name as the manual entry they correspond to.
For example, the notes file for the manual entry test(1sh)
Printed 4/6/89 3
HELP(1MAN) COMMAND REFERENCE HELP(1MAN)
would be stored in the file $HOME/.helpnotes/test.1sh. If
there are notes on a manual entry, they can be displayed by
using the Section command `no'. Notes can be appended to or
edited using the following commands:
an Append to notes on current entry.
en Edit notes on current entry.
The editor to use is determined in the following fashion: If
the environment variable HELPEDIT is set, that command is
used. If not, the variables EDITOR and EDIT are used, in
that order. If none of these are set, vi(1) is used.
When either of these commands is invoked, the terminal mode
is restored to its original value and the cursor is placed
at the bottom of the screen.
These commands are not available in the alternate screen.
Stack Commands
The help system maintains a stack of up to 300 items. Each
item in the stack lists the manual entry name, the current
section, and the current page in the section; this allows
the user to save contexts and return to that context easily.
The top element on the stack is listed on the right side of
the top line in the Commands/Information section of the main
screen. The available stack commands are:
pu Push current page/section on stack.
po Pop stack. Top element becomes current page/section.
sw Swap current page/section for top of stack. This is
especially useful for switching back and forth between
two manual entries.
cs Clear stack.
ps Print stack values. The stack items are printed in order
from the top of the stack on the alternate screen. The
entry name, section, and page are all printed.
These commands are not available in the alternate screen.
Other Commands
There are three commands that do not fall into the above
categories. The command `?' prints a description of all of
the available commands and error messages in the alternate
Printed 4/6/89 4
HELP(1MAN) COMMAND REFERENCE HELP(1MAN)
screen.
From the main screen, the command `q<CR>' (`q' followed by a
carriage return) causes the help system to exit. From the
alternate screen, the `q' command returns the user to the
main screen. Interrupting the help system at any point will
terminate the session.
The command `he' is used to look at another manual entry.
The command prompts the user for the new entry specification
by printing the prompt ``Entry: '' on the second line of the
Commands/Information section of the main screen. The entry
specification must be less than 67 characters long, be
terminated by a return, and be in one of the following
formats:
<title> (eg, ``test'')
<section> <title> (eg, ``1sh test'')
<title>(<section>) (eg, ``test(1sh)'')
Since many manual entries are simply links to other manual
entries (this is done when a manual entry describes more
than one item), when the `he' command finds that the new
manual entry is the same as the current entry, no change
takes place.
OPTIONS
-p All `he' commands are automatically preceded by an
invocation of the `pu' command, thus saving the last
section viewed in each manual entry. This is useful for
switching back and forth between the current and previous
manual entry.
EXAMPLES
The following example will execute the help system with the
manual entry for the command co(1rcs) with all `he' commands
interpreted as `pu' and `he'.
help -p 1rcs co
In addition, if there are no other manual pages for co in
section 1, the following command will work the same way.
help -p 1+ co
FILES
$HOME/.helpnotes
manual entry notes directory
VARIABLES
HOME the user's home directory
Printed 4/6/89 5
HELP(1MAN) COMMAND REFERENCE HELP(1MAN)
HELPEDIT the editor to be used to edit notes
EDITOR the editor to be used if HELPEDIT is not set
EDIT the editor to be used if HELPEDIT and EDITOR
are not set
RETURN VALUE
[NO_ERRS] Command completed without error.
[USAGE] Incorrect command line syntax. Execution
terminated.
[NP_WARN] An error warranting a warning message
occurred. Execution continues.
[NP_ERR] An error occurred that was not a system
error. Execution terminated.
[P_WARN] A system error occurred. Execution continues.
See intro(2) for more information on system
errors.
[NP_WARN] An error warranting a warning message
occurred. Execution continues.
CAVEATS
There is no way to ask for more than one manual entry on the
command line.
The terminal must have at least 80 columns and 12 lines to
use the help command.
Standout modes are dependent on terminal types; existing
standout modes are underline, bold, and highlight; on color
terminals and color workstations a color contrasting with
the set display environment is used for standout mode.
SEE ALSO
apropos(1man), buildif(1man), echo(1sh), makewhatis(1man),
man(1man), manintro(1man), section(1man), whatis(1man),
man(5man), manindex(5man), whatis(5man), and catman(8man).
Printed 4/6/89 6
%%index%%
na:312,121;
sy:433,213;
de:646,2558;3588,2131;6103,2305;8792,2451;11627,1181;
op:12808,372;
ex:13180,450;
fi:13630,154;
va:13784,147;14315,221;
rv:14536,773;
ca:15309,547;
se:15856,522;
%%index%%000000000219