man(1) Manual page archive


     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

     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

     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

     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½.