man(1) Manual page archive


     HELP(4)                                                   HELP(4)

     NAME
          help - make and control help windows

     SYNOPSIS
          help/help

          Help(1) serves a variety of files for reading, writing, and
          controlling its windows.  The files are mounted on the
          directory /mnt/help and are also unioned into the beginning
          of /dev.  At the top level of that directory are files cons,
          consctl, and mouse, much like those of 8½(1). Help's ver-
          sions of these files have restricted utility, however: cons
          may be written to but not read and both consctl and mouse
          draw an error when opened.  When a program is run from
          within help, its standard input is connected to /dev/null
          and its standard output to /mnt/help/cons.  Text written to
          cons will appear in help's Errors window.  Consctl and mouse
          are there to prevent access to the files help is itself
          using.

          Another file in /mnt/help is index, which holds one line of
          text for each help window.  Each line has the numeric window
          id for the window, a tab, and the tag of the window.

          The rest of the files in /mnt/help are directories, one per
          window, named by the numeric window id of the corresponding
          window.  Each directory contains the following files:

          body     This read-only file contains the text of the body
                   of the window.
          bodyapp  Text written to this write-only file is appended to
                   the body.
          bodypos  This read-only file contains the starting and end-
                   ing byte offsets of the selection in the body, for-
                   matted as two textual numbers in 12-byte blank pad-
                   ded fields.
          bodysel  This read-only file contains the selected text in
                   the body.
          tag      This read-only file contains the text of the tag of
                   the window.
          tagpos   Like bodypos but for the tag.
          tagsel   Like bodysel but for the tag.
          ctl      A read of this file returns the textual numeric id
                   of the window.  Messages written to ctl change the
                   contents of the window.  Each message must be con-
                   tained in a single 9P write message (see read(5))
                   and must begin with an ASCII letter, possibly an
                   address, and a newline.  An address is one or two
                   comma-separated positions in the file, either line
                   numbers or character positions.  The address syntax

     HELP(4)                                                   HELP(4)

                   is a subset of that in sam(1). If the message con-
                   tains text to be added to the window, the text fol-
                   lows the newline and need not be newline-
                   terminated.  This description mentions only the
                   upper case versions.  The symbol \n stands for a
                   literal newline:
          a\n<text>           Append the text to the tag.
          A\n<text>           Append the text to the body.
          d<address>\n        Delete the addressed text from the tag.
          D<address>\n        Delete the addressed text from the body.
          i<address>\n<text>  Insert the text in the tag at the
                              addressed location.  If the address has
                              two components, the second is ignored.
          I<address>\n<text>  Like i, but insert in the body.
          u\n                 Mark the window `not dirty', that is,
                              remove the Put! string from the tag.
          A single directory /mnt/help/new, when accessed, creates a
          new window.  The easiest way to manage a new window is to
          open /mnt/help/new/ctl, which will create it automatically,
          and then read the file to retrieve the numeric id.  The
          other files in the window may then be opened as usual.

     EXAMPLE
          Create a new window and run date(1) in it.

               id = `{cat /mnt/help/new/ctl}
               echo 'a
               Current time    Close!' > /mnt/help/$id/ctl
               date > /mnt/help/$id/bodyapp

     SEE ALSO
          help(1), 8½(4)