OS/2 Professional/OS2PRO194.ISO/os2/com/utils/mush/mush.doc

Text File | 1990-12-21 | 232.9 KB | 5,743 lines

     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



     NAME
          The Mail User's Shell - Shell for electronic mail.

     SYNOPSIS
          mush [ -n ] [ -v ] [ -s subject ] [ -c cc-list ] [ -b bcc-
          list ] [ address-list ]
          mush [ -n ] [ -v ] [ -U[!]  ] -h draft-file
          mush [ mode-options ] [ file-options ]

     INTRODUCTION
          The Mail User's Shell (Mush) is an interface for sending and
          manipulating a database of electronic mail messages under
          the UNIX(TM) environment.  There are three user interfaces
          that allow the user to interact with Mush. The default
          interface is the conventional tty-based line mode similar to
          command line interpreters such as csh as well as other
          mailers, such as University of California, Berkeley's Mail
          and Bell Lab's System V mailx interface.  This mode requires
          nothing from the terminal in terms of screen capability and
          may be run on many different versions of the UNIX(TM)
          operating system.

          The text-graphics (curses) interface is reminiscent of the
          vi visual editor, but is user-configurable to simulate other
          editors.  This interface does not require graphics
          capabilities of the computer or the terminal on which it is
          run, but the terminal must have the minimum capabilities
          required by any visual screen editor.

          The window interface for the Sun Workstation utilizes the
          icon and menu based (mouse selectable) windowing system.
          This tool (graphics) mode is highly subject to the version
          of operating system your Sun may be running.  It is intended
          to be run on Sun versions 3.5 and higher (those that have
          the SunView window system).

          See the corresponding sections for more information on the
          user interface desired.  Most of this manual deals with
          commands, variables and actions that are common to all three
          interfaces although some attention is paid to individual
          characteristics of each interface.

          The following command line arguments are understood by Mush
          (full word forms in parentheses):

          -b bcc-list
               (-blindcarbon, -blind) The list of Blind Carbon Copy
               recipients is set on the command line.  If more than
               one address or an address containing spaces is
               specified, the entire list should be enclosed in
               quotes.  This option applies when sending mail only.
               If you are entering the shell, curses mode, or the tool



     Page 1                                         (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               mode, this option is ignored.

          -C   (-curses) Enter the mailer in curses mode upon startup.

          -c cc-list
               (-carbon, -copy) The list of Carbon Copy recipients is
               set on the command line.  If more than one address or
               an address containing spaces is specified, the entire
               list should be enclosed in quotes.  This option applies
               when sending mail only.  If you are entering the shell,
               curses mode, or the tool mode, this option is ignored.

          -d   (-debug) Turns on the debugging level to 1.  You can
               change debugging levels from within the shell using the
               debug command.

          -e   (-echo) Normally, the program runs with the local echo
               off and each character typed is processed individually
               so as to process certain macros and keyboard mappings.
               This option will suppress this from taking place and
               the program will only process input after a carriage
               return has been hit.  Under normal circumstances, this
               action is transparent to the user and the use of this
               option is discouraged except when using a debugger with
               the program.  Note that if this option is specified,
               any key sequence set by map or map! will not take
               place.  This option is ignored for curses mode.

          -F[!] filename
               (-source) This file is the same type as the
               initialization file read on startup (see
               INITIALIZATION) with the exception that commands that
               manipulate or search messages may be given.  Normally,
               such commands may not appear in the initialization file
               since that file is read before the folder is scanned.
               The file specified by -F is read after the folder is
               scanned, so commands that affect messages are allowed.
               The optional `!' argument prevents the shell from
               running after the file has been sourced.  Otherwise,
               Mush continues into whatever interface has been
               specified.

          -f [ filename ]
               (-folder) The optional filename argument specifies a
               folder containing mail messages.  With no argument,
               mbox in the current directory (or the variable mbox) is
               used.  If no filename is given, this option must be
               last on the command line.

          -H[:c]
               (-headers) Have Mush display mail headers without
               entering the shell.  See the headers command for



     Page 2                                         (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               information on the :c argument.  No colon modifier is
               equivalent to "-H:a".  This option prevents the shell
               from running, so this option will turn off the -S and
               -C flags.  This option is ignored if the tool mode is
               in effect.

          -h draft-file
               (-draft) This option specifies a previously prepared
               message file (called a draft) which will be read in as
               a new message to be sent.  The current implementation
               requires that the draft file must contain all the
               message headers; Mush will add only a new "Date:" and a
               "From:" header if there is none.  If there is no "To:"
               header, the draft will not be sent.  See the mail
               command and the section on "Sending mail" for more
               information.

          -I[!] filename
               (-init) This option specifies an initialization file to
               be read before any of the other Mush initialization is
               done.  The file specified by -I is read before the
               default system initialization file is read (see the
               INITIALIZATION section for details).  The optional `!'
               argument prevents Mush from reading the default system
               file, so -I! can be used to specify a substitute
               default file.  The user's personal initialization file
               is read normally.

          -i   (-interact) Forces interactive mode even if input has
               been redirected to the program.  This is intended for
               remote host mail sessions (with -e) but also allows the
               user to redirect input from a "script" of Mush
               commands.  See the INITIALIZATION and MUSH SCRIPTS
               sections for information on how to write scripts that
               deal with mail.  Note that this flag is different from
               the "ignore" flag of UCB Mail.

          -m mailbox-path
               (-mailbox) The mailbox specified will be interpreted as
               if it were the user's main (system) mailbox in place of
               /usr/spool/mail/$USER (or whatever path is applicable
               for your system and Mail Transport Agent).

          -N   (-noheaders) Enter Mush without displaying any message
               headers.  This argument is passed to the folder
               command.

          -n[!]
               (-noinit) No initialization is done on start up.  That
               is, do not source the default system initialization
               files.  If the `!' argument is given, reading of the
               user's personal .mushrc or .mailrc files is also



     Page 3                                         (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               suppressed.  See the INITIALIZATION section for more
               information on startup and the significance of these
               files.

          -r   (-readonly) Initialize the folder in Read-Only mode; no
               modification of the folder is permitted.  This argument
               is passed on to the folder command.

          -S   (-shell) This flag allows the user to enter the shell
               even if the system mailbox or specified folder is empty
               or doesn't exist.

          -s subject
               (-subject) The subject is set on the command line using
               this flag.  If the subject has any spaces or tabs, the
               entire subject should be enclosed in quotes.  This
               applies when sending mail only.  If you are entering
               the shell, curses mode, or the tool mode, this option
               is ignored.

          -T timeout
               (-timeout) In the tool mode (Sun only), timeout
               specifies the length of time (seconds) to wait between
               each check for new mail.  30 seconds is the smallest
               time allowed for performance reasons; 60 seconds is the
               default value.  This option should be used either in
               place of -t or immediately after it.

          -t   (-tool) Use the graphics tool mode (Sun only).  This
               option must be the first one on the command line,
               before any Sun window system flags or other Mush
               options.

               NOTE:  The -t option is obsolete and may be eliminated
               in future revisions.  The preferred way to run the tool
               mode of Mush is to use the command mushtool, which is a
               link to mush.

          -u [ user ]
               (-user) The mailbox to use is /usr/spool/mail/user.  If
               the login name for user is not specified, then root is
               used.

          -U[!]
               (-send) This option may be used only with -h (-draft).
               It causes the draft file to be sent immediately without
               further editing ("unedited", hence -U).  If the
               optional `!' is appended, signatures and fortunes are
               suppressed.  See the mail command and the section on
               "Sending mail" for more information.

          -v   (-verbose) Verbose mode is turned on.  This option is



     Page 4                                         (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               passed to the actual mail delivery subsystem internal
               to your version of UNIX(TM).  Some mailers do not have
               a verbose option, so this flag may not apply to your
               system (System V, for example).  This applies when
               sending mail only.  If you are entering the shell,
               curses mode, or the tool mode, this option is ignored.

     GENERAL USAGE
          Because there are three different interfaces available to
          the user, the tty characteristics (backspace, kill-word,
          kill-line, redraw line) are simulated identically in all
          interfaces.  When the user has to type something, the 4.2BSD
          style of tty driver interface is simulated whether you're in
          the window system, the curses mode, or the tty-line mode,
          and even on System-V machines.  This means that backspacing
          causes a backspace-space-backspace effect (erasing the
          character backspaced over).  The user may reset his tty
          characteristics using the stty command.

          New mail.

          If during a Mush session, new mail arrives for you, it is
          automatically incorporated into your system mailbox and you
          are told that new mail has arrived.

          In the default line mode, new mail is checked between each
          command issued.  In the curses mode, new mail is checked on
          each command and is displayed in the bottom line of the
          screen.  In the tool based graphics mode, new mail is
          checked approximately every minute or the number of seconds
          specified by the -T option on the command line.

          If you are using your system mailbox as your "current
          folder," then the new mail is added immediately to your
          current list of messages and information similar to the
          following example is displayed, to tell you whom the mail is
          from:

            New mail: (#15) [e-mail] (Dan Heller)

          If you are not in your system mailbox, then the new mail
          will not be added to your list of messages, but you will
          instead be informed of the new arrival.

          If you are using the tool based mode and Mush is closed to
          an iconic state, then the number of messages in the current
          folder is displayed on the mailbox icon and the flag on the
          mailbox will go up.

          Displaying messages.

          Depending on the interface you use, you can display any



     Page 5                                         (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          message in your list of messages as long as the message is
          not marked for deletion.  If the message is marked as
          deleted, then use the undelete command supplied by the
          interface you are using.  To display a message in line mode,
          specify the message using print, type, p, t, or type a
          message number to display that message on the screen.

          In curses mode, move the cursor over the message you want
          and type a `t' or `p' to read the message.  You may "bind"
          other keys to call the function that displays messages if
          `t' and `p' are uncomfortable.

          In the tool mode, move the cursor over the header summary of
          the message you wish to be displayed and select the LEFT
          mouse button.  The MIDDLE mouse button will delete the
          message, and the RIGHT button will bring up a menu of
          additional options, including help.  If the message you want
          is not visible (in the header subwindow), you may type the
          number of the message in the "Range:" item, and press
          return.  That message number will be displayed.  Finally,
          the "Next" item in the panel below the header display can be
          used to step through the folder, one message at a time.

          In the line or curses mode, if the message has more lines
          than the variable crt, then a pager will be invoked to allow
          the user to page through the message without having it
          scroll off the screen.  The pager used is determined by the
          variable pager.  If that variable is unset, then a default
          pager will be used.  Note that if pager is set, but not to a
          value, or is set to the value of "internal", then the
          internal pager is used.  The internal pager is very simple;
          the spacebar displays the next crt lines, carriage return
          prints the next line, and "q" quits the pager.

          In the tool mode, if a message is larger than the size of
          the message subwindow, the scrollbar at the left side of the
          window may be used to page the message forwards and
          backwards.  The variable crt_win may be set in an
          initialization file to preset the size of the message
          display subwindow.

          An alternative to displaying messages is the top command.
          This command will print just the top few lines of a message.
          The number of lines is determined by the variable toplines.
          If this variable isn't set, top will print a number of lines
          equal to the value of the variable crt.

          Sorting mail.

          Mush allows you to sort your mail according to various
          constraints such as time, size, status (new, unread,
          deleted, etc.), author and subject.  See the sort command in



     Page 6                                         (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          the COMMANDS section for more information on sorting.
          Sorting has a panel item in the tool mode, and is bound by
          default to the `o' (sort) and `O' (sort reverse) keys in
          curses mode.

          Picking specific messages.

          You can select messages that contain unique information, or
          from messages that have special attributes.  You have the
          option of restricting your search to messages between dates,
          message numbers, author names and other constraints.  See
          the pick command in the COMMANDS section for complete
          details.  This feature is not directly accessible from the
          tool mode, and is available only as a search action in
          curses mode (see, however, the CURSES INTERFACE section for
          temporary escapes to line mode).

          Sending mail.

          You can send mail by listing addresses on the command line
          when Mush is started, by using the mail command from within
          Mush, or by responding to other mail.  In curses mode, the
          `m' key invokes mail, and the `r' key begins a response.  In
          the tool mode, selecting the "Compose" or "Reply" items on
          the main panel will open a separate frame for message
          composition.  The message replied-to is either the current
          message or one specified in the "Range:" item.

          When you are sending mail, you are in a mode where
          everything you type is added to the contents of the message.
          When you are done typing your message in line or curses
          modes, you can type `^D' (control-D) to signify the end of
          the message.  If you have the variable dot set, then you can
          end a message with a `.' on a line by itself.  In the tool
          mode, select the "Send" item in the composition frame to
          finish and send the message.

          While you are composing a message, Mush treats lines
          beginning with the character `~' specially.  This is called
          a tilde escape.  For instance, typing "~i" (alone on a line)
          will place a copy of the "current message" into your message
          body.  It will not include the message headers of the
          message, just the body of text that comprises the message.
          A subset of these escapes are available in the tool mode,
          and others are provided as panel items or as menu selections
          from the "Include" item.  Tilde escapes which alter message
          headers are not usable when the variable edit_hdrs is set or
          when the -E option was passed to the mail command.

          The tool mode composition window uses header editing at all
          times, but provides some of these escapes anyway; see the
          descriptions below, and the description of the edit_hdrs



     Page 7                                         (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          variable, for complete details.

          Available tilde escapes:  [OPTIONAL arguments in square
          brackets]

          ~a file
               Append message buffer to file name.  Accessed via the
               "Export" panel item in tool mode.

          ~b [bcc-list]
               Modify blind carbon recipients; otherwise identical to
               ~t.  In tool mode, moves the cursor to the Bcc: header,
               adding one if necessary.

          ~c [cc-list]
               Modify carbon copy recipients; otherwise identical to
               ~t.  In tool mode, moves the cursor to the Cc: header,
               adding one if necessary.

          ~E[!]
               Erase message buffer; not available in tool mode.
               Saves the contents of the letter to "dead.letter"
               (unless the `!' is specified) and then clears the
               message buffer; the user remains in editing mode.  If
               the variable nosave is set, then `!' need not be
               specified.

          ~e [editor]
               Enter the editor.  Defaults to variable editor,
               environment EDITOR, or vi, except in tool mode, where
               ~e is equivalent to ~v.

          ~F[!]
               Add a fortune [don't add] at end of message.  Accessed
               via the "Fortune" panel item in tool mode.

          ~f [msg-list]
               Forward mail.  The included messages are not indented,
               but are marked as "forwarded mail".  Accessed via the
               "Include" panel item in tool mode.

          ~h   Modify all message headers.  Each header is displayed
               one by one and each may be edited.  In tool mode, moves
               to the To: header; typing a carriage return will
               advance the input cursor to each of the other headers
               in turn.  The mouse cursor will change to a "bent
               arrow" when automatic input cursor advance is active.

          ~I [msg-list]
               Same as ~i, but also include the message headers.
               Accessed via the "Include" panel item in tool mode.




     Page 8                                         (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          ~i [msg-list]
               Include the body of the current message (or listed
               messages).  Accessed via the "Include" panel item in
               tool mode.  See the descriptions of the variables
               indent_str, pre_indent_str, and post_indent_str.

          ~p [pager]
               Page the message body; not available in tool mode.
               Defaults to variable pager, environment PAGER, or the
               default pager set up by the system administrator.  This
               may be the internal pager.

          ~q   Quit message; save in ~/dead.letter if nosave is not
               set.  Not available in tool mode.

          ~r file
               Read filename into message buffer.  Accessed via the
               "Import" panel item in tool mode.

          ~S[!]
               Include [don't include] signature at end of message.
               The variables autosign and autosign2 describe the file
               or string to append to the message.  See the VARIABLES
               section for more information on these variables.
               Accessed via the "Autosign" panel item in tool mode.

          ~s [subject]
               Modify the subject header.  In tool mode, moves to the
               Subject: header, adding one if necessary.  In other
               modes, if an argument is given (a new subject), then
               the subject line is replaced by the new subject line.
               If none is given, then the subject line is displayed
               for editing just as in the ~t command.

          ~t [list]
               Change list of recipients ("To" list).  In tool mode,
               moves the cursor to the To: header.  In other modes, if
               a list is given, this list is appended to the current
               list.  If no list is given, then the current list is
               displayed and the cursor placed at the end of the list.
               You can backspace over the stuff in the list or you can
               append more addresses onto the end of the list as
               desired.

          ~u   Up one line; not available in tool mode.  If the user
               made a mistake typing a letter and he has already hit
               carriage return, he may avoid entering the editor and
               edit the previous line using ~u.  The line is retyped
               and the cursor is placed at the end allowing the user
               to backspace over it and retype the line.  System-V
               users should note that if the new line is shorter than
               it was before the ~u command, the line is padded with



     Page 9                                         (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               blanks to the previous length of the file.

          ~v [editor]
               Enter the visual editor; works in tool mode.  Also
               accessible through the "Edit" button in tool mode.
               Defaults to variable visual, environment VISUAL, or vi.

          ~w file
               Write message buffer to the indicated file.  Accessible
               in tool mode via the "Export" panel item.  When the
               header editing is in use (the variable edit_hdrs or the
               -E option of mail), this tilde-command can be used to
               create a draft file.  Draft files are partially
               completed letters that you wish to save for editing and
               eventually sending later.  See the mail command for a
               description of rereading and sending drafts.

          ~x   Exit message; don't save in dead.letter.  Accessible in
               tool mode via the "Abort" panel item.

          ~$variable
               Insert the string value for variable into message; not
               available in tool mode.  If a boolean variable is
               listed, nothing is appended regardless of its value.

          ~:command
               Run the Mush command specified by "command"; not
               available in tool mode.  You may not run any command
               that sends mail.  It is inadvisable to change folders
               at this time since the current message list may be
               corrupted, but the action is allowed nonetheless to
               provide flexibility for experienced users.

          ~~   A line beginning with two escape characters will be
               unaffected by Mush except that only a single tilde will
               be inserted into the letter.

          The variable escape may be set to describe a character other
          than `~' to be used as the escape character.  However, tilde
          escapes are normally NOT interpreted when Mush is started
          with redirected input.  If tilde-interpretation is desired,
          use the -i option when starting mush.

          Mail Aliases.

          Mail aliases are shorthand names for long mail addresses.
          These are supported in the same manner as UCB Mail supports
          them.  Because Mush has command line history reminiscent of
          csh, commands that use UUCP's `!' character for user-host
          and host-host separation should be escaped (preceded by a
          backslash).  This is not necessary in the initialization
          file (.mushrc) because history referencing is ignored while



     Page 10                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          these files are being sourced.  See the INITIALIZATION and
          LINE-MODE INTERFACE sections for more information on
          initialization file format and the history mechanism.

          Aliases reference normal mailing addresses as well as other
          aliases.  If a loop is detected, then the user will be
          notified and the message will be forced into the file
          dead.letter in the user's home directory.  The unalias
          command is used to reverse the effects of the alias command.
          From the tool mode, aliases can be set and unset in an
          aliases subwindow.  Press the RIGHT mouse button on the
          "Options" item in the main frame, and select "Aliases" from
          the menu.

          Help.

          Mush was designed so that each command or action should not
          be a mystery.  Helping the user understand what to do and
          how to do whatever he wishes is the goal behind the help
          facility.  For this reason, the help command gives
          information on both general usage and a few specific help
          categories.

          In text mode, most help is gotten by typing -? as an
          argument to a command.  Almost every command has the -?
          option.  When this option is specified, most commands will
          attempt to read from a help file a brief explanation of the
          functionality of the command.  If necessary, a pointer to
          other sources of information will be given to fully explain
          a concept.

          In line mode, typing `?' as a command will display a list of
          possible commands.  In the curses mode, the `?' key will
          display help message, which explains how to obtain a list of
          the current key-to-command bindings; a keystroke or set of
          keystrokes correspond directly to a command.

          In the tool mode, this is also available, but more extensive
          help is provided in the pop-up menus.  Press the RIGHT mouse
          button (the "menu button") when pointing to any panel button
          and a number of items will appear in a menu.  The last
          command in the menu list will often be one labelled "help".
          If a button does not have a menu or has no help item, check
          the menu of the "Help" button for related topics.  Selecting
          any help item will open a new scrollable window with help
          text.  Note:  The limited number of file descriptors in
          SunOS 3.5 forces Mush to display help information in the
          message window in the main frame.

     INITIALIZATION
          After the command line arguments have been interpreted Mush
          will read commands from one or more initialization files



     Page 11                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          that (typically) set variable values, aliases, command line
          aliases, and so forth.  Any file specified by the -I option
          is read first.  Next, if neither -I! nor -n was given, a
          default system initialization file is read.  The system
          default file is set up by the system administrator and may
          contain commands that should be set system-wide.  Finally,
          if -n! was not given, Mush reads the user's personal
          initialization file.

          The user's file is determined by first looking for the
          environment variables MUSHRC or MAILRC.  If neither of those
          environment variables is set, then the file .mushrc is
          searched for in the home directory of the user.  If that
          file cannot be found, Mush will attempt to read the file
          .mailrc from the same directory.  Finally, if that file
          cannot be read, no initialization is done and the default
          values will be in effect.

          If the user has no home directory, or permissions prevent
          read/write access to $HOME, /tmp is used as the home
          directory.  See the home variable under the VARIABLES
          section.

          Once in the shell, the source command may be used to specify
          a file if you want to read commands from a file other than
          the default.  The command saveopts will save all variable
          settings, aliases, and all other Mush settable attributes,
          to aid in creating an initialization file.  If no filename
          is given on the command line, the source and saveopts
          commands choose a file in the manner described above.
          Saveopts will not overwrite the file if it exists.  In such
          cases, you will be prompted to confirm overwrite.  If you
          confirm overwriting the existing file, remember that
          existing "if" expressions or other manually entered comments
          or non variable-setting type commands that previously
          existed in the file will be lost.

          No interactive commands should be called from any
          initialization file.  These commands are not prevented
          because it is impossible to trace which commands are
          actually UNIX(TM) commands that will be interactive.  The
          responsibility of not running interactive commands is left
          to the user.  Because the initialization file is read before
          any messages are read into the program, message filtering
          commands should not be placed in this file unless you know
          you're going to re-source the file later as a command.

          Initialization File Format.  When reading the initialization
          file, Mush will recognize the `#' character as a comment
          character.  It may be anywhere on a line in the file.  When
          that character is encountered, processing of that line is
          discontinued to the end of the line.  If the `#' is enclosed



     Page 12                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          in quotes (single or double), then it is not considered a
          comment.  Examples:

            set shell = /bin/csh  # set the shell variable
            # this entire line has been commented out.
            set prompt = "Message #%m: "  # The `#' is within quotes

          The exit command has special meaning in the initialization
          file.  If the command is found, Mush will not exit, but
          rather, discontinue reading from the file immediately.

          There may be "if" expressions within the initialization file
          to determine certain runtime states of Mush.  No parentheses
          are allowed and only one boolean expression may be evaluated
          per line; that is, no "&&" or "||" may be used in
          expressions.  An "else" on a line by itself may precede
          alternative actions.  "If" expressions may be nested to any
          reasonable depth, but there must always be an "endif"
          matching each "if" expression.  The statements associated
          with an "if" expression are never on the same line with the
          conditional expression.

          Conditional expressions understood include the internal
          variables istool, iscurses, is_shell, hdrs_only, is_sending,
          and redirect.  These are internal variables whose values
          cannot be referenced using the "$variable" method of
          variable expansion.  If istool is true, the program is going
          to run in the tool mode.  If iscurses is true, the program
          is in or is going to run in the curses mode even though the
          screen package may not yet have been started.  If is_shell
          is true, then Mush has entered the shell; is_shell is always
          false at startup when initialization files are read, and is
          always true when files are sourced after initialization with
          the source command or the -F option.

          If hdrs_only is true, then the -H flag on the command line
          has been given.  If is_sending is true, then the user is
          sending mail to another user.  This does not imply that the
          user is not going to be running a shell after the mail is
          sent.  If redirect is true, then input to the program is
          redirected.  The test for redirection tells whether input,
          not output, has been redirected to the program.  The -i
          option on the command line is required to run the shell if
          redirect is on.  If -i is specified, the value for redirect
          will be set to false.  Note that any time Mush runs when not
          connected to a terminal, it will believe that input has been
          redirected.  See the MUSH SCRIPTS section for more details.

          The `!' operator may be used to negate expressions, thus,

            if !istool
                exit



     Page 13                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



            else
                set autoprint
            endif

          means that if you are not running as a tool, stop reading
          commands from this file.  Otherwise, set the autoprint
          variable.

            set hdr_format = "%25f %7d (%l/%c) %25s"
            if hdrs_only
                exit
            endif

          This tells the program to set the hdr_format variable and
          check to see if we're running the program to read headers
          only.  If so, stop reading this file (exit) and continue on
          with the program.  This speeds up runtime quite a bit for
          those who have lengthy initialization files, because no
          other shell variables are necessary.

            if !iscurses
                set crt = 24 screen = 18
            endif

          This segment checks to see that we're not running in curses
          mode, and if not it will set our crt and screen sizes.  This
          is mostly because the curses mode will set those values for
          us by looking at the size of the screen.  See the CURSES
          INTERFACE section for configuring your environment so you
          enter curses mode each time you run the shell.

          String evaluation is allowed in "if" expressions, and the
          operators "==" and "!=" may be used to determine equality or
          inequality, and "=~" and "!~" may be used for pattern-
          matching.  Usually, variables are compared with constants
          for evaluation.

          Note that it is not possible to compare variables to an
          empty string, and variables that evaluate to an empty string
          may cause errors.  It is possible to test whether a variable
          is set by using the syntax "$?variable" (as in csh) but
          there is not currently any way to test for an empty string
          value.

            if $TERM == adm3a
                set pager = more
            else
                set pager = less
            endif

          This segment tests to see if the user's terminal type is
          "adm3a".  If it is, then it sets the pager variable to be



     Page 14                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          the more program.  Note that the variable TERM will be
          gotten from the user's environment if a shell variable is
          not set already.  Otherwise, the pager variable is set to
          "less".  This exemplifies the fact that less frequently
          fails to function correctly for the terminal type "adm3a" so
          we don't use it.

          Also supported in "if" expressions are the test flags "-e"
          and "-z".  These flags test to see if a file exists ("-e")
          or if it is zero-length ("-z").  These are most useful in
          command files that are to be read after the shell has
          started; see the examples in the MUSH SCRIPTS section.

          After sourcing the initialization file, Mush reads all the
          mail out of the specified folder (the system spool directory
          if no folder is given) and creates a list of messages.  The
          current maximum number of messages the user can load is set
          to 1000 by default.  The system administrator who configures
          the program can reset this value higher or lower if you ask
          nicely.  If the user has the sort variable set, then when
          the current folder's messages have all been read, the
          messages are sorted according to the value of the variable
          (see the sort entry under the VARIABLES heading for more
          information).  Each message has a number of message header
          lines that contain information about whom the mail is from,
          the subject of the message, the date it was received, and
          other information about the letter.  This information is
          then compiled into a one-line summary for each message and
          is printed out in an appropriate manner depending on the
          interface you're using.

          At this point, commands may be input by the user.  Lengthy
          or complex commands can be placed in a file and then
          executed via the source command.  Such files use the same
          format as the initialization files and may use all the same
          tests in "if" expressions.  Sourcing of a file of filter
          commands such as those in the example above can be automated
          by using the -F option when Mush is started.  Also see the
          MUSH SCRIPTS section for other uses.

     LINE-MODE INTERFACE
          In the line-mode, the user is given a prompt to which
          commands are issued and arguments are passed to commands.
          When the user types at the prompt, each line is parsed and
          words (or arguments) are separated into an array of strings.
          This array, also called an argument vector, is then modified
          by expanding history references, command line aliases, and
          variable references.  A command line ends when the end of
          the line is encountered or a pipe (|) or semicolon (;)
          character is encountered, separating discrete commands.

          When a command line has been parsed and placed in an



     Page 15                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          argument vector, the first argument in the vector (the
          "command") is searched for in a list of legal Mush commands.
          If found, the function associated with that command is
          called and the rest of the line is passed to that function
          as command line arguments.

          Before commands are called, however, the input the user
          gives is preprocessed in a style reminiscent of the C-shell
          (csh).  Mush also supports a subset from each of the
          following aspects of csh:
            +o Command history.
            +o Command line aliasing.
            +o "Piping" mechanism to redirect "input" and "output" of
            commands.
            +o Filename metacharacters.

          Command history.

          Mush supports a history mechanism similar to that supplied
          by csh.  A subset of csh history modifiers are supported to
          reference previously issued commands and to extract
          specified arguments from these commands.

          The history mechanism remembers a list of past commands
          whose length is bounded by the value of the history
          variable.  If this variable is not set, only the most recent
          command is remembered.  To reference previously typed
          commands, the `!' character is used in the same manner as in
          csh.  There is a limited implementation of history
          modification; supported are the argument selectors that
          reference command line arguments and ":p" (echo, but don't
          execute the command).

          Examples:
            !-2:$   two commands ago, last argument.
            !3:2-4  the third command, arguments two through four.
            !!:p    print the last command in its entirety.

          During the sourcing of initialization files (.mushrc),
          history is not in effect and therefore the `!' character
          does not cause history expansion.  This includes startup of
          the program and when the command source is issued.  UUCP
          style addresses that contain the `!' character may be given
          in the initialization file without the need to be preceded
          by a backslash.  However, `!' does need to be escaped if
          cmd's are used to reference command line arguments.

          Command line aliasing.

          Command aliases are different from mail aliases in that they
          are used to expand to commands.  This feature enables
          command substitution similar to csh.  To be backwards



     Page 16                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          compatible with UCB Mail, the alias command is used for
          address aliasing.  Thus, the command cmd is introduced in
          place of alias.

          Examples:
            cmd d delete
            cmd t type
            cmd dt 'd ; t'
            cmd - previous
            cmd r 'reply \!* -e -i'

          In the last example, if the user types "r 5", Mush will
          reply to sender of the fifth message and pass all the other
          arguments along to the reply command.  Note the escaping of
          the `!' character.  This must also be done if set in the
          initialization file (.mushrc).  Had the user not specified a
          message number on the `r' command line, reply would respond
          to the "current message" rather than the fifth message.

          Piping commands.

          Mush commands can be "piped" to one another so as to provide
          output of one command to be used as input to the next
          command in the pipeline.  However, the output of commands is
          not the "text" that is returned (as it is in sh and csh),
          but instead is a message list of the messages that were
          affected.  A message list is defined as the set of messages
          that the user specifies in a command or the messages a
          command affects after it is through executing.  When one
          command is piped to another, the effect is that the second
          command will consider only those messages affected by the
          first command.  In most cases, Mush is smart enough to know
          when piping is occurring and may suppress text output that a
          command might produce.

          Examples:

            pick -f fred | save fred_mail

          This will find all the messages from "fred" and save them
          all in the file named fred_mail.

            lpr 4-8 | delete

          This will send messages 4, 5, 6, 7, and 8 to the printer and
          then delete them.

            headers :o | delete

          Deletes all old (already read) mail.

          Because action is taken on mail messages, not files,



     Page 17                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          metacharacters such as `*' and `?' are not expanded to file
          names as csh would do.  Instead, Mush commands take message
          lists as arguments (a list references one or messages) to
          take action upon.  When referencing message numbers, Mush
          understands the following special syntax:

            *       All messages
            ^       The first message
            $       The last message
            .     The current message
            N-M    A range of messages between N and M, inclusive

          In the last case, N and M may be * ^ $ . or digits
          referencing explicit message numbers.  The range must be in
          ascending order.

          You can also negate messages by placing the message list
          inside braces, `{' `}' -- thus, the expression "2-19 {11-
          14}" references messages 2 through 19 except for messages 11
          through 14.

          Note that message lists are parsed left to right.  Negated
          messages may be reset by turning them on again later in the
          argument list.  A common error new users make is to specify
          a negated list without specifying any beginning messages.

            delete { 6 }

          In this example, the user attempted to delete all messages
          except for number 6.  He should have specified `*'
          beforehand.  A correct example:

            preserve ^-. { 3 }

          Here, the user specifies a valid message list and causes
          Mush to preserve all messages from the beginning of the list
          (message 1) to the current message, excluding message 3.

          As discussed, after the command line is parsed, the command
          given is called and the rest of the arguments on the command
          line are passed to it.  If no Mush command has been found
          that matches the one given, then the variable unix is
          checked.  If it is set, Mush attempts to run the command
          line as a UNIX(TM) command.

          If unix is not set, or if the command could not be found in
          the user's PATH environment, a message will be printed
          indicating that the command was not found.

          Since no "messages" are affected by UNIX commands, those
          that appear within Mush pipelines are executed by the pipe
          command.  A UNIX command may never be the first command in a



     Page 18                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          pipeline unless the pipe command is used explicitly.  If the
          user wishes to execute UNIX commands that are to be piped to
          one another (or use any sort of redirection), the command sh
          is provided for such purposes.  Since Mush will parse the
          entire command line, caution should be taken to enclose
          questionable shell variables or metacharacters with quotes
          to prevent Mush from expanding them.  See the COMMANDS
          heading below for more detail.

          This shell-like quality is for the convenience of the user
          and is not intended to replace the functionality of sh, csh,
          or any other command interpreter.

          Filename metacharacters.

          Mush's command interpreter does not normally pre-expand
          metacharacters in the manner of other shells, because the
          metacharacters may refer to either messages or files.
          Instead, those commands that deal with file names do any
          necessary metacharacter expansion.  Two metacharacters are
          nearly always recognized:  `~' refers to the user's home
          directory, and `+' refers to the user's folder directory
          ("~/Mail" or the value of the variable folder).  Another
          user's home directory can also be referenced as "~username",
          and for this reason files in the user's home directory must
          be referenced as "~/filename".  However, the `/' character
          is optional when referring to folders; that is, "+filename"
          and "+/filename" both refer to the same file in the folder
          directory.

          If filename completion is enabled by setting the variable
          complete, the command interpreter will expand csh-style
          metacharacters when completing filenames.  A completion
          containing metacharacters expands to all the files matching
          the pattern when the completion key is pressed (defaults to
          ESC, `^[').  See the description of complete for limitations
          of this facility.

     CURSES INTERFACE
          The curses interface utilizes the curses routines intrinsic
          to most UNIX systems.  This interface is screen oriented
          rather than line oriented and allows the user to access
          commands and messages more quickly at the cost of history,
          piping, and a few commands.

          Many users who prefer the curses interface might want to
          always start all their mail sessions in the curses
          interface.  Putting the curses command in your
          initialization file is allowed, but you can also create an
          alias or function in your login shell to always use the -C
          option.  Mush will attempt to know not to run a shell if
          you're just sending mail to someone, so the csh command



     Page 19                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          sequences:

            % alias mail 'mush -C'
            % mail fred

          will mail to fred and not enter the shell.  However, if you
          just said "mail" with no arguments, you'll enter the shell
          in curses mode if you have mail.  If you don't, you'll be
          told so, and the shell will not start.  If you want to enter
          curses mode even if you don't have mail, use the -S option
          on the command line.

          In curses mode, the user's terminal has its "echo" turned
          off so commands that are issued are not echoed on the
          screen.  Certain commands cause the mode to return to normal
          for typing purposes (sending mail, for example).  In normal
          operation, the screen will display the current set of
          message headers, the current message number is in the top
          left corner, the mail status on the top line, and the cursor
          will be placed on the current message.  The number of
          message headers displayed is set by the variable screen.  If
          the user does not have that variable set, the baud rate is
          checked and the size of the screen is set according to
          optimal refresh time.  Usually, 300 baud gives 7 lines, 1200
          gives 14, 2400 gives 22 lines, and all higher baud rates
          give the size of the screen, whatever that may be.  Note
          that the top line is reserved for "status" and the bottom
          line is for user interaction should it be required.

          The user may now type commands via key sequences that are
          not echoed to the screen.  Thus, function keys may be bound
          to "commands" by using the bind command.  A list of key-to-
          command bindings can be found at runtime by typing `?'  in
          curses mode or by using the bind command in line mode.

          The commands to which you can map sequences are intended to
          be as self explanatory as possible, but admittedly, it might
          be easier to figure out via trial and error than to try to
          wade through this documentation.  A list of the legal curses
          commands can be obtained when executing the bind command.
          Regular tty line-mode commands are not issued from the
          curses interface; only special curses mode commands are
          understood.  The current list of valid curses commands is:

              alias   last-msg        screen-back
              back-msg        line-mode       screen-next
              bind    lpr     search-again
              bind-macro      mail    search-back
              bottom-page     mail-flags      search-next
              chdir   map     shell-escape
              copy    map!    sort
              copy-list       my-hdrs sort-reverse



     Page 20                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



              delete  next-msg        source
              delete-list     preserve        top
              display quit    top-page
              display-next    quit!   unbind
              exit    redraw  undelete
              exit!   reply   undelete-list
              first-msg       reply-all       update
              folder  reverse-video   variable
              goto-msg        save    version
              help    save-list       write
              ignore  saveopts        write-list


          The following is a list of default key-command bindings.  If
          you specify bind commands in your initialization file that
          conflict with these defaults, your settings will override
          the defaults.  The default settings given in this manual use
          the ^-character method to indicate control characters
          (mostly because nroff makes printing the backslash character
          so amazingly difficult).  Thus, `^X' would mean control-X
          even though you'd have to type "\CX" to set the binding and
          actually use the control key and the `X' key simultaneously
          to really do a Control-X.

          ., t, p, T=top, n=next
               Display (type/print) message.  Top will display the
               first crt lines of a message.  Next will print the next
               message.  If the current message is deleted, the next
               undeleted message is found.  You might notice this is
               different from the line mode, which will return an
               error message that the current message is marked as
               deleted.

          +, j, J, RETURN
               Go to next message.

          -, k, K, ^K
               Go to previous message.

          ^, $ Go to first/last message.

          {, } Go to top/bottom of screen.

          a    Set aliases.

          b, B Set/unset bindings.

          d, D, u, U
               Delete/undelete messages (capitals prompt for message
               list).

          f    Change folder.  If current folder has changed,



     Page 21                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               verification for update will be requested.

          g, 0-9
               Go directly to a specified message.  When the "goto"
               command is selected, a prompt at the bottom of the
               window prompts for a message list.  Anything that
               describes a message list may be used.  Since Mush
               commands return message lists, a legal Mush command
               enclosed in backquotes may be used to go to a
               particular message.  The new current message pointer
               will point to the next message, returned by the
               command, that is below the old current message.  An
               example:

                 goto msg: `pick -f argv`

               This will cause the current message to move to the
               first message in the current folder from the user
               "argv" that comes after the message pointed to when the
               "goto" was issued.  So, if messages 1 and 5 are from
               the user "argv" and the current message the user was on
               was message 3, then the new current message would be
               message 5, since it is the first message found after
               message 3 that is from "argv".  If none of the messages
               are found after the current message, the new current
               message will be the first one returned by the command.

          h    Set personal headers.

          i    Set ignored headers.

          m, M Send mail (capital prompts for mail flags).

          o, O Order messages (sort; capital reverses order).  A
               prompt requests the sort constraints.

          q, Q, x, X
               Quit/exit.  `q' will test to see if the current folder
               has been updated and prompt the user to verify
               updating.  `x' does not update mail, but quits the
               program.  `Q' does not prompt for update verification;
               if changes were made, updating is automatic.  `Q'
               (quit!) and `X' (exit!) will work even when typed at
               the "...continue..." prompt, whereas `q' and `x' will
               not.

          r, R Reply/reply all.

          s, S, c, C, w, W
               Save, copy, or write messages (capitals prompt for
               message lists).




     Page 22                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          v    Set regular variables (as opposed to environment
               variables).

          V    Print version number.

          z, Z Print next/previous screenful of message headers.

          ^L   Redraw the screen.

          ^P   Preserve current message (toggle).

          ^U   Update folder.  A prompt will request confirmation.

          ^R   Toggle reverse video mode (current message is in
               reverse video).

          |    Send message to printer

          !    Shell Escape.  Prompts for command; RETURN invokes a
               shell.

          %    change directory.

          (, ) Source/saveopts.  Prompts for file name.

          /, ^/, ^N
               Forward, backward, continue search for patterns.
               Entire messages are not searched for here.  Only the
               text available on the screen is searched for.  Note
               that some terminals use `^_' (control-underscore) for
               `^/', so you may wish to re-bind this key.

          &&   Create a curses mode macro.

          &:   Create a line mode macro.

          &!   Create a composition mode macro.

          :[cmd]
               Enter line mode for one command.  History is not
               recorded for this escape, and line mode macros are not
               available.  If no command is given, curses mode is
               exited and the session continues in line mode (in which
               case history and macros become available).

          When setting new key sequences to be bound to commands, the
          user may use control keys and the ESCAPE character for
          extended commands.  Exceptions are control-C, control-\, and
          possibly other control characters depending on your system's
          configuration or your current tty mode settings.

          When assigning key sequences to commands, the user enters



     Page 23                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          the bind command and prompting is done.  If the user wishes
          to have control characters or the escape character in a key
          sequence while still using ASCII format, a special notation
          for control characters is provided.  This sequence is used
          primarily for the use of binding control character sequences
          in the initialization file.  This format is also used to
          display the current key-command mappings by the program.

          To specify control characters in ASCII format for the bind
          command, the sequence "\Cc" is used where `c' is the
          character that the control key will translate to and must be
          in upper case.  The sequence "\CP" would map to control-P.
          If the user wishes to indicate the RETURN key, this is
          specified with the string "\n" and the tab key is specified
          by the string "\t".  As a more complex example, on a Wyse-50
          terminal, the 8th function key outputs the three characters:
          control-A, H, line-feed.  To map this function key to a
          command, the user would have to enter the sequence "\CAH\n"
          as the key sequence, then follow up with a valid curses
          command.  From then on, if the user presses that function
          key, the command mapped to it will be executed.

          The ESCAPE key is signified by the sequence, "\E".  On a
          Sun-3 workstation, the R1 key outputs the character
          sequence: ESC, [, 2, 0, 8, z.  The corresponding bind key
          sequence would be "\E[208z".  Restrictions are that key
          sequences may not contain the space character unless bound
          in line mode, and can never begin with a digit.

          Whenever a command is entered, other than `^L' (redraw),
          which causes the screen to scroll or be refreshed in any
          way, Mush is left in the continue mode.  When in this mode,
          the user is given his line-mode prompt followed by
          "...continue..." indicating that he may issue a new command
          or return to the top level where the current message headers
          are displayed on the screen.  Remember that this is still
          the curses mode, but much time is saved by avoiding
          redrawing the screen after each command.  The user may move
          up and down messages using the appropriate commands (j/k by
          default) or anything else the curses mode allows.  Only the
          exit and quit commands will return to the top level.
          Because of this, there are 2 additional ways to "quit" from
          curses mode and return to the login shell.  The "exit" and
          "quit" commands will quit from the top level, but the
          commands exit! and quit! are used to exit from the
          "continue" level in the curses interface as well as from the
          top level.

          Note that the best way to understand the curses interface is
          to just use it.  In line mode, the command "curses" puts you
          into curses mode.




     Page 24                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



     GRAPHICS TOOL INTERFACE
          When running the window-based tool interface, there will be
          five subwindows:  a panel for folder-related commands and
          general options, a scrollable display of message header
          summaries, another panel of message manipulation commands, a
          four-line scrollable window for warnings and output from
          certain commands, and a larger window which is used for
          displaying messages.  The message display and command output
          windows can be scrolled with the up and down cursor keys
          (function keys R8 and R14 by default), and also recognize
          "vi" movements (j, k, ^U, ^D, etc.), in addition to having
          scrollbars.

          In the header summary window, pressing the LEFT mouse button
          while pointing at a message header displays that message in
          the large message window at the bottom of the frame.
          Pressing the middle button deletes the message, and pressing
          the RIGHT mouse button displays a menu of actions that will
          affect the message.  Possible actions are to display the
          message, delete or undelete it, reply to it, save it,
          preserve it (see the preserve command), or print it
          (hardcopy).

          All panel items in the frame have labels describing their
          functionality.  Selecting a panel item with the LEFT mouse
          button causes the action to be executed.  The RIGHT mouse
          button displays a menu of options that the command may
          branch to.  For example, the Save panel item by default will
          save messages to the file "mbox", but the RIGHT mouse button
          causes a menu to be displayed, and the choices of where to
          save the message increase to include the items in the menu.
          These typically include the files in the user's folder
          directory (see the folder variable below).

          At the end of most lists of menu entries for panel items is
          an item labelled "help".  When this item is chosen, an new
          window is opened where help for that command is displayed.
          Note:  The limited number of file descriptors in SunOS 3.5
          forces Mush to display help information in the message
          window in the main frame.

          When composing letters, a separate frame is created which
          includes a panel of command items, a four-line scrollable
          window, and a large window for editing the letter.  Panel
          items for including messages, editing (via your usual text
          editor), sending, aborting the message, and various other
          manipulations are supplied.  See the section on "Sending
          mail", under the summary of tilde escapes, for more details
          of composition frame command items.  As long as the
          composition frame is open, all Mush command output is
          redirected from the small window in the main frame to the
          small window here.  Note:  This subwindow is not present in



     Page 25                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          SunOS 3.5 due to the limited number of file descriptors;
          command output stays in the main frame in that case.  The
          SunView textsw interface is used by default in the large
          window for paging and editing.  Cursor movement with the
          function keys (R8, R10, R12, and R14 by default) is
          supported.

     COMMANDS
          Described below are legal commands understood by Mush that
          you can type at the line mode prompt.  Most commands have
          abbreviations (given in parentheses) and can be followed by
          message lists.  In most cases, whitespace is not necessary
          to separate commands from message lists.  For example, "d*"
          will delete all messages, and "u1-7 {4}" will undelete
          messages 1 through 7 except for message number 4.  NOTE:
          This "token splitting" may have unexpected side effects,
          especially for UNIX commands whose names contain digits.

          The ability to customize commands using the cmd facility
          allows users to customize Mush to resemble other mailers.
          However, efforts have already been made to include commands
          that are backwards compatible with other line-mode mailers.
          Users of the graphics tool mode of Mush may have little need
          for the command line mode because the icon based interface
          allows interaction with many commands.  The tool mode is
          much more restrictive in favor of a simpler, user friendly
          interface, but most useful commands may be achieved anyway.

          The following is a list of all recognized commands.  Since
          most commands accept a message list as an argument,
          arguments are noted only when they differ from a message
          list.

          alias [name] [address-list]
          unalias name
               The alias command defines a name to stand for a list of
               addresses.  The defined name can then be substituted
               for the entire list when sending mail.  For example,

                 alias dan [e-mail] [e-mail]

               This defines the name "dan" to be shorthand for two
               addresses, both of which happen to be Dan Heller.

               The command unalias can be used to remove an alias
               definition.

               With no arguments, alias prints out all the current
               aliases.  With one argument, it prints the list
               associated with that name, and with more than one
               argument, it creates a new alias.




     Page 26                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          alternates [host-list] [!path!login] [*[user]]
               (alts) This command is useful if you have accounts on
               several machines.  It can be used to inform Mush that
               your login name at each of the listed hosts is really
               you.  When you reply to messages, Mush will not send a
               copy of the message to your login name at any of the
               hosts listed on the alternates list.  If the special
               symbol "*" is used, then your login name is matched
               against all pathnames and local addresses.  A user name
               may be appended to the "*", in which case that name is
               matched instead of your login name.

               If you have another login name on the local or remote
               machine, then that login may be specified by preceding
               the login name or the path to the login name by a `!'
               character.

               For example,

                 alts zipcode maui1 !cory.berkeley.edu!dheller !root

               are all either hostnames or pathnames to my other
               accounts.  The last item, "!root" will match root that
               is only destined for my workstation.  Root accounts
               elsewhere are not considered to be me.

               If the alternates command is given with no arguments,
               the current set of alternate names is displayed.

          await [-T timeout]
               Directs the shell to wait for the arrival of new mail.
               New mail is checked approximately every 30 seconds, or
               every timeout seconds as specified by the -T option.
               This command does not return until new mail arrives or
               until a keyboard interrupt (^C) is typed.  Unless the
               string "await" appears in the value of the variable
               quiet, the terminal bell will ring when await reads in
               a new message (see the VARIABLES section for details).

          bind [string [command [parameters]]]
          unbind string
               Bind the sequence of keystrokes specified by string to
               the curses-mode function, command.  The string is
               usually one or two characters, or a sequence sent by
               one of the "function keys" of a particular terminal.
               See the CURSES INTERFACE section for a complete list of
               curses-mode functions; this interface is not available
               on all systems.  The parameters are currently
               recognized only for the special macro function; see the
               bind-macro command for details.

               If no arguments are given to bind, the current set of



     Page 27                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               curses bindings are listed; if only a string argument
               is given, the binding for that string is listed; and if
               both a string and a command are given, a curses binding
               is created such that when the string is typed in curses
               mode, the function specified by command will be
               executed.

               Bindings can be removed by using the unbind command.

          bind-macro [string [expansion]]
               This command is an abbreviation, which invokes the bind
               command with the special function macro as the second
               argument.  The effect of binding a curses macro is that
               whenever the string is typed in curses mode, the effect
               is the same as if the expansion had been typed instead.
               A special syntax is provided for including non-printing
               (control) characters in both the string and the
               expansion; see the CURSES INTERFACE section and the
               MACROS section for details.

               If no arguments are given, bind-macro will list the
               current curses mode macros.  It is otherwise identical
               to
                   bind string macro expansion.

          cd   Change the working directory to that specified, if
               given.  If no directory is given, then changes to the
               user's home directory.

          cmd [name [command]]
          uncmd name
               Command line aliases are set and unset using these
               commands.  More extensive information is given in the
               LINE-MODE INTERFACE section.  Uncmd may take `*' as an
               argument to uncmd everything set.

          curses [off]
               The curses command causes Mush to change from the
               line-oriented mode to the screen-oriented (curses)
               mode, as described above in the CURSES INTERFACE
               section.  This command may not be given when curses
               mode is already active.  When used in an initialization
               file (such as .mushrc) this command is the same as
               giving the -C (-curses) switch on the mush command
               line.

               The argument off may be used only in initialization
               files, including those read with -I (-init), and has
               the effect of turning off the -C switch.  Off is
               ignored at all other times, even in files read with -F
               (-source).




     Page 28                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          debug [N]
               Set debugging level to N (1 by default).  When in debug
               mode, the user can see some of the flow of control the
               program makes while executing.  The intent of the debug
               level is for tracking down bugs with the program at
               specific locations.  Occasionally, the program may
               segmentation fault and core dump.  When this happens,
               the user can reenter the program, set the debugging
               level and recreate the problem.

               If the user suspects memory allocation problems, a
               debugging level of 5 or higher will prevent memory from
               being freed so that memory bounds won't get
               overwritten.

               If the user suspects Mail Transport Agent errors, a
               debugging level of 3 or higher will prevent the MTA
               from starting and outgoing mail is directed to the
               standard output instead of actually being sent.

          delete/undelete
               (d/u) Takes a message list as argument and marks them
               all as deleted.  Deleted messages will not be saved in
               mbox, nor will they be available for most other
               commands.  If the folder has not been updated, deleted
               messages can be recovered with undelete.

          dt   Deletes the current message and prints the next
               message.

          echo [-n] [-h | -p] arguments
               Echoes all the arguments given on the command line,
               expanding variables and history references.  If the -n
               flag is given, then no newline is appended.  If the -h
               flag is given, then echo looks for formatting
               parameters as if the "from" command were given on the
               "current" message.  If the -p flag is given, then echo
               looks for formatting parameters as if your prompt were
               changed temporarily.

               Examples:

                 echo -h This message is from %a and is dated %d.
               might produce:
                 This message is from zipcode!argv and is dated Dec 14, 1988.

                 echo -p There are %n new messages to read in %f.
               might produce:
                 There are 5 new messages to read in /usr/spool/mail/argv.

               Note that -h and -p cannot be specified together.




     Page 29                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          edit (e, v) This function lets you edit messages in your
               folder.  When editing messages, be careful not to
               remove certain message headers such as Date or From or
               any others that looks important.  If you remove or
               change something you shouldn't have, you will be
               notified and the temporary file used to edit the
               message will not be removed.

          eval [-h | -p] arg ...
               As in most shells, the list of arguments to eval is
               re-parsed and then executed as a command.  This is
               useful primarily for causing multiple levels of
               variable expansion.

               If the -h option is given, eval will expand header
               format strings in the argument list before executing
               the command.  Similarly, the -p option will expand
               prompt format strings in the argument list before
               executing.  These formats are expanded last, after all
               history and variable expansion is completed, and are
               implicitly quoted, so embedded quotes, spaces, tabs,
               `!'s, etc. are handled correctly.  Header formats are
               expanded using the current message.  For example,

                 eval -h pick -f %a

               will find all messages from the same author as the
               current message.  See the the entries for hdr_format
               and prompt in the VARIABLES section for more details.

               Note that -h and -p cannot be specified together.

          exit (x) Returns immediately to the login shell without
               modifying the current folder or system spool directory.

          expand alias-list
               Aliases, given as arguments, are expanded as they would
               be if you were to send mail to each.

          flags [ [ + | - ] [ D f N O P p R r S U ] ] [msg-list]
               This command modifies the flag bits set on the listed
               messages.  It should not normally be needed, but is
               provided to allow users, through the cmd facility, to
               alter the ways that certain conditions are recorded.
               Multiple flag bits may be set or modified at once.  The
               modifiable flag bits are:

                   D       deleted
                   f       forwarded
                   N       new
                   O       old
                   P       preserved



     Page 30                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



                   p       printed
                   R       read
                   r       replied-to
                   S       saved
                   U       unread

               If a `+' or `-' is included in the list of bits, the
               specified bits are turned on or off respectively,
               without modifying other bits.  If no `+' or `-' is
               given, then the list of bits is set explicitly and all
               other bits are lost.  The `-' modifier can be escaped
               with a backslash (i.e., "\-") to prevent its
               interpretation as part of a message range, or it may be
               given after the list of bits for the same reason.

               Message lists can be piped to the flags command; for
               example, you may use

                   cmd r 'flags \!* + r | reply'

               to mark as replied-to all messages included in a reply.

          folder [-N] [-n] [-r] [ %[user] | # | & | file ]
               (fo) Change current folder.  With no arguments, prints
               the name of the current folder.  The arguments are:
                 -N     No headers are displayed upon entering new folder
                 -n   The current folder is not updated
                 -r     Set Read-Only mode (can't alter new folder)
                 %[user] Change to /usr/spool/mail/[user] (default is yours)
                 #       Switch back to the previous folder
                 &       Change folder to $mbox (default is ~/mbox)

               File names that do not begin with `/' are interpreted
               relative to the current directory unless they begin
               with one of the metacharacters `+' or `~'.  As in csh,
               the character `~' expands to the user's home directory
               (or to some other user's home directory if used as
               "~username").  The character `+' is expanded to the
               name of the user's folder directory (defaults to
               "~/Mail" or the value of the variable folder).  For
               compatibility with other mailers, no `/' character
               needs to appear between the `+' and the name of the
               folder (see "Filename metacharacters" in the LINE-MODE
               INTERFACE section).

               This command can only appear in a pipeline if it is the
               first command; it returns a list of all the messages in
               the new folder.  This command cannot be used in
               initialization files before the shell has started.

               For compatibility with older versions, the argument `!'
               with no leading `-' is interpreted as -n.



     Page 31                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          folders
               List the names of the folders in your folder directory.
               Your folder directory is the directory Mail in your
               home directory.  Or, you can set the variable folder to
               specify another folder directory.

          from [ + | - ] [msg-list] [pattern]
               (f) With no arguments, from will print the current
               message's header summary (see the variable hdr_format).
               If given a pattern, from will print the headers of
               those messages whose "From: " lines match the pattern.
               When a message list precedes the pattern, or when a
               message list is supplied by a pipeline, the search is
               restricted to that list.  If only a message list is
               given (or piped), from will print the headers of the
               listed messages.

               The special arguments `-' and `+' can be given to move
               the current message pointer to the previous or next
               message, respectively, while also printing that
               message's header.  If a message list was given in
               addition to `-' or `+', then the current message
               pointer will be set to the first or last message,
               respectively, in the message list given.  Examples:

                 from + Dan

               will print the headers of all messages that contain
               "Dan" in in the author's name and set the current
               message pointer to the last one of that kind in the
               list.

                 from - 10-30 {16}

               will print the headers of messages 10 through 30 except
               for message 16 and set the current message pointer to
               10.

                 from +

               will print the header of the message after the current
               message and increment the current message pointer to
               the next message.

                 from $

               will print the last message's header and not move the
               current message pointer.

          headers [ [-H][:c] ] [ + | - ]
               (h, z) Prints a screenful of message headers listed in
               the current folder.  If a message number is given on



     Page 32                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               the command line, the first message of the screenful of
               messages will be that message number.  The `z' command
               is identical to the "h +" command and remains for
               compatibility reasons.  The variable screen may be set
               to tell how many headers are in a screenful.  In the
               graphics tool mode, the variable screen_win contains
               the number of headers used in the headers subwindow.

               A typical header may look like:

                 5 >N  [e-mail] Feb 19, (10/278) Test

               This line indicates that it is message number 5 and the
               > indicates that the "current message pointer" is
               pointing to this message.  The next two positions
               indicate the message status.  The first may be one of,
               "N" (new and unread), "U" (old, but still unread), "*"
               (deleted), "S" (saved), "P" (preserved), or " " (read).
               The second position may have an "r" if the message has
               been replied to.

               The author of the example message header is
               [e-mail], the date is Feb 19, the number
               of lines in the message is 10, the number of characters
               is 278 and the subject of the message is Test.  The
               format of the message header shown here is described by
               the string variable hdr_format.  The example given
               above has a hdr_format of

                 set hdr_format = "%25f %7d (%l/%c) %25s"

               See the description of hdr_format in the VARIABLES
               section for more information on header formats.

               You can print a special subset of message headers by
               using the -H:c option, where `c' is one of:
                 a       all messages
                 d       deleted messages
                 n       new messages
                 o       old messages
                 r       replied to messages
                 s       saved messages
                 u       unread messages
               Note that the -H is not required; "headers :c" is
               valid.

               More options to the headers command include `+' and
               `-'.  Each will print the next or previous screenful of
               message headers.  The z command can also be used; `z'
               alone will print the next screenful (thus, the `+' is
               optional) and "z -" is equivalent to "h -".




     Page 33                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               Headers affects all the messages it displays, so piping
               may be done from the headers command.  Piping to the
               headers command causes the message headers affected by
               the previous command to be printed.  This action is
               identical to piping to the from command.

          help [topic]
               Help is provided on a per topic basis and on a general
               basis.  For general help, just typing help will provide
               some general information as to how to get further help
               and a list of topics suggested for more specific help.
               There is also help provided for each command by using
               the -?  option to most commands.  This option will
               provide command line usage information as well as a
               description of what the command does and how to use it.

               If no help file is found, an error message will be
               printed.  The location of the help files may be reset
               by setting the variables cmd_help and tool_help to the
               paths of the new help files.

               The tool_help variable is recognized only by versions
               capable of using suntool mode (tool mode need not be
               active).

          history [-h] [-r] [N]
               This command displays the command history in
               chronological order; early commands are printed first
               followed by more recent commands displayed last.
               Option -h suppresses printing of history event numbers
               with each history command.  Option -r reverses the
               order of the history events displayed.

               If a number N is given, then that number of previous
               commands is echoed rather than the number set by the
               variable history.

               See the LINE-MODE INTERFACE section for a description
               of referencing the history in commands.

          ignore/unignore [header-list]
               Display or set a list of headers to be ignored when
               displaying messages.  When reading messages, all the
               message headers are displayed with the text body of the
               message.  Since these message identifier fields are
               cumbersome and uninteresting in many cases, you can
               filter out unwanted headers by using this command.  For
               example,

                 ignore Received Date Message-Id

               will ignore the three specified fields.  Additional



     Page 34                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               ignore commands are cumulative.  The command unignore
               is used to reverse the effects of ignore.

               For another way to control this, see the variable
               show_hdrs.

          lpr [-h] [-n] [-Pname] [msg-list]
               Takes a message list and sends those messages, one by
               one, to the printer, each separated by page feeds.  The
               -h option suppresses printing of ignored headers (see
               the ignore command and the variables show_hdrs and
               alwaysignore), and the -n option suppresses all
               headers.  A default printer name is supplied if one is
               not specified on the command line (-Pprinter-name).  If
               you have the variable printer set, that printer name
               will be used.

               If the variable print_cmd is set, the command described
               by that variable will be used instead of the default
               system command.  In such cases, the -P option and the
               printer variable are ignored and the command is simply
               executed as is.

               The "printed" status bit is set for each message
               printed by this command.

          ls [flags]
               This command duplicates the UNIX(TM) command /bin/ls.
               By default, ls always uses the -C flag (columnate
               output).

          mail [flags] [recipient ...]
               (m) Send mail to a list of users.  If no recipient list
               is specified on the Mush command line, then a "To: "
               prompt will request one.  A list of recipients must be
               supplied at some time before the message is sent, but
               is not required to begin composing a letter.  This
               implementation of Mush supports mailing to files and
               programs as recipients.  Filenames must be full
               pathnames; thus, they must start with a `/' or there is
               no way to know whether a recipient is a pathname or a
               user name.  The special characters `+' and `~' may
               precede pathnames since they are expanded first to the
               user's folder directory (+), as described by the
               variable folder, and the user's home directory (~).
               Mailing to programs is indicated by the pipe `|'
               character preceding the program name.  Since the user's
               path is searched, full pathnames are not required for
               programs that lie in the user's PATH environment
               variable.

               Example:



     Page 35                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



                 mail username, /path/to/filename, "|program_name",
               +folder_name, ~user/mbox

               Options are:
                 -b addr-list   set list of blind carbon recipients
                 -c addr-list   set list of carbon copy recipients
                 -E     edit outgoing message headers
                 -e     immediately enter editor (autoedit)
                 -F     add random fortune to the end of message
                 -f [msg-list]  forward messages (not indented)
                 -H file        read file as prepared text (no headers)
                 -h file        read file as a draft (text and headers)
                 -I [msg-list]  include messages with headers (indented)
                 -i [msg-list]  include messages in letter (indented)
                 -s [subject]   prompt for subject [set subject explicitly]
                 -U     send draft immediately (use only with -h)
                 -u     unsigned: no signatures or fortunes added
                 -v     verbose (passed to mail delivery program)

               The verbose option may not be available depending on
               the mail transport agent on your system.

               The -e flag causes you to enter the editor described by
               the variable visual.

               The -E flag causes Mush to place the headers of the
               outgoing message in the editor file so they can be
               changed.  See the description of the variable edit_hdrs
               for details.

               The -i flag will include the current message into the
               body of the message you are about to send.  The
               included message is indented by the string "> " or by
               the string described by the variables indent_str,
               pre_indent_str, and post_indent_str.  See the VARIABLES
               section for more information on these string values.
               If a message list is given after the -i option, then
               the messages described by that list are included.  The
               -I option is identical to the -i option except that the
               headers of the message are also included.

               The -s flag looks at the next argument and sets the
               subject to that string.  If the string is to contain
               spaces, enclose the entire subject in quotes.  If there
               is no following argument, then the subject will be
               prompted for.  This flag is useful if the user:

                 +o does not have the variable ask set, or
                 +o wishes to change the subject used with reply

               The subject is not prompted for and is ignored
               completely if the -f flag is specified (see below).



     Page 36                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               The -f flag is for message forwarding only.  An
               optional message list can be given just as the -i
               option has.  The forward option does not allow you to
               edit the message(s) being forwarded unless the -e flag
               is also specified.  The subject of the message (if
               available) is the same as the current message; it is
               not necessarily the subject of the message being
               forwarded.  The subject of forwarded mail cannot be
               changed.  However, using the -e flag will allow the
               user to change the subject once in editing mode either
               by using the escape sequence, "~s", or by editing the
               "Subject:" header.

               Forwarded mail that has not been edited by the user
               will contain special headers such as

                 Resent-To:
                 Resent-From:

               and perhaps others, depending on your mail transport
               agent.  Sendmail, for example, may add a number of
               other "Resent-*" headers.

               The -u option, meaning "unsigned", prevents signatures
               and fortunes from being appended to the message.  It
               overrides the variables autosign and fortune, but will
               affect the -F option only if given after it on the
               command line.

               The -h option indicates that the given file is a
               previously prepared message, possibly a partial one
               saved with "~w".  Such a file is called a draft.  The
               file argument must be given, and in the current
               implementation all message headers must either be
               present in the file or must be added manually by the
               user.  At minimum, there must be a "To:" header; Mush
               will add "From:" and "Date:" headers when sending, if
               necessary.  To read a prepared text file that does not
               contain headers, use -H.  If the -U option is also
               given, then the letter is sent immediately without
               further editing.


          map[!] [string [expansion]]
          unmap[!] string
               The map command creates or lists macros for the line
               mode interface, and the map! command creates or lists
               macros for the message composition mode.  In either
               mode, macros act in such a way that, when string is
               typed, the effect is the same as if expansion had been
               typed instead.  The string is usually one or two
               control characters, or a sequence sent by one of the



     Page 37                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               "function keys" of a particular terminal.  See the
               MACROS section for the syntax used to specify the
               string and the expansion, and for comments on the
               interactions of macros in the same and in different
               modes.

               If no arguments are given, these commands will display
               the list of macros and expansions for the appropriate
               mode.  If only a string is given, they will display the
               expansion associated with that string for the
               appropriate mode.  Otherwise, they will create a macro,
               associating the given expansion with the specified
               string.

               Line mode macros are unset with the unmap command, and
               composition mode macros are unset with the unmap!
               command.

          merge [-N] folder-name
               Messages from the named folder are read into the
               current folder.  The header summaries of the merged
               messages are printed unless the -N option is given (see
               the folder command, above).  This command can only
               appear in a pipeline if it is the first command; it
               returns a list of all the messages from the merged-in
               folder.  This command cannot be used in initialization
               files before the shell has started.

          my_hdr/un_hdr [header]
               You can create personalized headers in your outgoing
               mail using this command.

               Command usage:
                 my_hdr  print all your headers
                 my_hdr header   print value of header
                 my_hdr header: string   set header to string
                 un_hdr header:  unset header

               To set a header, the first argument must be a string
               that contains no whitespace (spaces or tabs) and must
               end with a colon (:).  The rest of the command line is
               taken to be the text associated with the mail header
               specified.  If any quotes are used in the header and
               the header itself is not set in quotes, then quotes
               should be escaped (preceded) by a backslash.  This
               holds true for semicolons, pipe characters or any other
               metacharacter that Mush might interpret as a command
               line modifier.

               If the variable no_hdrs is set, then your headers will
               not be added to outgoing messages, but no headers will
               be unset.  The un_hdr command may take `*' as an



     Page 38                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               argument to un_hdr everything set.

               Example:

                 my_hdr Phone-Number: [phone]

               Mush treats the the header "From:" as a special case.
               If you have set your own From:, a simple test is
               performed to determine whether the address given is
               valid.  Any UUCP or domain address that directs mail to
               your login at the local machine should be acceptable,
               but certain configurations may prevent some
               combinations from being recognized.  If the address is
               valid, your From: header will be used; otherwise, an
               address known to be valid will be generated and used
               instead.  Some mail transport agents are "picky" and
               will not allow Mush to supply a From: header; in these
               cases, your From: header is silently removed at send
               time, and replaced with one generated by the MTA.

               Note:  You cannot set the "Date:".  Attempting to do so
               will not result in any error messages; your date will
               simply be overwritten by the system when your mail is
               sent.

          pick [flags] [<pattern>]
               Allows the user to select particular messages from a
               folder.  The <pattern> is a "regular expression" as
               described by ed.  If no arguments are given, the
               previous expression searched for is used.  You can
               search for messages from a user, for a particular
               subject line, between certain dates, and limit searches
               to a range of messages.  You can also find all messages
               that do not match the same arguments mentioned above.

               Options:
                 +<num>  keep only the first <num> messages matched (head).
                 -<num> keep only the last <num> messages matched (tail).
                 -ago <format>  search for messages relative to today's date.
                 -d [+|-]date  messages sent on or [+ after] [`-' before] date.
                 -e     take all remaining arguments to be the pattern.
                 -f     search for pattern in "From" field only.
                 -h header      search for pattern in specified header only.
                 -i     ignore case of letters when searching.
                 -r msg-list    search only the listed messages.
                 -s     search for pattern in "Subject" field only.
                 -t     search for pattern in "To" field only.
                 -x     select messages that do not match the pattern.

               The -ago option can be abbreviated as -a.  Only one of
               -a, -d, -f, -h, -s and -t can be specified at once.
               Entire messages are scanned for the <pattern> unless



     Page 39                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               -a, -d, -f, -h, -s or -t is specified.  Messages marked
               for deletion are also searched.  No patterns can be
               specified with the -a or -d options.  The -x option may
               not be used in conjunction with +n (head) and -n
               (tail).

               For the -d option, "date" is of the form:

                 month/day/year

               with an optional `-' to specify that the messages of
               interest are those older than that date.  Omitted
               fields of the date default to today's values.  Examples
               of selecting on date:

                 pick -d 4/20   on April 20, this year.
                 pick -d -/2/85        on or before the 2nd, this month, 1985.
                 pick -d +5/4   on or after May 4 of this year.
                 pick -d /      today only.

               At least one `/' char must be used in a date.  There is
               no strong date checking; 2/30 would be considered a
               valid date.

               For the -ago option, the format is very simple.
               Specify the number of days followed by the word "days",
               or the number of weeks followed by the word "weeks",
               and so on with months and years.  Truncation is
               allowed, since only the first character is examined, so
               all of the following are equivalent:

                 pick -ago 1 day, 2 weeks
                 pick -ago 2Weeks 1Day
                 pick -ago 2w,1day
                 pick -a 2w1d

               These examples will find all messages that are exactly
               2 weeks and 1 day old.  All "ago" dates collapse into
               "day" time segments.  This means that months are 30.5
               days long.  If more precise date selection is required,
               use the -d option and specify specific dates.

               Also note that the -ago option allows the "before" (-)
               and "after" (+) arguments.  Thus, you may pick all
               messages older than 1 week with:

                 pick -ago -1 week

               Other examples of pick:

                 pick -d 2/5/86 | pick -d -2/5/87 | pick -s "mail
               stuff" | lpr



     Page 40                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               Will find all the messages between the dates February
               5, 1986, and February 5, 1987, that contain the subject
               "mail stuff" and send them to the printer.

                 pick -s Re: | delete

               Deletes messages that have "Re:" in the Subject header.

                 folder +project | pick -f frank

               Finds all messages from frank in the folder described
               by +project.

                 pick -h return-path ucbvax

               Searches all messages that have the header "Return-
               Path:" and determines if the string "ucbvax" is in the
               header.  Note that case sensitivity applies only to the
               pattern searched, not the header itself.

                 pick -ago +1w | save +current

               This finds all messages that are a week or less old and
               saves them in the file called current, which is found
               in the user's folder variable.

                 pick +3 mush-users

               Finds the first three messages containing the string
               "mush-users".

                 eval -h "pick +2 -r .-$ -s %s" | pick -1

               Finds the next message with the same subject as the
               current message.

          pipe [-p pattern] [msg-list] unix-command
               Allows the user to send the texts of a list of messages
               to a UNIX(TM) command.  The list of messages may either
               be given explicitly or may come from a Mush pipeline
               (see "Piping commands" under the LINE-MODE INTERFACE
               section).  If a list is neither given nor piped, the
               current message is used.  All headers are considered
               part of the message text for purposes of this command
               unless the value of the variable alwaysignore includes
               the word "pipe" (see alwaysignore in the VARIABLES
               section for more information).  For example,

                   pipe 3 5 7 patch

               sends the text and headers of messages 3, 5 and 7 to
               the patch utility.



     Page 41                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               If a pattern is specified with the -p option, Mush will
               search the message for a line beginning with that
               string.  The matching line and all succeeding lines
               will be sent to the unix-command.  If -p is not given,
               and the unix-command is omitted, Mush will search for a
               line beginning with "#!" and feed that line and all
               succeeding lines to "/bin/sh".  Thus, pipe with no
               arguments treats the current message as a shell script.

               The pattern may also be of the form
               /pattern1/,/pattern2/ in which case printing will begin
               with the line containing pattern1 and end with the line
               containing pattern2 (inclusive).  Patterns of this form
               must still match at beginning of line, and regular
               expressions are not currently allowed.

               The pipe command can also be invoked as Pipe (note
               capitalization), in which case only the body of the
               messages, and none of the message headers, are sent to
               the unix command.

               When the variable unix is set, UNIX(TM) commands can
               appear anywhere except as the first command in a Mush
               pipeline without explicitly using pipe.  However, it is
               still necessary to specify Pipe in order to exclude all
               headers.

               Note:  All messages listed as arguments to pipe or Pipe
               are sent to the standard input of the same process as a
               continuous stream!  This is probably not desirable when
               extracting shell scripts in particular, so take care.
               Future revisions may provide an option to control this
               behavior.

          preserve
               (pre) Saves a message list in your spool directory
               rather than your mailbox unless it has been explicitly
               deleted.  The variable hold causes all messages to be
               held in your spool directory automatically.

          print
               (p, type, t) Takes a message list and displays each
               message on the user's terminal.  If the first letter of
               the command is a capital letter (`P' or `T') then
               "ignored" headers are not ignored provided that the
               variable alwaysignore is either not set or is set to
               one of its possible values.  If this variable is set
               with no value, the ignored headers will be ignored
               regardless of the command used to display the message.
               See the ignore command for more information about
               ignored message headers.




     Page 42                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               The `+' and the `-' keys can be used to display the
               "next" and "previous" messages respectively.  The `+'
               key has the caveat that the message is not paged at all
               and none of the messages headers are displayed.

          pwd  Prints the current working directory.

          quit (q) Updates the current folder and exits from Mush.  If
               the variable "hold" is set, all messages not marked for
               deletion are saved in the spool directory.  Otherwise,
               messages that have been read are saved to ~/mbox or to
               the file described by the string variable mbox.
               Messages marked for deletion are discarded.  Unread
               messages go back to the spool directory in all cases.

          reply/replyall [msg-list] [-r path] [flags] [users]
               (r/R) Messages are replied to by sending mail to the
               sender of each message in the given message list.  The
               command replysender is equivalent to reply.  Replyall
               responds to all the recipients as well as the sender of
               the message.  These commands understand all the same
               flags as the mail command.

               When constructing a return mail address to the author
               of a message, reply searches for special mail headers
               in the author's message that indicate the most
               efficient mail path for return mail.  Mush will search
               for the "Reply-To:", "Return-Path:", and "From:"
               headers, in that order, by default.

               If none of these fields are found in the message, the
               first line of the message is parsed if possible; this
               "From " line is different from the "From: " line.  If
               the user wishes to change the order or the actual
               fields to search for return paths, then the variable
               reply_to_hdr may be set to a list of headers to be used
               (in the order specified).  If it is set, but has no
               value, the first "From " line is used regardless of
               what headers the author's message contains.  The
               "From " line may be specified explicitly as an item in
               the list of reply-to headers by specifying the header:
               From_. See the VARIABLES section for more information
               about reply_to_hdr.

               When replying to all recipients of the message using
               the replyall (R) command, only the original author's
               address can be obtained from the message headers.
               There is no way to determine the best path to the other
               recipients of the message from message headers aside
               from taking their addresses directly from the "To:" and
               "Cc:" lines.




     Page 43                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               Example:

                 replyall 3,4,5 -i 4,5 7 -s response mail-group

               Here, messages 3, 4 and 5 are replied to (all the
               authors are obtained from each of those messages as
               well as the recipients from those messages) and the
               text from messages 4, 5 and 7 are included in the body
               of the reply.  The subject is set to "response" and the
               alias mail-group is appended to the list of recipients
               for this message.

               The -r flag will prepend the path to each recipient in
               the address list with the indicated path.  This
               overrides the value of auto_route, but has the exact
               same functionality.  See the explanation of the
               variable in the VARIABLES section.  Also see the MAIL
               ADDRESSES section for more information concerning
               replying to messages.

          save/write/copy [-f] [-s | -a] [msg-list] [filename / directory]
               (s/w) With no arguments, save and write will save the
               current message to the file mbox in the user's home
               directory (or the file specified by the mbox variable).
               If a message list is given, then the messages specified
               by the list are saved.  If a filename is given, then
               that filename is used instead of mbox.  The -s options
               forces the filename used to be that of the subject of
               the message.  Similarly, the -a option causes the
               filename used to be that of the author of the message
               being saved.  If more than one message is being saved,
               the subject or author name used is that of the smallest
               message number (since message lists have no order of
               precedence).  With these two options, a directory name
               may be given to specify a directory other than the
               current directory.

               If the file exists and is writable, the specified
               command will append each message to the end of the
               file.  If -f is given, then the file is overwritten
               causing whatever contents it contains to be lost.  For
               compatibility with older versions, the character `!'
               may be substituted for -f (no `-' is used with `!').
               If the current folder is the system mailbox, then saved
               messages are marked for deletion when the user exits
               using the quit command.  If the variable keepsave is
               set or the current folder is not the system mailbox,
               then messages are not marked for deletion.

               The write command differs from save and copy in that
               the message headers are not saved in the file along
               with the body of text.  The copy command is is like



     Page 44                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               save except that messages are never marked for
               deletion, whether or not keepsave is set.

               Because message lists are used to determine the
               messages to be saved, if the user wishes to save
               messages to a file that begins with a digit or any
               other message list metacharacter, a backslash should
               precede the filename to escape the message list
               expansion routine.  The backslash will not become a
               part of the filename.

          saveopts [file]
               The complement of source, saveopts, will save all
               settable variables, aliases and cmd's in the
               initialization file.  (See the INITIALIZATION section
               for more information on initialization files.)  If an
               argument is given, that file is used.  Beware that this
               will overwrite files, so any "if" expressions will be
               lost, as will settings that have changed since entering
               Mush.  Using saveopts is highly discouraged and is
               intended for the naive user only.

          set [[?]variable [= value]]
          unset variable
               With no arguments, set prints all variable values.
               Otherwise, it sets the named variable.  Arguments are
               of the form "variable=value" (whitespace is allowed).
               Boolean options such as autoedit need not have "=value"
               associated in the command.  Multivalued variables are
               set in the same way as other variables, and the list of
               values should be enclosed in quotes if whitespace is
               used to separate the items.  See the VARIABLES section
               for details of the format of each type of variable.

               The special command

                 set ?all

               will print all known variables utilized by the program
               and a brief description of what they do.  The user may
               set and manipulate his own set of variables, but
               internal variables that are utilized by the program are
               the only ones displayed.

               The command

                 set ?variable_name

               will print the same information for one variable
               instead of all variables.  You may unset everything by
               issuing the command "unset *".




     Page 45                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               It is possible to set a variable to a list of messages
               returned by another command by using the piping
               mechanism.  For example,

                 pick -s Status Reports | set reports

               The variable reports now contains a message list which
               can be used as the message list argument to any command
               which accepts a list.

                 mail -i $reports boss

               This command will mail to "boss" and include the text
               of all the messages held in the reports variable.

          sh [command]
               Invokes an interactive version of the shell.  The shell
               spawned is described by the variable shell.  If the
               optional argument command is given, then that command
               is executed under the Bourne Shell.  If the special
               character `&' is at the end of any shell command, then
               the command will be executed in background.

          source [file]
               Read Mush commands from a file.  If no filename is
               specified, the files searched for are .mushrc or
               .mailrc in the user's home directory.  If the
               environment variable MUSHRC or MAILRC is set, then the
               file named by the variable is sourced instead.  If a
               filename is given on the command line, that file is
               sourced.  See the INITIALIZATION heading and the home
               variable descriptions for more information.

          sort [-i] [[-r] -a | -d | -l | -R | -s | -S]
               This command will sort messages according to author,
               date, status or subject (with or without considering
               the "Re: ", in replied messages).  In addition, the
               messages can be sorted in reverse order (same
               arguments).

               Options:
                 -i   ignore case in alphabetical sorts
                 -r   reverse sort order of next option
                 -a   sort by author (alphabetical)
                 -d   sort by date
                 -l   sort by length of message
                 -R   sort by subject including "Re:"
                 -s   sort by subject (alphabetical)
                 -S   sort by message status

               By default (no arguments), sort sorts messages by
               status.  New, unread messages are first, followed by



     Page 46                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               preserved messages, and finally deleted messages are
               placed at the end of the list.  If -r is the only
               option given, the status ordering is reversed.

               When sorting by date, the boolean variable
               date_received is checked.  If it is set, then sorting
               goes by date received.  Otherwise (default), sorting is
               by date sent by the original author.

               If more than one sort option is specified, they will be
               applied in left-to-right sequence to each comparison.
               Thus:

                 sort -a -d

               sorts messages by author and, if the author of any set
               of messages is the same, sorts within that set by date.
               Note that the -r option applies to only one other
               option at a time; to reverse the sort of both author
               and date requires:

                 sort -r -a -r -d

               The options can also be grouped:

                 sort -ra -rd
                 sort -rard

               Currently, only the line mode interface supports
               multiple sort criteria, but the other interfaces allow
               subsorting indirectly when appropriate actions are
               taken, as discussed below.

               It is also possible to sort a consecutive sublist of
               messages by using pipes.  If the mailbox were already
               sorted by author,

                 pick -f [e-mail] | sort -s

               would find all messages from the user
               "[e-mail]" and sort them by subject.  You may
               specify the exact message list by specifying that
               message list on the command line and using a pipe:

                 10-. | sort d

               This command means to sort the messages from 10 to the
               current message according to the date.

               To specify subsorting from with the curses interface,
               the temporary curses escape key must be used (the colon
               `:') and the command issued at the `:' prompt (as if



     Page 47                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               giving an "ex" command to "vi").  When the command is
               finished, the "...continue..." prompt is given and the
               user may continue or return to the top level of the
               curses mode.

               The sort range must consist of consecutive messages.
               Reversed sorting is not currently available in tool
               mode.

               If the variable sort is set, messages are sorted each
               time the user's system mailbox is read as the current
               folder.  The sort variable can be set either to nothing
               or to legal "sort" arguments.

               Note:  For compatibility with older versions, sort
               options are recognized even if they are not preceded by
               a `-'.  Also, if a `-' is given by itself (separated by
               spaces from any following arguments) it is interpreted
               as -r.

          stop For systems with job control, stop will cause Mush to
               send a SIGTSTP to itself.  The command was introduced
               to facilitate the stop-job action from a complex
               command line alias rather than the user having to type
               his stop character explicitly.

          top  Takes a message list and prints the top few lines of
               each.  The number of lines printed is controlled by the
               variable toplines and defaults to the size of the value
               of the variable crt. This command is ignored in the
               tool mode.

          undigest [-m] [-p pattern] [msg-list] [filename]
               A "digest" is a mail message which is a collection of
               other mail messages mailed to a "moderator" by other
               users.  The moderator compiles all the messages into a
               folder and sends the result to all the subscribers of
               the mailing list.  The undigest command disassembles
               the entries into the set of messages which comprises
               the digest.

               The -m option will merge these messages into the
               current folder.  Otherwise, if a filename is specified,
               a new folder is created and the user can change folders
               to read the messages separately.

               The -p option specifies an alternate pattern to be used
               as the digest article separator.  This pattern must
               match literally at the beginning of the line.  The
               default pattern is "--------" (eight hyphens).  This is
               the defacto USENET standard digest article separator
               and should work for most digests, but some use another



     Page 48                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               separator.  The -p option is also useful for "bursting"
               forwarded messages out of a wrapper message; for
               example:

                   undigest -m -p "--- Forward"

               will burst out messages forwarded by another user of
               Mush and merge them into the current folder.

               If a message list is specified, each digest in the list
               is disassembled to the same filename (if given).  If no
               filename is given and the user did not request a merge,
               then a temporary file is made.

          update [-r]
               Updates your current folder, writing back changes just
               as if you quit.  Headers are not listed when the folder
               is read back in.  The -r option puts the folder into
               read-only mode after updating it.

               See the folder command for complete information.


     VARIABLES
          Shell variables are controlled via the set and unset
          commands.  Options may be either boolean, in which case it
          is only significant to see whether or not they are set;
          string, in which case the actual value is of interest;
          numerical, in which case the numerical value is important;
          or multivalued, in which case they may be set to a list of
          values.  Some variables may have attributes of boolean and
          string or multivalued at the same time.

          If you or the program references a variable that is not
          explicitly set, then the environment variables are checked
          and that data is returned.

          Variable values can be modified by one of four variable
          modifiers, or by a numeric string.  The modifiers `:h',
          `:t', `:l' and `:u' may be applied to the variable names.
          The current implementation allows only one `:' modifier on
          each `$' expansion.

          :t   The variable is treated as a file path name, and the
               name of the file (the "tail" of the path) is
               substituted for the variable.  That is, everything to
               the right of the last `/' is returned.

          :h   The variable is treated as a path name, and the "head"
               of the pathname is substituted for the variable.  That
               is, everything up to, but not including, the last `/'
               is returned.



     Page 49                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          :l   All alphabetic characters in the variable's value are
               converted to lower case.

          :u   All alphabetic characters in the variable's value are
               converted to upper case.

          :number
               The value of the variable is converted to a list of
               space-separated words, which are numbered from one (1),
               and the word described by number is selected and
               returned.  It is not an error for number to be greater
               than the actual number of words; an empty string is
               returned in this case.

          Following is a list of all variables with predefined
          meanings.

          alwaysignore
               (Boolean/Multivalued) If set with no value, the mail
               headers set by the ignore command are always ignored.
               Normally, ignored headers are not ignored when sending
               messages to the printer, when interpolating messages
               into letters with ~f or ~I, when the `P' or `T' command
               is given (see the print command), or with the -I flag
               to the mail or reply commands.  Setting alwaysignore
               will ignore those headers even in the situations
               mentioned here.  No headers can be ignored during
               updates and when using the save command since the user
               may ignore headers that are required by Mush or any
               other mail system to read those folders.

               This variable can also be set to a list of words
               separated by commas or spaces.  Currently recognized
               words, and their meanings, are:
                   forward       Ignore headers when forwarding messages (~f).
                   include       Ignore headers when including messages (~I).
                   pipe        The pipe command ignores headers.
                   printer       The lpr command ignores headers.

               Also see the ignore command and the show_hdrs variable
               for more information.

          ask  (Boolean) If set, you will be prompted for a subject
               header for outgoing mail.  Use the tilde escape "~s" to
               set the header once in the message or specify the -s
               option on the mail command line at the Mush prompt.

          askcc
               (Boolean) If set, you will be prompted for a Cc (carbon
               copy) list when you are finished editing a letter to be
               sent.  If the variable edit_hdrs is set, prompting will
               not occur, but a Cc: line will be added to the edit



     Page 50                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               file.  This also applies to the tool mode.

          autodelete
               (Boolean) When exiting mail, all messages that have
               been read regardless of whether they have been marked
               for deletion are removed.  Only messages that haven't
               been read or that have been marked as preserved are not
               removed.

          autoedit
               (Boolean) If set, you are automatically put into your
               editor whenever you send or reply to mail.

          autoinclude
               (Boolean) When replying to any mail, a copy of the
               message being replied to is automatically inserted into
               your message body indented by the string described by
               the variable indent_str.

          autoprint
               (Boolean) After you delete a message, the next message
               is printed automatically.

          auto_route
               (Boolean/String) If set boolean (not to a string), all
               the recipients in a message that is being replied to
               (via replyall), will be routed through the path back to
               the original author.

               For example, if the original sender of a message came
               from the remote host c3p0 and the list of recipients
               looked like

                 From: c3p0!user1
                 To: yourhost!you
                 Cc: r2d2!user2, r2d2!user3

               then clearly, "user1" on the machine c3p0 can talk to
               your machine and the machine named r2d2.  However, you
               would not be able to respond to those users if your
               machine did not exchange UUCP mail with the host r2d2.

               Mush will attempt to solve this problem by
               reconstructing the addresses for "user2" and "user3"
               according to the address of the original sender,
               "c3p0".  The new addresses for "user2" and "user3"
               should therefore become

                 c3p0!r2d2!user2, c3p0!r2d2!user3.

               If your machine not only talks to c3p0, but talks to
               r2d2 as well, it becomes unnecessary to route the mail



     Page 51                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               through both c3p0 and r2d2.  So, the variable
               known_hosts may be set to a list of hosts which you
               know your machine to have UUCP mail connections with.
               This list is checked when constructing mail addresses
               for replies only and the shortest path is made by
               removing from the UUCP path those hosts that do not
               need to be called or are redundant.  See the entry for
               known_hosts for more information.

               If auto_route is set to a specific pathname (host names
               separated by !'s), all addresses in the reply will have
               this route prepended to their addresses.  This ignores
               the original path of the author.  This is quite useful
               for hosts which talk uucp to a node which is connected
               to the internet or uunet since both of those machines
               tend to be one-hop away from all other hosts (or
               reroute accordingly).  For example, if a message was
               addressed like so:

                 To: [e-mail], [e-mail]
                 Cc: ucbcad!foo!bar

               If auto_route were set to "ucbcad", then replies to
               this address would be directed addressed like so:

                 To: ucbcad!ucbvax.berkeley.edu!root, ucbcad!zipcode.uucp!argv
                 Cc: ucbcad!foo!bar


               This assumes that the host in question talks uucp with
               ucbcad.  This example demonstrates several things.
               First, notice that all addresses are converted to
               uucp-style format.  Whenever routing is changed, the
               format is converted like this.  Secondly, note that the
               Cc: line did not change.  This is because all redundant
               hostnames from UUCP pathnames are removed to avoid
               unnecessary UUCP connections and speed up mail
               delivery.

               Another example of how auto_route truncates UUCP paths:

                 pixar!island!sun!island!argv

               Here, mail was probably originally sent to users at
               pixar and sun from somewhere undetermined now.  Since
               sun and pixar do not talk to each other, the users on
               those machines may have responded to mail creating the
               type of addresses stated above.  Here, it can be seen
               that we can reduce the path to the host island:

                 pixar!island!argv




     Page 52                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               See the MAIL ADDRESSES section for more detailed
               information about legal mail addresses.

               Note that the -r flag to reply and replyall overrides
               the value of auto_route.

          autosign
               (Boolean/string) Append a signature to outgoing mail.
               If this variable is set, but not to a string (e.g.,
               boolean-true) then the file ~/.signature is used.

               Otherwise, the variable is interpreted in one of four
               ways.  By default, the string is interpreted as a
               pathname relative to the current directory.  For this
               reason, it is advisable to use full pathnames here.  As
               usual, the special characters `~' and `+' are expanded.
               If a file is found, it is opened and its contents are
               read into the message buffer.

               If the variable is set to a string that begins with
               `$', then that string is interpreted as a user-
               definable variable and is expanded and appended to the
               letter.

               If the variable is set to a string that begins with a
               backslash (\) then the string itself (minus the `\'
               character) is used; no expansion is done and no files
               are read.

               Finally, if the variable is set to a string that begins
               with a vertical bar (or "pipe") character (|), the rest
               of the string is interpreted as a command whose output
               will be used as the signature.  The special characters
               `~' and `+' are NOT expanded in the command name, but
               the command is run via /bin/sh so $PATH will be
               searched and redirection can be specified.  The list of
               addresses to which the letter will be sent is passed to
               the command as its arguments, in the same form that
               they will be passed to the Mail Transport Agent (MTA).
               Depending on your MTA, each address may be followed by
               a comma.

               In the latter three cases, it is advisable to set the
               variable using single quotes to protect the `$', `\'
               and `|' characters from being interpreted.  Examples:

                 set autosign = '$foo'
                 set autosign = '\  Dan Heller zipcode![e-mail]'

               Warning:  if redirection from the calling shell is
               used, no signature or fortune will be added to outgoing
               mail.  For example,



     Page 53                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



                 % mush -s report manager < report_file

               In this command, mail is being sent to the user
               "manager" and the subject is set to "report" and the
               file "report_file" is being redirected as input.  In
               this case, there will be no signature appended.

               Note:  The `|' syntax for calling a program to sign the
               letter is a little counterintuitive and may change in
               future releases.

          autosign2
               (String) This alternate signature is available for
               special cases where the default signature is not
               desired or if no signature is desired for special
               addresses or if only special addresses require a
               signature.  The format for this variable is:

                 autosign2 = "address1, address2, ... : <signature>"

               Each address can be one of these types:

               1)  address
                    Legal mailing addresses that do not contain
                    comment fields (see the sections MAIL ADDRESSES
                    for more information on legitimate mail addresses)
                    will match literally.

               2)  *username
                    If the username is present on the recipient list,
                    regardless of what remote site the user may reside
                    on (including locally), the pattern matches.

               3)  !hostname !host1!host2...
                    Any user who appears as a recipient will match the
                    pattern provided he resides on the specified
                    hostname.  If a path of hosts is specified, then
                    the user must reside on the last host of the
                    specified path.

               4)  @sub.domain
                    The user must reside on any host within the domain
                    specified.  Neither the user or the hostname needs
                    to match; only the domain name must be required to
                    match.

               Example:

                 set autosign2 = "!zipcode @sun.com @mit.edu *schaefer root: --dan"

               This means that any mail sent to 1) anyone at zipcode,
               2) anyone within the sun domain, 3) anyone within the



     Page 54                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               mit domain, 4) Bart Schaefer (at any host anywhere --
               even locally), and 4) root on the local machine only
               (or, root@local-machine-name) will be signed with the
               "alternate" signature.  If any address on the recipient
               list fails to satisfy these four matches, the mail will
               be signed by my regular signature.

               One can have a local signature and a remote signature
               by specifying the autosign2 to include the hostname of
               the home machine the user is logged into.  Note the
               "zipcode" example above.

               The list of recipients, after alias expansion and
               comment removal, is then scanned and the following
               patterns are matched against those addresses specified
               in the autosign2 or fortunates variable according to
               these rules.

               The signature description is the same as described by
               autosign variable.  The colon (:) separates the list of
               addresses from the signature description.  If there is
               no colon or the address list is missing, the entire
               string is considered the signature (except for the
               colon).

               If autosign is not set, then autosign2 will ONLY work
               if the tilde command "~S" is specified.  In this way, a
               user may never have autosign set and just set autosign2
               to be some signature value.  The user may then issue
               the tilde command to automatically sign the letter.  If
               a list of addresses is given (terminated by a colon),
               then all recipients of the message must be in the list
               of addresses in autosign2; otherwise, the signature in
               autosign (if set) is used instead.  A null signature in
               autosign2 will not sign the letter.

               Example:

                 set autosign2 = "fred, barney, wilma, betty: ~/flintstone.sig"

               If a message is sent to:

                 To: fred, wilma

               Then the file ~/flintstone.sig will be used.  However,
               if the address were:

                 To: barney, betty, bambam

               Then autosign2 will not be used because bambam is not
               in the list.




     Page 55                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               Note that mail sent via redirection from the calling
               shell will not sign letters or append fortunes.

          cdpath
               (String) Set to a string of pathnames separated by
               spaces to use when searching for a directory when the
               cd command is issued.  If this variable is used, it is
               recommended that the path `.' be included.  Note that
               this differs from the csh, which does not require that
               `.' be present.

          cmd_help
               (String) This variable gives the path name of the
               general help file, which is read by the help command.
               This variable is normally reset only in the system
               initialization files, when the default location of the
               help file has changed.

          complete
               (String) Setting this variable enables word completion.
               The first character of the value of complete is used as
               the completion character; if complete is set, but not
               to a value, the escape character is used as the
               default.  When the completion character is typed at the
               end of a word prefix, Mush will interactively complete
               that word.  If the prefix is not unique, the word will
               be completed as far as possible and a bell will sound
               (see, however, the variable quiet).  If the word
               contains filename metacharacters, all possible matches
               will be completed.  If the list overflows the command
               line buffer, it will be truncated, so this feature
               should be used with care.  Metacharacters recognized
               are the same as in csh.

               The second character of the value of complete is used
               as the completion listing character.  When this
               character is typed, the possible completions will be
               printed, and Mush will prompt again with the original
               prefix.  If complete is set to only a single character,
               completion listing is disabled; if it is set with no
               value, control-D (^D) is used as the default listing
               character.

               See the description of the variable fignore for ways to
               exclude filenames from completions.

               Word completion is currently supported only for file
               names.  Command name and alias completion may be added
               in a future version.  Completion is not possible if the
               -e (-echo) flag was given, and is currently not
               available in tool mode.




     Page 56                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          crt  (Numeric) Set to a value that describes the number of
               lines a message must have before invoking the pager to
               view a message.

          crt_win
               (Numeric) Set to the height (in lines) of the message
               display window in tool mode.

          curses_help
               (String) This variable may be set to a space-separated
               list of curses mode command names (see the CURSES
               section for the possible choices).  If set but without
               a value, a default list established by your Mush
               maintainer is used.  When it is set, a display of the
               current bindings for the listed commands will appear at
               the bottom of the screen in curses mode.  This help
               display will normally shorten the display of headers,
               but the the user may explicitly scroll over the help
               display if he wishes to see more headers.

          cwd  (String) The current working directory string is
               automatically set upon startup of Mush and is reset
               each time the commands cd and pwd are called.  It may
               be changed or referenced like any other shell variable.

          date_received
               (Boolean) When message headers are printed, the date is
               normally shown is the time and date the sender sent the
               message.  If this variable is set, then the date
               displayed is the date received.

               When sorting messages by date, this variable is queried
               to determine whether the messages should be sorted by
               date sent or date received.

               Warning: For mailers that store messages without a line
               that starts with "From ", this option does nothing.

          dead (String) File to use instead of dead.letter when
               interrupted mail is saved.  May be set to a unix
               command by prefixing the value with `|'.  For more
               information, see the variable nosave.

          domain_route
               (Boolean/String) In combination with auto_route, this
               variable specifies that addresses containing a fully-
               qualified domain should be short-circuited to mail
               directly to the rightmost fully-qualified domain.  If
               set boolean (not to a string), only short-circuiting is
               done.  If set to a string, the address is rewritten to
               UUCP form and the value of the variable is prepended.
               Domain short-circuiting applies only to addresses



     Page 57                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               containing a fully-qualified domain, but short-circuits
               in spite of any path specified with the -r flag of
               reply or through the string value of auto_route (thus
               possibly omitting the auto_route or -r paths
               altogether).  See auto_route for more information.

          dot  (Boolean) Causes Mush to accept a `.' on a line by
               itself, in addition to `^D', to terminate messages.

          editor
               (String) Specifies the editor to use when the "~e"
               escape or the edit command is used.  Default is the
               value of the environment string EDITOR or the variable
               visual.

          edit_hdrs
               (Boolean) When in letter-composition mode (via mail or
               reply, etc), the headers of the outgoing message are
               stored in the same buffer as the text of the letter.
               So, if the editor is called to edit the message buffer,
               the headers of the message can be edited as well.
               However, there are some restrictions.

               There must be a To: header.  Without this, Mush will
               not deliver the letter.  Instead, the editor must be
               reentered and a To: header with a valid recipient must
               be inserted.  A valid Cc: header does not remove this
               restriction.  You may have as many To: and Cc: headers
               as you like.

               The From: header normally should not be changed.  If
               you change this header to an address that Mush is
               unable to identify as authentic, the original From:
               header will silently be put back.

               The Date: header will always be replaced by one with a
               more accurate time and date stamp.  Therefore, changing
               or removing this header has no effect.

               You cannot add a Status: header, and blank headers are
               dropped.  For example, if an empty Cc: header exists,
               the header will not show up in the outgoing message.
               Therefore, leaving empty headers has no effect.

               Aliases specified on the command line are expanded and
               put into the message buffer in their expanded form
               regardless of the value of no_expand. However, if the
               user changes the headers using the editor and specifies
               aliases, those aliases will not be expanded if
               no_expand is set.  Otherwise, they are expanded as
               usual.




     Page 58                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               The headers Bcc: and Fcc: are removed as expected.

               One added side effect of edit_hdrs is that you can add
               an Fcc: header to specify a "File Carbon Copy".  This
               must be a pathname to a file or program.  For programs,
               the pathname must be preceded by a pipe character (|).
               Note that all addresses on the Fcc: line that do not
               begin with `|' are interpreted as file names; don't put
               other kinds of addresses there.

               When using edit_hdrs, certain tilde escapes don't work.
               Specifically, any tilde escape that allows you to add
               or set headers or to empty the file are inactive.
               These functions are to be done in the editor only.

               Once a letter is being edited, edit_hdrs cannot be set
               or unset; the user must end the letter (either by
               sending it or forcefully terminating it) first.

               Header editing is required (and happens automatically)
               when using the "Compose" tool mode item.

          escape
               (Character) When composing a mail message (not in an
               editor), and the escape character is the first
               character on the line, the next character is examined
               and a corresponding function associated with that
               escape command is executed.  See tilde escapes for more
               information.

          fignore
               (String) This variable is tested when filename
               completion is used (see the variable complete for
               details).  The value of fignore may be a list of
               filename extensions (".c", ".o", etc.), a list of
               filename patterns containing metacharacters (*?{}[]),
               or a mixture of the two.  Each element in the list must
               be separated from the others by a space.  When a
               filename completion occurs, any filenames with the
               extensions listed in fignore, or matching the patterns
               given there, will be omitted from the completion.

               For example,

                   set fignore = ".o .s [Mm]ake*"

               will cause any filename ending in ".o" or ".s", and any
               filename beginning with "Make" or "make", to be
               excluded from completions.

               If all files in the current directory match the
               extensions or patterns, fignore is disabled and



     Page 59                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               completion will occur.  For this reason, it is usually
               not a good idea to include "*" in the list.

          folder
               (String) The folder variable is set to the path of a
               directory where folders are kept.  This path is used by
               various commands to expand the `+' metacharacter (see
               the folder command for details).  "~/Mail" is the
               default expansion of `+'.

          fortune
               (Boolean/string) If fortune is set, a random fortune is
               appended to the end of all outgoing mail using the
               UNIX(TM) command /usr/games/fortune (may vary from
               system to system).  If fortune is set to something that
               starts with a `-', then it is interpreted as a flag to
               fortune (e.g., "-o").  If fortune starts with a `/',
               then the program described by the string is executed
               (thus not doing fortune at all, if you want).  By
               default, fortune -s (short fortunes) is used.

          fortunates
               (String) When fortunes are added to messages, sometimes
               it is desirable to make sure that only a selected group
               of people get a fortune since certain people may not
               understand the messages at the end of your mail.
               Therefore, you can set a list of addresses (either pure
               addresses or aliases that are expanded to addresses) to
               be the only people who receive fortunes if one is to be
               appended.  Therefore, if the To: and Cc: lines contain
               only address listed in this string variable, then a
               fortune is appended to the message.  If those lists
               contain names that are not on the fortunates list, then
               no fortune is added.  This cannot be overridden; using
               the tilde command "~F" does not force a fortune to be
               added unless the individuals on the recipient list are
               all included in the fortunates list.  The list is made
               up of addresses or aliases separated by spaces or
               commas.  NOTE: fortune must be set in order for
               fortunates to work.

          hangup
               (Boolean) If this variable is set, Mush will update
               your folder before exiting when it receives a SIGHUP
               signal.  This is useful if you frequently read mail
               when dialed in over a noisy phone line that often drops
               carrier.

               WARNING:  Certain errors are ignored during this
               update, because it is presumed to be impossible to
               query the user for instructions.  Except in the event
               of a write error, the folder will be forced to contain



     Page 60                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               exactly those messages that were not deleted at the
               time of the hangup.  In particular, this means that if
               an error occurs when loading new mail before the
               update, the new mail will be lost.  Write errors will
               still cause both the working tempfile and as much of
               the folder as possible to be preserved.

          hdr_format
               (String) This variable controls the format of the
               headers displayed by the headers command and in the
               curses and tool modes.  The format style of this
               variable string is similar to printf in C.  When
               printing the information, the variable is evaluated and
               each character in the string is echoed unless a `%'
               character is encountered.  If one is found, the
               following string substitutions are made:

                 %a      address of the author
                 %c      number of characters (bytes) in the message
                 %f      entire "From:" field (author)
                 %l      number of lines in the message
                 %i      the message-id (may not be present)
                 %n      name of the author
                 %s      subject of the message
                 %t      "To:" field (recipients)
                 %d      date and time of the message
                 %T      time only of the message
                 %N      day number of the month of the message
                 %W      day of the week (Sun, Mon, etc.)
                 %M      month name of the message
                 %Y      year of the message
                 %y      last two digits of %Y
                 %Z      time zone of the message
                 \n     a newline
                 \t     a tab

               A field width specifier may be used in all options.
               Thus, "%20f" will print the first 20 characters of the
               from line.  No matter what the formatting string, the
               message number followed by a `>' (for current message)
               is printed.

               The "address" and "name" of the author are extracted
               from the "From:" field of the message.  The name may be
               given in parentheses and the rest of the line is the
               address, or the address is given in angle brackets (`<'
               and `>') and the rest of the line is the name.
               Sometimes the address is the only thing on the line, in
               which case the name and address are the same.

               A special format is also provided to obtain the
               contents of any header not listed above.  If a format



     Page 61                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               of the form "%?header-name?" (both leading and
               following `?'  characters are required) appears in the
               value of hdr_format, the named header will be looked
               up.  For example,

                   set hdr_format = "%a %n %?phone?"

               causes the electronic address, name, and (if a "Phone:"
               header is present) phone number of the sender to be
               displayed.

          history
               (Numeric) This variable is set to the number of
               commands the shell interface will remember.  It is just
               like the history variable used in csh. If unset, the
               last command can always be referenced, but none other.

          hold (Boolean) Normally, on termination of mail, read
               messages are saved in your mbox (except those marked as
               preserved).  Setting hold prevents this from happening,
               and messages remain in /usr/spool/mail/user.  This does
               not apply to folders, obviously.

          home (String) This variable describes the user's home
               directory.  The variable is initialized to the value of
               the environment variable HOME, but can be modified at
               any time during the Mush session.  The home directory
               is the same directory where temporary files are kept
               for editing and so forth.  If the home directory cannot
               be found or read/write access is denied, an alternate
               directory, typically /tmp, is used.

          hostname
               (String) This is the name of your computer.  Currently,
               its sole usage is to compose a correct "From:" line for
               use with Mail Transport Agents that do not create this
               header automatically.  This will aid the recipients of
               your mail in replying to your messages.

               Note: the user should not have to set this variable
               since it should be set automatically by the system.
               However, it may happen that the system's hostname
               cannot be queried and the user may have to set this
               variable manually.

          ignore_bang
               (Boolean) If set, Mush will ignore the `!' character as
               a history reference.  Note that this severely limits
               use of the cmd facility, which depends upon history
               references for argument substitutions.

          ignoreeof



     Page 62                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               (Boolean/string) If set, `^D' will not exit from Mush.
               If set to a string, that string is executed as a
               command when `^D' is typed.  This does not effect
               termination of messages under the mail and reply
               commands.

          indent_str
               (String) When including messages into the text of a
               letter you are editing, each line of the messages is
               preceded by the value of indent_str.  If it is unset,
               the message body is indented by the string "> ".  See
               also the variables pre_indent_str and post_indent_str.

          in_reply_to
               (String) This variable may be set to a string that will
               complete the header "In-Reply-To:".  The format of this
               string is identical to the options for the variable
               hdr_format.

               For example, if the user were to respond to a message
               from Dan Heller that was sent on October 21, 1987, at
               10:39pm, with in_reply_to set to the string

                 %n's message as of %d.

               the header line

                 In-Reply-To: Dan Heller's message as of Oct 21, 1987, 10:39pm.

               would be added to the message.

          keepsave
               (Boolean) If set, the commands save and write will not
               mark messages for deletion.

          known_hosts
               (String) Used in conjunction with the variable
               auto_route, this variable is set to a list of hosts,
               separated by spaces, tabs, and/or commas, and describes
               the hosts with whom you know your machine shares UUCP
               connections.  When replying to mail, many times you
               will see that the return path constructed will have
               hostnames that your site could call, but instead the
               mail has been routed through a number of different
               machines first.

               For example, if you respond to mail that would mail to
               the path

                 unicom!pixar!root

               but your know your machine already calls pixar, then



     Page 63                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               sending the mail to unicom first is unnecessary.  If
               you have set your known_hosts string to include pixar
               in its list, the resulting address would look like

                 pixar!root

               Also see the command replyall for more information on
               constructing correct return addresses.

          logfile
               (String) Set to a filename which logs the headers of
               outgoing messages.  The message body of the message is
               not logged as it is for the record filename.  The
               logfile can be read as a folder to scan for the fact
               that messages have been sent.  If logfile and record
               are both set, then the logfile and the record files
               will match exactly.  In this case, the record file can
               be quickly scanned by scanning the log file instead.

               If set, but not to a string, the log file defaults to
               ~/mail.log.

          mail_icon
               (String) Set to a pathname for an alternate icon pixmap
               to use when the Mush tool is closed.  The number of
               messages in the mailbox is displayed as an icon label
               unless the string iconlabel appears as one of the
               values of the variable quiet.  See also the variable
               newmail_icon for the icon displayed when new mail
               arrives or is present.

          mbox (String) Set to the pathname of a file you'd like Mush
               to use as the default folder for read mail.  The
               default is ~/mbox.

          metoo
               (Boolean) When replying to mail, you are normally
               deleted from the list of recipients.  If metoo is set,
               you remain on the list.  See the alternates command for
               information on determining whether or not you're even
               on the list.

          mil_time
               (Boolean) Whenever the time is displayed in a message
               header or in the prompt, it can be displayed in either
               12-hour am/pm format, or in 24 hour military time
               format.  The default is the 12 hour format, but can be
               reset to use the 24 hour format by setting this
               variable.

          newline
               (Boolean/string) If set, carriage returns are ignored.



     Page 64                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               If set to a string, that string is executed as a
               command when a carriage return is typed.  Otherwise,
               carriage return prints the next undeleted message.
               newmail_icon (String) Set to a pathname for an
               alternate icon pixmap to use when new mail is
               available.

          no_expand
               (Boolean) When a Mush alias is used to reference a list
               of addresses, the list is expanded on the To: and Cc:
               lines to indicate the complete list of all the
               recipients of the message.  When no_expand is set,
               aliases are not expanded and the headers reflect the
               same information as typed by the user.

          no_hdrs
               (Boolean) If set, this variable tells Mush not to
               include your personalized mail headers in messages.
               This does not unset your headers, it just disables
               them.

          no_reverse
               (Boolean) In curses mode and in the tool mode, reverse
               video is not used to indicate the current message if
               this variable is set.  In the tool mode, if reverse
               video is not in use, text is displayed in "bold".

          nonobang
               (Boolean) If this variable is set, history references
               that don't match anything will be left unexpanded,
               rather than generating error messages.  This is useful
               if you want argument referencing in cmd expansions, but
               do not want to remember to escape every `!' you type in
               UUCP addresses.  It is also recommended for use with
               curses mode, because history is not kept for line mode
               escapes from that interface.

          nosave
               (Boolean) When composing a letter, the user can
               terminate the letter without sending it by using the
               tilde escape "~q" or by sending two "interrupt"
               signals.  When the message is terminated, a copy of it
               is saved to the file "dead.letter" in the user's home
               directory or to the file described by the variable
               dead.  If the variable nosave is set, then a backup
               copy of the message will not be saved.

          output
               (Read-only string) This variable holds a message list
               representing the output of the last successful command.
               This is useful for recovering from broken pipes or to
               capture the output of a command without affecting the



     Page 65                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               information it displays (some commands limit or
               suppress output when used in a pipeline).  Commands
               which return an error status (see the variable status)
               do not affect the value of output, but successful
               commands that return no message list will clear it.
               Also, many curses mode commands return an error status
               to indicate that the display has been altered, even if
               no actual error occurred.  This variable is thus most
               useful in line mode and in scripts.

          pager
               (String) If a message is longer than the number of
               lines that the variable crt is set to, then this
               program is executed to view a message.  If the user
               does not have this variable set, the user's environment
               PAGER is checked.  If this isn't set, then the default
               value for pager (set up by the system manager) is used.
               This may or may not be the internal pager.  To use the
               internal pager, you may set the variable pager to
               internal or to a null string.

          pre_indent_str
               (String) If this variable is set, when including the
               body of a message into an outgoing mail message (using
               the -i option to reply or mail, or when using the "~i"
               escape), a line preceding the first line of included
               text is printed using the string value of the variable.
               This string uses the same printf style formatting
               characters as the hdr_format variable.  For example,
               you could set pre_indent_str as follows:

                 set pre_indent_str = '[In the message entitled "%s",
               on %7d\n %n writes:]'

               You can then include a message body using "~i", and you
               might get something like this:

                 [In the message entitled "This is a test.", on Jan 19,
                  Dan Heller writes:]
                 > This is a test message to show how
                 > pre_indent_str might be used.

               This example assumes that the string value of
                 indent_str is not set.

          post_indent_str
               (String) This variable has the same function as
               pre_indent_str except that the string is inserted into
               the message body after the text of the included message
               rather than before.  The purpose of this variable is to
               complement the string described by the variables
               pre_indent_str and indent_str.  For example,



     Page 66                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



                 set pre_indent_str = "/*"
                 set indent_str = " * "
                 set post_indent_str = " */"

               An included message might look something like this:

                 /*
                  * This is a test message to show how
                  * post_indent_str and pre_indent_str
                  * can work together with indent_str.
                  */

          printer
               (String) Used to set the default printer for the lpr
               command.

          print_cmd
               (String) This string should describe a UNIX(TM) command
               other than "lpr" for sending messages to the line
               printer.  Some people may choose to use a device
               independent troff style program, but virtually any UNIX
               command will suffice.  Common usage might include:

                 set print_cmd = 'ptroff -ms -Plp'
                 lpr .-$

               This command would send all messages from the current
               message to the last message through the ptroff command,
               supplying the appropriate arguments.

          prompt
               (String) You can set your prompt to tell you many
               different pieces of information.  By default, the
               prompt is set to the string

                 "Msg %m of %t: "

               If you have 10 messages and your current message is 5,
               then your prompt would look like:

                 Msg 5 of 10:

               The string value that prompt is set to will be printed
               as your prompt.  If the string contains a `%', then
               that character is ignored, the next character is
               evaluated and an appropriate value is printed in its
               place:

                 %F      full path name of the current folder
                 %f      name of the current folder (tail of %F)
                 %m      "current message" number
                 %t      total number of messages



     Page 67                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



                 %n      number of "new" messages
                 %u      number of unread messages
                 %d      number of deleted messages
                 %T      current time (hours and seconds)
                 %N      today's date (Number of the day in the month)
                 %W      weekday name (Sun, Mon, Tue, ...)
                 %M      current month
                 %Y      this year
                 %y      last two digits of %Y
                 \n     a newline
                 \t     a tab

          quiet
               (Boolean/Multivalued) This variable tells Mush to be
               quiet in various circumstances.  If set, but not to any
               values, the currently running version of Mush is not
               printed on startup.  Otherwise, quiet may be set to one
               or more words separated by spaces or commas.  Currently
               recognized words are:

                   autosign        Suppress messages when appending signature.
                   await       Suppress await's bell for new mail.
                   complete        Suppress word completion error bells.
                   fkey        Suppress warnings about unset function keys.
                   fortune       Suppress messages when appending fortune.
                   iconlabel       Suppress showing message count as icon label.
                   newmail       Suppress new mail notification messages.
                   pick        Suppress descriptions of pick searches.
                   startup       Suppress the startup message.
                   tool        Suppress tool mode bell for new mail.

               Error conditions for signatures and fortunes are still
               reported.  See the variables autosign, complete, and
               fortune for more details.  The newmail setting does not
               prevent automatic inclusion of new mail, it only
               suppresses the announcement of its arrival, including
               tool mode bells.  The fkey setting applies only to tool
               mode.

          realname
               (String) Set to the name of the user.  The name is
               initialized to the value of the environment variable
               NAME upon invocation of the program.  If that isn't
               set, then the name is gotten from the password file if
               available.  If this variable wants to be reset or
               changed after the program has started, the user should
               issue the command:

                 set realname = "Your name here"

          record
               (String) Set to the name of a file to record all



     Page 68                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               outgoing mail.  This should be a full pathname or the
               current directory is searched.  The pathname may begin
               with `+' (indicating the user's ~/Mail directory or the
               value of the folder variable) or with a `~' (or
               "~user") indicating the user's home directory.

          reply_to_hdr
               (String) When replying to mail, Mush searches for
               return paths from the message by searching for the
               message headings "Reply-to", "Return-path", and
               "From:", in that order.  If none are found, then the
               first line of the message created by the delivery
               system is parsed and the address given there is used.
               This special message header is created by most mail
               delivery programs, but not all of them (MMDF, for one).
               This line is called the From_ header because it is a
               colon-less header, but contains the return address of
               the author of the message.  If the variable
               reply_to_hdr is set to a list of headers (delimited by
               spaces or commas), then that list is searched.  If none
               of the headers listed in the variable exist in the
               message, then a warning message is printed and the
               default headers are used.  The special case From_
               header can be specified as one of the headers to search
               for.

                 set reply_to_hdr = "sender reply-to return-path from_"

               This example shows that Mush will search for (in
               order), the headers listed in the reply_to_hdr
               variable.  If one header isn't found, then Mush looks
               for the next in the list.  If none of the headers in
               the list are found, the default headers (mentioned
               above) are searched.  The last header listed in the
               example is the special "From " header.  Also see the
               reply command.

          save_empty
               (Boolean) Normally, when all messages in a folder are
               deleted and the user updates the folder or changes to a
               new folder, the empty folder is deleted.  save_empty
               prevents the folder from being deleted and it is left
               zero length.  Note: the main system mailbox is never
               deleted, even when empty.

          screen
               (Numeric) May be set to the number of message headers
               to display at a time in the line and curses modes.

          screen_win
               (Numeric) May be set to the number of message headers
               to display in the tool mode.  A subwindow is created



     Page 69                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               for message headers, and its size is large enough to
               hold $screen_win headers.

          sendmail
               (String) If set, the program and arguments described by
               this variable will be executed to actually deliver mail
               sent by Mush.

          show_deleted
               (Boolean) If true, deleted message headers are
               displayed along with other messages (`*' indicates a
               deleted message) for the headers command.  Also,
               deleted messages can be displayed using any command
               which displays a message.  In curses mode, this
               variable is ignored and deleted messages are always
               displayed with other messages to facilitate undeleting
               messages.

          show_hdrs
               (Multivalued) Set to a list (space and/or comma
               separated) of headers that are to be the only headers
               displayed when viewing a message.  This variable
               disables the headers suppressed by the ignore command.
               For example,

                 set show_hdrs = "from date subject to cc"

               will only display the headers From: Date: Subject: To:
               Cc: in their entirety.

          sort (Boolean/string) The value of this variable is the same
               as the arguments to the sort command.  This variable is
               used for the initialization file to presort mail in the
               system mailbox upon entering Mush.  See the COMMANDS
               section for more information.

          squeeze
               (Boolean) Whenever messages are read, piped, or saved,
               if this variable is set, all consecutive blank lines
               are squeezed into one blank line.

          status
               (Read-only numeric) This variable records the success
               or failure status of the most recently executed
               command.  All line-mode commands return 0 (zero) for
               success and a negative value for error.  Some curses
               mode commands return an error status to indicate that
               the display has been corrupted, even when no actual
               error has occurred.  This variable is most useful in
               scripts to test the success of an operation before
               proceeding.




     Page 70                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          tmpdir
               (String) This variable describes the path to use as the
               directory for all tempfiles that Mush uses.  By
               default, the user's home directory is used.  If that
               cannot be accessed, a directory writable by all is used
               (typically, /tmp).  If tmpdir is set, then it is used
               first.

          thisfolder
               (Read-only string) The full path name of the current
               mailbox.  This variable cannot be modified or displayed
               by the set command; its value changes whenever a new
               folder is entered with the folder command.  During
               sourcing of the initialization files, thisfolder is not
               set, because the current folder has not yet been read.
               If you refer to "$thisfolder" in an initialization file
               (e.g., .mushrc), be sure to do so inside an "if
               $?thisfolder" test.

          toplines
               (Numeric) The number of lines of a message to print
               when the top command is issued.  If unset, $crt lines
               are printed.  Note that the message body only is
               printed when using the top command; message headers are
               not counted as lines since they are not displayed.

          unix (Boolean) If set, commands that are not Mush commands
               are considered to be UNIX(TM) commands.  This removes
               the inconvenience of requiring the user to do shell
               escapes to do quick UNIX commands.  For systems that
               support job control, SIGTSTP will stop the entire shell
               as well as the process being executed.  When SIGCONT is
               delivered, both will receive the signal and the shell
               will continue to wait for the job to finish.

               Due to the lack of real job control, input/output
               redirection and UNIX command piping, this mode of the
               shell is not intended to be used as a login shell.

               If a Mush command conflicts with a UNIX command, use
               the command sh to force execution as a shell command or
               use the full pathname of the command (e.g. starting
               with a '/').

               Warning:  Be aware that Mush pipes transmit message
               lists, NOT TEXT. You cannot pipe the output of UNIX
               commands to or from Mush commands or other UNIX
               commands with the Mush pipe mechanism.  You can,
               however, pipe Mush commands to a final UNIX command
               (see the pipe command for more information).  UNIX
               commands should be simple commands without pipes or
               metacharacters.



     Page 71                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               This feature is not available for the tool mode.

          verbose
               (Boolean) Passes verbose flag to mail delivery systems
               when sending mail, and causes Mush to print additional
               information about the sending process.

          verify
               (Boolean) When through editing messages, just before
               sending, verify will ask you if you want to send,
               continue editing, or abort the whole message
               altogether.

          version
               (Read-only String) The value of this variable is the
               version string, printed by Mush at startup (unless
               quiet is set) and included in the "X-Mailer:" header in
               messages.

          visual
               (String) May be set to the visual editor to use when ~v
               is specified.  Default is vi or the environment string
               VISUAL.  The visual editor is invoked by the -e
               arguments to the commands, respond and mail.

          warning
               (Boolean) If set, warning messages are printed when:
                 +o A command line alias ("cmd") looks like a command.
                   For example,
                     cmd mail 'set fortune; \mail'
                     cmd respond 'unset fortune; \respond;'
                 +o The date format of a message is unknown.
                   The date of a message is taken from the "Date:"
                   header.  If the date on that header is unknown,
                   other headers are searched for a valid date format
                   until a legal one is found.  This date may not be
                   correct in that it was the date the message was
                   received, not sent.
                 +o A variable is unset without first being set.
                   For example, if you give the command
                     unset metoo and the variable metoo is not set,
                   you will be notified that the variable is not
                   defined.
                 +o No header can be found for a digest article.
                   This occurs when the undigest command encounters
                   what appears to be an article separator but cannot
                   find a "From:" or "Date:" header in the following
                   text.

               The intent is so that users who are used to their own
               environments will be aware of changes in other
               environments should they be forced to use them.  There



     Page 72                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               may also be warning messages of failed routines or
               assertions that are not fatal enough to interrupt
               normal running of the program.

          wrap (Boolean) Normally, when the last message is deleted,
               the current message pointer remains pointing to the
               last message and the user is done reviewing his mail.
               If the wrap variable is set, the current message
               pointer will wrap around to the beginning of the user's
               messages again to the next undeleted message.  This
               also applies to the next command.

          wrapcolumn
               (Numeric) May be set to a column number at which line
               wrap will occur when composing messages.  If set, but
               given no value, column 78 will be assumed.  When Mush
               is able to determine the number of columns on your
               screen, it will enforce a maximum value for wrapcolumn
               of two less than that number of columns.  Line wrapping
               can be disabled either by unsetting wrapcolumn or by
               setting it with the explicit value of 0 (zero).

               Line wrapping occurs only at whitespace (spaces or
               tabs).  Lines containing no whitespace to the left of
               the specified column will not be wrapped.  If Mush was
               started with the -e (echo mode) option, or is in tool
               mode, line wrapping cannot be done due to I/O
               incompatibilities.

          In addition to the named variables described above, three
          special variable forms are recognized.

          $$   This string returns the process id (PID) of the current
               mush process.  Colon modifiers are not recognized for
               this special variable.

          $[%fmt]
               The string %fmt is interpreted as a header formatting
               string (as in the hdr_format variable) and is expanded
               using the headers from the current message.  Colon
               modifiers are allowed to follow the format.  For
               example,

                   save $[%4n]:l

               will save the current message in a file whose name is
               the first four characters of the name of the author,
               converted to lower case.

          $(%c)
               The string `%c' is interpreted as a prompt format (as
               in the prompt variable) and is expanded.  Colon



     Page 73                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



               modifiers are allowed.  For example,

                   echo $(%T)

               will print the current time.  Note that "$(%F)" is
               equivalent to "$thisfolder".

          NOTE:  Evaluation of many "$[%...]" or "$(%...)" values in a
          single command is inefficient.  If expansion of several
          formats is desired, it is better to use the -h and -p
          options of echo or eval, which also provide better quoting
          of the interpolated strings.

     MUSH SCRIPTS
          One of the most useful features of Mush is the ability to
          write scripts of commands, which can be read by the source
          command from within Mush, or by redirecting input from the
          script and using the -i option.  If your operating system
          supports the "#!" interpreter mechanism, a script can be
          even be executed as a program.  Script files can use all the
          usual Mush commands; the only restriction is that the `!'
          history notation for referencing arguments of cmd aliases is
          disabled in scripts, so only very simple cmds will work.

          For example, a filtering file, "filter", might contain:

            set newfolder = /usr/spool/mail/$USER
            if is_shell
                if -z $newfolder
                    set newfolder = $mbox   # mbox must be set!
                endif
                if -e $newfolder
                    folder $newfolder
                else
                    quit
                endif
            endif

            pick -f Mailer-Daemon | save mail_errors
            pick -f yukko | delete
            pick -s -i thesis | save +thesis_mail
            pick -t unix-wizards | +wizmail
            update
            sort d

          Then the first command the user types when beginning a Mush
          session might be "source filter", and the following would
          happen:

            First, a new variable called newfolder is set to the the
            user's spool mailbox (the system mailbox).  A test is made
            to see if the shell is running, because the folder command



     Page 74                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



            can only be used from the shell.  Then a test is done to
            see the spool mailbox is zero length, and if it is, the
            variable is reset to the value of the user's mbox variable
            (mbox must already be set by this time or this will fail).
            A final test assures that the new folder exists.  If it
            does, Mush changes folders to the new folder.  If it
            doesn't exist, the program exits (via quit).

            Once the correct folder has been loaded, all messages that
            have "Mailer-Daemon" in the From header will be saved in
            the file mail_errors.  Then, all mail from the user
            "yukko" will simply be deleted.  Next, all mail that has
            in the Subject field, "thesis" (case ignored, so "Thesis"
            would also match) will be saved in the file
            $folder/thesis.  The next command will find all messages
            that are addressed to the group "unix-wizards" (of which
            the user is an elite member) and save them in the file
            $folder/wizmail.  Last, the folder will be updated,
            removing all deleted mail (saved mail may be marked as
            deleted) and the folder is reread and sorted according to
            the date of the messages.

          If the "#!" mechanism is supported, the "filter" script can
          be made into a program by adding as the first line:

              #! /usr/local/bin/mush -F

          (The actual location of mush may vary from system to system;
          /usr/local/bin is used as an example.)  Then make the file
          executable:

              chmod +x filter

          Now, when the command "filter" is typed at the user's
          regular shell prompt, the mush program will be invoked by
          the operating system.  Mush will first read the commands
          from the "filter" file and perform them, exactly as
          described above, and then will continue into the usual
          interface.  If it would be preferable for mush to exit after
          reading the script, the first line can be changed to:

              #! /usr/local/bin/mush -F!

          The -F! option should also be used when running scripts in
          the background or in other circumstances where the standard
          input cannot be a terminal, and the only commands to be
          executed are those in the script itself.

          Note that any additional arguments passed to a "#!" script
          are interpreted by mush; they are not passed along in any
          way that makes them accessible to the script.  Thus,




     Page 75                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



              % filter -f mbox

          would apply the commands in the "filter" script to the
          "mbox" folder.

     MACROS
          Macros are available in several different modes in Mush.
          Curses mode macros are created by using the bind command
          with the special function macro (or by using bind-macro,
          which is synonymous).  These macros are effective only when
          the curses interface is active.  Line mode macros are
          created with the map command, and are effective only in the
          line-oriented command interface.  Finally, composition mode
          macros are created with the map! command, and are effective
          only when composing mail messages.  Macros are not available
          in the tool mode, nor when composing messages from the tool
          mode.  Line and composition mode macros are also
          nonfunctional when Mush is started with the -e (echo)
          option.

          In general, macros consist of two parts:  a key sequence and
          an expansion.  The key sequence is the character or string
          of characters which, when typed in the appropriate mode, is
          recognized by Mush as a reference to a macro.  The expansion
          part of a macro is the string that will actually be "seen"
          by Mush when the key sequence is recognized.  Macros are
          like an interactive search-and-replace function; if a key
          sequence appears in the input, the associated expansion is
          substituted in its place.  Thus, if you create a macro whose
          key sequence is "^X^W" (control-X control-W) and whose
          expansion is "save", then when you hold down the control key
          and type the two characters `x' and `w', the effect will be
          as if you had actually typed the four characters `s', `a',
          `v' and `e'.  This is called "expanding" the macro.  More
          detailed examples of macros will be presented in the
          subsections for each mode in which macros can be used.

          Key sequences are usually made up of control characters or
          special strings of characters generated by "function keys,"
          but may in fact be almost any string the user desires.  Keys
          that generate a signal or an end-of-file from the keyboard
          (for example, on BSD systems, control-Z generates a TSTP
          signal and control-D generates an end-of-file) can never
          appear in key sequences, and macros in line or composition
          modes cannot begin with a newline, control-D, or any of the
          editing keys (erase, word-erase, line-erase, etc.).
          Otherwise, there are no restrictions.  It should be kept in
          mind, however, that for the line and composition modes, key
          sequences should be unusual characters or combinations of
          characters, not individual lower-case letters.  If common
          characters or strings are used for key sequences, much
          confusion can result when typing commands or messages.  This



     Page 76                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          is not important in the curses mode.

          In the line and composition modes, a timeout is used for key
          recognition; that is, once the first character of the key
          sequence has been typed, the succeeding characters must be
          typed after it relatively quickly, or Mush will fail to
          recognize them as a continuous sequence.  It is for this
          reason that key sequences are usually either very short, or
          are strings that are automatically generated by pressing a
          special key on the terminal.  On the other hand, the timeout
          can be used intentionally to prevent a macro from being
          expanded; simply type the first character of the macro, then
          wait for it to echo before typing the next.  This does not
          work in curses mode, because curses macros never "time out."

          In any mode, macros are recursive; that is, if the key
          sequence of one macro appears in the expansion of another
          macro (or even of the same macro), the second key sequence
          will be recognized when the first macro is expanded, and
          this new key sequence will also be expanded.  Great care
          should be taken when creating macros to be certain that
          recursive expansions do not happen unintentionally.
          Expansion can be prevented in line or composition modes by
          using a literal-next character.

          Literal-next characters may be used from the keyboard or
          embedded in expansions.  In either case, they prevent the
          next character from being interpreted as part of a key
          sequence.  Mush recognizes the literal-next character from
          the tty settings of the terminal, if the "new" BSD-style
          device driver is available; otherwise, `^V' (control-V) is
          recognized as a literal-next.  Note that, if you have a tty
          literal-next character, then when typing you will need to
          type two of them in order to send one to Mush; this is
          because the tty driver consumes the first one.  It is not
          necessary to use two literal-nexts in macro expansions
          unless you wish to cause the second literal-next to be
          literal.

          Backslash can be used as a literal-next when typing, and can
          sometimes be used as a literal-next in expansions; but use
          it with caution, because it also introduces escape sequences
          (see "Macro syntax," below).  There is no literal-next
          mechanism for curses mode.

          A macro will always abort whenever any command called by the
          macro returns an error.  This includes recursive expansions,
          so no matter how often a macro has recurred, it will be
          terminated completely.  Errors in curses mode include
          illegal cursor movements, such as up from the top of the
          screen or down from the last message.




     Page 77                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          Macro syntax.

          A special syntax is provided for specifying control
          characters and other non-printing characters in macro key
          sequences and expansions.  This syntax is the same as that
          for bindings, discussed in the CURSES INTERFACE section; it
          can be summarized as:
            \CX    control-X (where X is any capital letter)
            \E     the escape character
            \n     a newline (other C-style escapes also work)

          Thus, to create a line mode macro for control-X control-W,
          as in the example above, the command would be

              map '\CX\CW' save

          Also provided is a syntax for executing functions from
          within macros.  There are two special functions that are
          effective in all modes; these are getstr and getline.  Both
          of these functions interrupt expansion of the current macro,
          and wait for a newline-terminated string to be entered from
          the standard input.  This input string is inserted into the
          macro expansion.  The functions differ in that getline
          retains the newline character (carriage-return) at the end
          of the input string, whereas getstr strips off the newline
          (one must still be typed to terminate input).  These
          functions can be executed by surrounding their name with
          square brackets ([, ]); for example,

              map '\CX\CW' save [getline]

          creates a line mode macro, which is expanded when control-X
          control-W is typed, and which displays "save" followed by a
          space and then waits for the user to type a line of input;
          the input line will be used as the arguments to the save
          command.

          Additional functions are currently available only in the
          curses mode.  However, the syntax of enclosing the function
          name in square brackets applies to all functions, regardless
          of mode.  Note that ONLY the function name can appear in the
          brackets; no whitespace is allowed.

          Curses mode macros.

          Macros in curses mode are the most versatile, because they
          can access the full range of curses commands quickly and
          easily.  Every character that appears in the expansion part
          of a curses mode macro can reference a curses command or
          another macro.  Like other curses functions, curses mode
          macros are created with the bind command.  For example, to
          sort your messages by date and then send the most recent one



     Page 78                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          to the printer, you could use

              bind @ macro 'od$|'

          When the `@' key is typed, this macro first invokes sort
          (`o' from the default bindings) and instructs it to use date
          (d) for sorting; it then moves the current-message pointer
          to the last message ($) and prints that message (|).

          Admittedly, the above macro is somewhat cryptic, and is
          dependent upon the bindings for sort, last-msg, and lpr
          being set to the defaults.  It would be better, and possibly
          more understandable, to refer to the desired curses
          functions without using their key bindings.  To allow this,
          the "[function]" syntax described above may be used in
          curses mode macros to reference curses functions.  The only
          function that is prohibited from appearing in the "[]" is
          the special macro function, which cannot be called when it
          has no binding.  The example macro can therefore be
          rewritten as

              bind @ macro [sort]d[last-msg][lpr]

          Such references to curses functions may be made only in
          curses mode macros, and are effective only when Mush is
          actually in curses mode.  That may sound strange, but the
          most common use of curses macros is to quickly perform
          functions that require an escape to the line mode.  For
          example, although there is a variation of the curses mode
          mail function that will prompt for additional flags, there
          is no function to prompt for flags to be passed to reply.  A
          macro can easily be created to provide this:

              bind R macro '[line-mode]reply '

          This macro binds `R' to perform an escape to line mode and
          type the string "reply" followed by a space.  Macro
          expansion then ends, leaving it up to the user to supply
          flags to the command or to backspace over it if a different
          command (or none) is desired.  Of course, the macro could
          also have provided some default arguments:

              bind R macro '[line-mode]reply -ei '

          Note that, if the getline or getstr function is used in a
          line-mode escape, it is not possible to erase the text that
          is typed before the get; that is, if the macro had been

              bind R macro '[line-mode]reply -ei [getline]'

          then the user would be forced to use the -ei flags.




     Page 79                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          Line mode macros.

          Line mode macros combine some of the convenience of single-
          keystroke commands with the versatility of the line-oriented
          text interface.  As has been noted, the choice of characters
          for line mode key sequences should be made carefully, so as
          not to interfere with normal typing.  Line mode macros are
          created with the map command; for example, suppose you
          frequently forward messages to a friend named "fred."  You
          could create a macro to do this:

              map '\CF' 'mail -f . fred\n'

          This macro causes the single keystroke `^F' (control-F) to
          forward the current message to "fred."  Note the newline
          character "\n" at the end of the expansion; this causes the
          command to be executed immediately, without you having to
          type a carriage-return.

          The expansion part of a line mode macro will echo to the
          screen when it is expanded, so you can see what the macro is
          doing.  You can therefore use parts of the expansion as a
          "prompt."  In the above example, suppose you wished to enter
          a message list rather than always forwarding the current
          message.  Change the macro to:

              map '\CF' 'mail -f [getstr] fred\n'

          This version of the macro prints "mail -f" and a space, then
          waits for a newline-terminated string from the standard
          input.  The newline is stripped, and the string is used as
          the message list passed to the "mail -f" command.  The
          address "fred" is also passed to mail, so the messages in
          the list are forwarded to fred.

          If you want to be able to "change your mind" after starting
          a line mode macro, you must leave the "\n" out of the
          expansion.  Without the newline, the macro will not be
          executed immediately, so you have a chance erase the line
          (or part of it) and type something different.  Remember that
          the getline function keeps the newline in the string it
          gets, so if you don't want a newline to appear, you must use
          getstr.  When using the get functions, you should also
          remember that you can never backspace past the "beginning"
          of a getline, and you can backspace past the beginning of a
          getstr only after the get has been completed.

          When the getstr function is used in line mode macros, Mush
          will reprint the current input line so you can see what the
          whole thing looks like, but will not redisplay the line mode
          prompt (see the entry for prompt in the VARIABLES section
          for information on what the prompt looks like).  Don't let



     Page 80                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          this worry you.  The input line is also reprinted when
          getline is used, but the newline in the input string usually
          results in a new prompt being displayed.

          NOTE:  Line mode macros are not available when using the
          line-mode escape function in curses mode.  It is necessary
          to escape all the way to line mode (that is, leave curses
          mode by typing carriage-return at the `:' prompt) in order
          to access line mode macros.  This is to prevent possible
          confusion when similar macros exist in both line and curses
          modes.

          Composition mode macros.

          Composition mode macros are very similar to line mode
          macros, and provide a "power typing" function when composing
          messages.  For example, you might want to have the word
          "percent" inserted into your message whenever you hit the
          `%' key:

              map! % percent

          Another use is to simulate the indentation features of
          editors.  For example, you might

              map! '\CT' '    '

          (where the expansion is four spaces, enclosed in single
          quotes).  This macro causes four spaces to be inserted into
          the message whenever control-T is typed.

          Composition mode macros can also be used to execute tilde-
          escapes (see the GENERAL USAGE section for a list of these).
          For example, you could create a macro to invoke the editor:

              map! '\CE' '\n~v\n'

          When control-E is typed, this macro prints a newline (to be
          sure that the tilde-escape is the first thing on a line),
          then types "~v" followed by another newline, to start the
          editor.  Similar macros can be created for other tilde-
          escapes.

          Mixed mode macros.

          It is not normally possible to mix macros among the
          different modes.  However, once expansion has begun, it is
          interrupted only by an error or by the appearance of one of
          the special get functions.  It is therefore possible to have
          a macro expansion which causes the mode to change before the
          expansion has completed.  In this case, recursive expansions
          will apply to the new mode.  Suppose we are using a



     Page 81                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          variation of the editor-starting macro shown above for
          composition mode:

              map! '\CE' '\n~v emacs\n'

          This macro causes the "emacs" editor to be started when
          control-E is typed in composition mode.  We can now create a
          line mode macro that makes use of this composition mode
          macro:

              map '#' 'reply -i [getline]~t[getline]\CE'

          When the `#' key is pressed in line mode, this macro will
          print "reply -i" and wait for a message list, then enter
          composition mode (by executing the reply command).  In
          composition mode, it will display the To: line (the "~t"
          escape) and wait for other addresses to be added.  Finally,
          it will recursively expand the control-E macro, to start
          editing the message with emacs.

          As can be seen from this example, the Mush macro facility is
          very powerful.  Be very careful not to accidentally expand
          recursive macros, especially when using macros that change
          modes.  When testing new macros, it is a good idea to start
          Mush in read-only mode (the -r command line flag) to be sure
          that messages are not lost or altered.

          Getting rid of macros.

          It is not necessary to delete a macro in order to redefine
          it.  New expansions for existing key sequences will
          automatically replace the old expansions.  If it is
          necessary to remove a macro completely, the commands unbind,
          unmap and unmap! can be used to remove curses mode, line
          mode, and composition mode macros, respectively.  Remember
          to use a backslash or other literal-next character to
          prevent the expansion of line mode macros when using these
          commands, especially unmap.

     MAIL ADDRESSES
          Whenever a command that requires a user address or set of
          addresses is specified (mail, reply, alias, etc) the
          addresses given must be separated by commas.  Most casual
          users specify addresses that contain no comments or
          whitespace.  The simplest addresses are just the login names
          of the users you wish to send your message to:

            mail fred barney wilma betty

          In these cases, Mush can figure out that they are separate
          addresses and insert commas between addresses automatically.




     Page 82                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



            To: fred, barney, wilma, betty

          Addresses may also contain `!', `@' and `%' characters which
          are used to separate hostnames and the final user name from
          each other.  This is primarily used to mail to users on
          other machines.  UUCP addresses are specified as

            host1!host2!user

          where there may be as many hosts as necessary to route the
          message to the recipient user.  Here, the user's account is
          on "host2" and that machine is connected to "host1".  Domain
          addresses (also called Arpanet, Internet, RFC822, and "fully
          qualified" addresses) are specified as

            [e-mail]
            user%host2.domain@host1

          where "domain" is a domain name such as ".berkeley.edu" or
          ".com".  As in the first example, the user is on "host2",
          but that machine talks to "host1".  It is beyond the scope
          of this document to discuss in detail the ramifications of
          inter-network mailing.  More information can be obtained
          through your system manager.

          Mush understands addresses containing a comment field.
          Comment fields do not affect the destination address of mail
          being sent.  These fields are purely for human legibility
          and may be specified according to the following constraints:

          Anything within angle brackets is an address; whatever is
          outside of the address is considered a comment:

            Dan Heller <zipcode![e-mail]>
            Dan Heller <[e-mail]>

          Anything that has parentheses is a comment; whatever is
          outside of the parentheses is considered the address:

            zipcode!argv (Dan Heller)
            [e-mail] (Dan Heller)

          Double quotes (") are treated just like parentheses:

            "Dan Heller" zipcode!argv
            "Dan Heller" [e-mail]

          If the comment is to contain a comma, the first case above
          may not be used; you must use either the parenthesis or
          double-quote cases.

            [e-mail] (Fred Flintstone, Cave Man)



     Page 83                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          If the comment contains unbalanced quotes, unpredictable
          results may occur (Mush won't deliver the mail).

          Since the angle brackets have the highest precedence, quotes
          or parentheses may be used in conjunction with one another.

            Yabba Dabba Doo (Fred Flintstone) <fred>
            Scoobie "Doobie" Doo <[e-mail]>

          Multiple addresses may appear on a line:

            [e-mail] [e-mail] dheller

          Because there is no indication of comments (parenthesis,
          angle bracket, or quotes), it is assumed that these are
          separate addresses and Mush will insert commas between these
          addresses accordingly.  It is for this reason that the user
          is encouraged to explicitly insert commas between all mail
          addresses and not depend on the automation of comma
          insertion to correctly separate addresses from one another.

          Mail aliases may contain addresses of the form described
          above.

            alias george    George Jetson <[e-mail]>
            alias jane      Jane Jetson <[e-mail]>
            alias group     george, jane

          You can mail using the alias as an address and it will be
          expanded accordingly.  You cannot, however, reference an
          alias and specify a comment or another address at the same
          time.

            To: The Jetsons <group>

          The alias "group" will not be expanded because the angle
          brackets causes it to be considered as another address
          entirely.

     FILES
          /usr/spool/mail/*       Directory for incoming mail
          ~/Mail  Default folder directory
          ~/mbox  File where old mail is saved
          ~/.mushrc       File giving initial Mush commands
          ~/.mailrc       Alternate initialization file
          ~/.edXXXXXXX    Temporary for file for outgoing messages
          ~/.mushXXXXXX   Temporary mail file (copy of current folder)

          Temporary files that are created by the program are always
          created with read/write access to the owner only; group and
          other permissions are never set.  This is also true for the
          /usr/spool/mail/* files.  All other files created by the



     Page 84                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          user via commands internal or external to the program have
          permissions set by the user's default umask.  If the umask
          is reset within the program, the mask remains intact even
          after exiting.  Remember to set the variable unix before
          attempting to set the umask value.

          If your system is using Sun Microsystem's NFS, take special
          note to read the manual page for mount(C).  Filesystems
          mounted for read/write access should be mounted as "hard"
          NFS mounts or you may lose mailboxes during a timeout during
          a write or update.

          Filesystems that use RFS still have bugs to be ironed out in
          the way of owners and permissions concerning utime(2).

     SEE ALSO
          Mail(C), binmail(C), csh(C), aliases(5), mount(C),
          mailaddr(F), sendmail(?), printf(S), execl(S), umask(C),
          utime(S).

     AUTHOR
          The original Mush was written entirely by Dan Heller.  Code
          to support macros, line wrapping, and a whole lot of other
          miscellaneous details, was written by Bart Schaefer, who
          gets his name in print because he updated and proofread this
          manual.  Numerous others have supplied valuable suggestions
          and assorted bits and pieces.

          [e-mail]       zipcode!argv

          Installation on this system, plus Dos(TM) and OS/2(TM) port,
          by Mike O'Carroll <[e-mail]>

     DISCLAIMERS
          Mush contains no UNIX(TM) sources and never has.  It is also
          not a modified version of any other mail user agent.
          Similarities with any other mailer may have been designed
          for compatibility reasons.

          UNIX is a trademark of AT&T.

          The Flintstones and The Jetsons are trademarks of Hannah-
          Barbara Inc.

     BUGS
          The curses interface uses the curses library.  The routines
          from the library that are used are the most basic and simple
          so as to avoid possible bugginess that different versions of
          UNIX might have.  However, one unavoidable problem is the
          reverse video mode.  Depending on your terminal, the termcap
          entry for it, and the version of curses you are running, the
          reverse video may make things worse than desired.  In such



     Page 85                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          situations, the user should set the variable no_reverse to
          not get reverse video.  `^R' may still be entered at runtime
          in the curses interface to toggle reverse video.

          Toggling from the curses mode to the line mode to get the
          full functionality of the shell/line mode is unfortunately
          necessary in order to maintain the display in a sensible
          manner and to keep the keystroke-command interface simple
          and "user friendly".  Mostly, such escapes are only
          necessary for piping of commands and using the pick command.
          Macros are a big help with this.

          If the program is already running and the system [later] has
          to swap and there is no swap space left, there may be
          problems.  One such problem is sending mail.  If this
          happens, then sending mail will fail and a segmentation
          fault from the spawned/forked child may occur (unless the -v
          flag was given to mail).  The unsent letter will not be
          removed from the editing file ($home/.edXXXXXX) and may be
          recovered.

          Many functions available to the line oriented mode (shell
          mode) are not available to the tool mode.  For example, pick
          may not be directly accessed although experienced users may
          find that typing pick commands within single backquotes in
          the "Range:" panel item above the header window and then
          selecting a command that uses the the range will indeed pick
          messages.  This is mostly for selecting the "delete range"
          item or the middle mouse button icon in the header panel.

          Version 6.5.6 was the last version designed to run under
          SunWindows, and is therefore the most recent version that
          will function under SunOS 2.x.  The current version, 7.0,
          has been ported to SunView, and may have a completely new
          set of problems in addition to those described below.  Also,
          some of those described below may have been eliminated, and
          remain in this discussion only for completeness.

          Shell escapes (of any kind) may be called only from the
          "pipe" command in the tool mode, should not be interactive,
          and should produce output only to a file.  The reason for
          this is that there is no tty window in which to do
          input/output.  Since the interactive function-key binding
          interface has gone away, it is unfortunately only possible
          to execute commands that have been pre-defined in the
          initialization file.  Future revisions may correct these
          deficiencies.

          The function keys and their ability to work has been
          variable depending on the version of SunWindows/SunView your
          Sun Workstation has.  From time to time, it works, but when
          it doesn't, it seems to be related to other user or system



     Page 86                                        (printed 12/21/90)






     MUSH(C)           Version 7.1.0 (Apr 25, 1990)            MUSH(C)



          definable dot-files or whatever.  This of course means that
          the function keys are relatively untested in conjunction
          with SunView (SunOS later than 3.3).  The default function
          key bindings have been eliminated to avoid collisions with
          SunView window system functions.

          Changing the value of the screen_win, crt_win, or msg_win
          variables after the tool is running simply has no effect.

          When using vi in the tool mode, the window is periodically
          one line "short." That is, scrolling is off by one line and
          you have to redraw the window (using "z." in vi) to get it
          in sync again.  This problem remains in most SunView
          implementations, but does not seem to appear with the
          current default composition window size.

          When running on full filesystems, Mush may complain or not
          even run since it needs temporary space with which to work.
          Instead of finding new filesystems on its own, Mush leaves
          this task up to the user.  The workaround is to set the
          variable tmpdir in the initialization file to be a writable
          place in a filesystem that has enough disk space.

          Most of the other known and documented bugs are in the
          supplied README files accompanying the source.  The source
          is also an excellent place to look as many known bugs are
          documented in comments.  A good way to track suspicious bugs
          is to use the debug command, but note that this command is
          very difficult to use in curses mode.


























     Page 87                                        (printed 12/21/90)