HELP(1) HELP(1)
NAME
help - experimental window system
SYNOPSIS
help/help
help/buf
eval `{/bin/help/parse [ -ca0 ] }
DESCRIPTION
Help is an experimental combination of window system, edi-
tor, shell, and user interface. Help supports textual
applications only.
Layout
The screen is divided initially into two columns of windows.
Each window is divided into two components: a single line of
text across the top, called the tag, and a multi-line body
of text below. Typically a window represents a file whose
name is in the tag and whose contents are in the body. In
this case, the file name appears as the first part of the
tag, followed by white space. The directory name associated
with the window is the file name in the tag stripped of text
after its final slash character.
The columns also have tags. The windows and columns are
stacked like aligned sheets of paper that may overlap. (In
the rest of this document, `window' will stand for `window
or column'.) Each window has associated a small black
square to the left of the column containing the window; each
column has one to the top. Clicking with mouse button 1 on
the square brings the associated window to the top of the
stack of windows in which it resides, leaving its x-y posi-
tion unchanged.
Pressing mouse button 3 in the tag of a window allows the
window to be moved: hold the button down and release it in
the desired new position.
New windows are placed automatically by help. They are
placed in the bottom of the column containing the selected
text (q.v.).
Text
Each window contains editable text in its tag and body. The
behavior of this text is essentially the same as in sam(1):
button 1 selects text; typing replaces the selection; there
is a scroll bar to the left, etc. Double clicking button 1
selects as in sam. The tag and body have independent
Page 1 Plan 9 (printed 12/22/24)
HELP(1) HELP(1)
selections.
The current window (tag or body) is the one under the mouse;
there is no `click-to-type' property.
Cutting and pasting are done by chords on the mouse buttons.
While button 1 is held down after a selection, clicking but-
ton 2 will cut the selected text and button 3 will paste the
snarf buffer into the selected text. There is no menu for
cutting and pasting, although there are such commands; see
the next section.
Execution
Commands are executed by selecting the text of the command
using button 2. When the button is released, the button 2
selection is passed to the shell for execution. While a
command is executing, the command name appears in the top
line of the help screen; when the command completes, it is
removed. Selecting with button 2 does not affect the cur-
rent text.
Some commands are built in to help. By convention, these
commands have initial capital letters. Examples are Cut,
Paste, Snarf, Open, etc. Such commands are interpreted
internally, much like functions in rc(1), and do not corre-
spond to executable files. Some built-ins take no arguments
and cause actions to the window in which they are executed.
These are suffixed with an exclamation point. They are
Close!, which closes the window, Get!, which rereads the
file, and Put!, which writes the window to its file.
The file name to execute is found as follows. If the com-
mand name begins / or ./ it is taken as a literal file name.
If not, the name is prefixed by the directory name of the
window holding the command name. If that file does not
exist or if there is no directory name, the name is prefixed
by /bin/.
Multiple words are interpreted as a command to execute fol-
lowed by its arguments. Single quotes behave as in rc(1).
Built-in commands that take an argument will use the
selected text as an argument if no argument is provided
explicitly. For example, one may select a file name with
button 1 and select Open with button 2 to open a window on a
file. Shell commands must be provided their arguments
explicitly, although it is possible to discover the selec-
tion in a program designed to run under help; see help(4)
and read about parse below.
Defaults
When selecting text with button 1, double clicks select
words, lines, etc. There is no way to double click with
Page 2 Plan 9 (printed 12/22/24)
HELP(1) HELP(1)
button 2, however. Instead, a null selection - a click -
with button 2 on a word expands to the entire white-space-
delimited word containing the selection. For example,
clicking button 2 on Cut will cut the selected text. If the
text selected with button 2 is not a null string, no such
expansion occurs.
When a null button 1 selection is used as an argument to a
command, rules relevant to the command are used to expand
the selection. For example, Open expands the selection to a
white-space-delimited word and interprets that as a file
name. It is therefore possible to open a file with two
clicks: one on the file name, one on Open. Also, since typ-
ing leaves the selection at the null string at the end of
the typed text, one may load a new file by typing its name
(leaving the selection at the end of the name) and clicking
button 2 on Open. Other commands interpret the selection as
numbers, words, C identifiers, etc., according to the rules
of the command.
Tools
Tools in help comprise directories holding executable pro-
grams and associated file, conventionally called stf
(`stuff') that holds the templates for executing the pro-
grams. Standard tools live in /help. For example,
/help/cbr is a directory of tools for browsing C source text
and /help/cbr/stf is a text file that acts somewhat like a
menu of browser commands. By the rules mentioned above,
clicking button 2 on, say, decl in the window holding
/help/cbr/stf will execute /help/cbr/decl, a program that
identifies the declaration of a C variable.
Boot
When started, help initializes its display and prints the
words help/Boot and Exit across the top. is naturally the
built-in command to quit help. The program help/Boot loads
help with the tools named in the environment variable
Support programs
See help(4) for an explanation of the control files help
offers its applications. Two programs in /bin/help assist
such applications. Buf collects its input and emits it in a
single write system call. It sends a maximum of 8192 bytes.
Parse reads help's control files to find the selected text.
It expands the selection, if null, to the alphanumeric word
defined by its option: -0 (zero) selects numbers; -a selects
alphabetic words; and -c selects C identifiers. Parse then
prints strings to set the environment variables $file to the
file name of the window holding the selection, $dir to the
directory, $base to the basename (file minus directory),
$line to the line number holding the beginning of the selec-
tion, and $id to the text containing the word. The output
Page 3 Plan 9 (printed 12/22/24)
HELP(1) HELP(1)
of parse should be executed by rc.
FILES
/mnt/help Files served by help (also unioned in /dev
in a window's name space, before the
terminal's real /dev files).
/help Directory of tools.
/help/lib/boot Bootstrap program.
SEE ALSO
8½(1), 8½(4), help(4)
Rob Pike, A Global Minimal User Interface.
BUGS
Help has not been engineered or tested nearly as well as 8½.
Page 4 Plan 9 (printed 12/22/24)