rsalz@uunet.UU.NET (Rich Salz) (09/19/87)
Submitted-by: island!argv@Sun.COM (Dan Heller)
Posting-number: Volume 11, Issue 53
Archive-name: mush5.6/Part03
[ This is the first half of the manpage; do "cat mush.1.[ab] >mush.1"
to get the full document. --r$ ]
#! /bin/sh
# This is a shell archive. Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file". To overwrite existing
# files, type "sh file -c". You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g.. If this archive is complete, you
# will see the following message at the end:
# "End of archive 03 (of 12)."
# Contents: mush.1.a
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'mush.1.a' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'mush.1.a'\"
else
echo shar: Extracting \"'mush.1.a'\" \(41182 characters\)
sed "s/^X//" >'mush.1.a' <<'END_OF_FILE'
X.\" Mush Man Page: Copyright (c) 1987 Dan Heller
X.\"
X.TH MUSH 1 "Mar 3, 1987"
X.UC 4
X.SH NAME
XThe Mail User's Shell \- Shell for electronic mail.
X.SH SYNOPSIS
X.B mush
X[
X.B \-S
X]
X[
X.B \-C
X]
X[
X.B \-f
X[
Xfolder
X]
X]
X[
X.B \-n
X]
X[
X.B \-T
Xtimeout
X]
X[
X.B \-t
X]
X[
X.B \-i
X]
X[
X.B \-N
X]
X[
X.B \-H[:c]
X]
X[
X.B \-r
X]
X[
X.B \-v
X]
X[
X.B \-s
Xsubject
X]
X[
X.B \-c
Xcc-list
X]
X[
X.B \-1
Xcmd_help
X]
X[
X.B \-2
Xtool_help
X]
X[
X.B \-d
X]
X[
Xuser list ...
X]
X.SH INTRODUCTION
XThe Mail User's Shell (Mush) is an interface for sending and manipulating
Xa database of electronic mail messages under the
X.I UNIX
Xenvironment. There are three user interfaces which allow the user to
Xinteract with
X.I Mush.
XThe
X.I window
Xinterface for the Sun Workstation utilizes the icon and
Xmenu based (mouse selectable) windowing system. This
X.I tool
X(graphics), mode is highly subject to the version of operating system
Xyour Sun may be running. While the program works with variable levels
Xof success on earlier versions, it is intended to be run on Sun versions
X2.0 and higher. See the BUGS section at the end for more information.
X.PP
XThe text-graphics interface is reminiscent of the
X.I vi
Xvisual editor. This interface does not require graphics capabilities of
Xthe computer or the terminal on which it is run, but the terminal must
Xhave the minimum capabilities required by any visual screen editor.
X.PP
XThe default interface is the conventional tty-based line mode
Xsimilar to command line interpreters such as
X.I csh
Xas well as other mailers, such as University of California, Berkeley's,
X.I Mail
Xand Bell Lab's System V
X.I mailx
Xinterface. This mode requires nothing from the terminal in cursor
Xoptimization and may be run on many different version of
X.I UNIX
Xrunning on various architectures such as VAX and MicroVax (4.2, 4.3 BSD),
XIBM-PC AT's running system V (XENIX), IBM-RT's, and pyramids.
X.PP
XSee the correpsonding subheadings for more information on the user
Xinterface desired. Most of this manual deals with commands, variables
Xand actions which are usually common to all three interfaces although
Xsome attention is paid to individual characteristics of each interface.
X.PP
XThe following command line arguments are understood by
X.I Mush:
X.TP
X\-S
XThis flag allows the user to enter the shell even if the system
Xmailbox, or specified folder is empty or doesn't exist.
X.TP
X\-C
XEnter the mailer in curses mode upon startup.
X.TP
X\-f [ filename ]
XThe optional filename argument specifies a folder containing mail messages.
XWith no argument,
X.B mbox
Xin the current directory (or the variable `mbox')
Xis used.
X.TP
X\-n
XNo initialization is done on start up. That is, do not source
X.I .mushrc
Xor
X.I .mailrc
Xfiles.
XSee the subheading INITIALIZATION for more inforation on start and these files.
X.TP
X\-T timeout
X(Sun only) In the tool mode,
X.I timeout
Xspecifies the length of time (seconds) to wait between each check for new mail.
X30 seconds is the smallest time allowed for performance reasons. 60 seconds
Xis the default value.
X.TP
X\-t
XUse the graphics tool mode (Sun only).
X.TP
X\-i
XForces interactive mode even if input has been redirected to the program.
XThis is intended for remote host mail sessions but also allows
Xthe user to redirect "scripts" of
X.I Mush
Xcommands. See the INITIALIZATION subheading for information on how to
Xwrite scripts which deal with mail.
X.TP
X\-N
XEnter
X.I Mush
Xwithout displaying any message headers. This argument is passed to the
X.B folder
Xcommand.
X.TP
X\-H[:c]
XHave
X.I Mush
Xjust display mail headers without entering the shell.
XSee the
X.B headers
Xcommand for information on the
X.B :c
Xargument. No colon modifier is equivalent to
X.B "-H:a.\ "
XThis option prevents the shell from running, so this option will turn off the
Xflags, -S and -C. This option is ignored if the tool mode is in effect.
X.TP
X\-r
XInitialize the folder in Read-Only mode; no modification of the folder is
Xpermitted. This argument is passed on to the
X.B folder
Xcommand.
X.TP
X\-v
XVerbose mode is turned on. This option is passed to the actual mail delivery
Xsubsystem internal to your version of
X.I UNIX.
XSome mailers do not have a verbose option, so this flag may not apply
Xto your system (System V, for example).
XThis applies when sending mail only. If you are entering the shell,
Xcurses mode, or the tool mode, this option is ignored.
X.TP
X\-s subject
XThe subject is set on the command line using this flag. If the subject has
Xany spaces or tabs, the entire subject should be encased in quotes.
XThis applies when sending mail only. If you are entering the shell,
Xcurses mode, or the tool mode, this option is ignored.
X.TP
X\-c cc-list
Xhe list of Carbon Copy recipients is set on the command line. If more than
Xone address is specified, the entire list should be encased in quotes.
XThis applies when sending mail only. If you are entering the shell,
Xcurses mode, or the tool mode, this option is ignored.
X.TP
X\-1 cmd_help
X.TP
X\-2 tool_help
XSpecify alternate locations of help files. These should be full pathnames
Xaccessible for reading. This is usually done if a binary copy of
X.I Mush
Xhas been copied from another machine and the wrong pathnames to the
Xhelp files cannot be changed.
X.TP
X\-d
XTurns on the debugging level to 1. You can change debugging levels from
Xwithin the shell using the
X.B debug
Xcommand.
X.SH FEATURES
X.PP
XThe following features are common to all user interfaces that
X.I Mush
Xprovides. Interface-specific features are listed separately
Xunder the subheading for that interface. Commands and user definable
Xvariables are described under the appropriate subheadings.
X.PP
X.B New Mail.
X.PP
XIf during a
X.I Mush
Xsession, new mail arrives for you, it is automatically incorporated into
Xyour system mailbox and you are told that new mail has arrived.
X.PP
XIn the default line mode, new mail is checked between each command
Xissued. In the tool based graphics mode, new mail is checked approximately
Xevery minute or by the number of seconds specified by the
X.B -T
Xoption on the command line. In the curses mode, new mail is checked on each
Xcommand and is displayed in the bottom line of the screen.
X.PP
XIf you are using your system mailbox as your "current folder," then the
Xnew mail is added immediately to your current
Xlist of messages and this information is displayed telling you whom the mail
Xis from:
X.sp
X.ti +5
XNew mail: (#15) island!argv@Sun.Com
X.sp
XIf you are not in your system mailbox, then the new mail will not be added
Xto your list of messages, but you will instead be informed of the new arrival.
X.sp
XIf you are using the tool based mode and
X.I Mush
Xis closed to an iconic state, then the number of messages in the current
Xfolder is displayed on the mailbox icon and the flag on the mailbox will go up.
X.sp
X.PP
X.B Aliases.
X.PP
XMail aliases are shorthand names for long mail addresses. These are
Xsupported in the same manner as UCB Mail supports them. Because
X.I Mush
Xhas command line history reminiscent of
X.I csh,
Xcommands which use uucp's `!' character for user-host and host-host
Xseparation should be escaped (preceded by a backslash). This is not
Xnecessary in the initialization file (.mushrc) because history
Xreferencing is ignored while these files are being sourced. See the
Xsubheading, INITIALIZATION and the line-mode interface for more information
Xon initialization file format and the history mechanism.
X.sp
XAliases reference normal mailing addresses as well as other aliases. If a loop
Xis detected, then the user will be notified and a dead.letter will be
Xforced into the file
X.B dead.letter
Xin the user's home directory. The command,
X.B unalias,
Xis used to reverse the effects of the
X.B alias
Xcommand.
X.sp
X.PP
X.B Help.
X.PP
X.I Mush
Xwas designed so that each command or action should not be a mystery.
XHelping the user understand what to do and how to do whatever he wishes
Xis the goal behind the help facility. For this reason, the command,
X.B help
Xgives information on both general usage and specific help categories.
X.PP
XIn text mode, most help is gotten by typing `-?' as an argument to a
Xcommand. Virtually all commands have the -? option. When this option
Xis specified, most commands will attempt to read from a help file the
Xnecessary information explaining the functionality of the command in
Xexecuted. If necessary, a pointer to other sources of information will
Xbe given to fully explain a concept.
X.PP
XIn the tool/graphics mode, this is
Xalso possible, but more extensive help is provided in the pop-up menus.
XPop-up menus can be gotten from virtually anywhere on the screen; press the
XRIGHT mouse button (the "menu button") and a number of items will appear
Xin a menu. The last command in the menu list will be one labelled "help."
XSelecting this menu item will display a "help box" in the center of the
Xconsole and wait for input to remove the box.
X.PP
XIn the curses mode, the `?' key will display a list of the current
Xcommand-to-key bindings; a keystroke or set of keystrokes correspond
Xdirectly to a command.
X.PP
X.B Sorting mail.
X.PP
X.I Mush
Xallows you to sort your mail according to various constraints such
Xas time, status (new, unread, deleted, etc), by author and subject.
XSee the
X.B sort
Xcommand in the subheading COMMANDS for more information on sorting.
X.PP
X.B Picking specific messages.
X.PP
XYou can select messages that contain unique information, or from
Xmessages that have special attributes. You have the option of
Xrestricting your search to messages between dates, message numbers,
Xauthor names and other constraints.
X.sp
X.SH INITIALIZATION
X.PP
XUpon startup, before any command line arguments are parsed, and before
Xthe current folder's messages are read (thus, there are no messages to
Xspeak of, yet),
X.I Mush
Xwill initialize itself with basic variable settings and values.
XIf the -n option is given, initialization is
X.B not
Xdone. If no -n option is given, it will source an
X.B initializing file
Xwhich contains commands that [typically] set variable values, aliases,
Xcommand line aliases, and so forth. The file it reads from is determined
Xby first looking for the environment variable,
X.I MAILRC.
XIf that file isn't found, then the file
X.I .mushrc
Xis search from the home directory of the user. If that file cannot be found,
Xit will attempt to read the file,
X.I .mailrc
Xfrom the same directory. If that file isn't found, then the default
Xinitialization file setup by the administrator is attempted.
XFinally, if that file cannot be read, then nothing is done about initialization
Xand the default values will be in effect.
X.sp
XIf the user has no home directory, or permissions prevent read/write access
Xto $HOME, /tmp is used as the home directory. See the
X.B home
Xvariable under the VARIABLES heading.
X.sp
XYou may specify a filename to source if you want to source a specific file
Xother than the default. You may use the command
X.B saveopts
Xto save all variable settings, aliases, and all other
X.I Mush
Xsettable attributes. If no filename is given on the command line,
X.B saveopts
Xchooses a file in the same manner that
X.B source
Xdoes. Using saveopts is highly discouraged since it overwrites files
Xwithout warning and saves settable variables only. ``if'' expressions
Xare not saved and session-dependent settings may be invalid upon next
Xinvocation.
X.PP
X.I "Initialization File Format.\ "
XWhen reading the initialization file,
X.I Mush
Xwill recognize the `#' character as a comment character. It may
Xbe anywhere on a line in the file. When that character is encountered,
Xprocessing of that line is discontinued to the end of the line.
XIf the `#' is encased in quotes (single or double), then it is not
Xconsidered a comment.
X.sp
X.ti +2
Xset shell = /bin/csh # set the shell variable
X.ti +2
X# this entire line has been commented out.
X.in +2
Xset prompt = "Message #%m: " # The `#' is within quotes
X.sp
X.PP
XThe
X.B exit
Xcommand has special meaning in the initialization file. If the command
Xis found,
X.I Mush
Xwill not exit, but rather, discontinue reading from the file immediately.
X.PP
XThere may be ``if'' expressions within the initialization file to determine
Xcertain runtime states of
X.I Mush.
XThere are no parentheses allowed and only one boolean expression may be
Xevaluated per line; that is, no ``&&'' or ``||'' may be used in expressions.
XThere is currently no support for multiple levels of if-else expressions
Xand embedded ``if'' expressions are ignored (they are evaluated to TRUE).
XThere must always be an ``endif'' accompanying all ``if'' expressions.
XThe statements associated with an ``if'' expression are never on the same
Xline with the conditional.
X.PP
XUnderstood conditional expressions include the internal variables,
X.I istool, iscurses, hdrs_only,
Xand
X.I redirect.
XIf
X.I istool
Xis true, the program is going to start in the tool mode. If
X.I iscurses
Xis true, the program is in or is going to start in the curses mode even
Xthough the screen package may not have already been started. If
X.I hdrs_only
Xis true, then the -H flag on the command line has been given. If
X.I redirect
Xis true, then input to the program is redirected. The
X.B -i
Xoption on the command line is required to run the shell if redirect is on.
XIf the flag is specified, the value for
X.I redirect
Xwill be set to false.
XThese are internal variables whose values can not be referenced using the
X``$variable'' method of variable expansion.
X.PP
XThe `!' operator may be used to negate expressions, thus,
X.sp
X.in +2
X.nf
Xif !istool
X exit
Xelse
X set autoprint
Xendif
X.in -2
X.fi
X.sp
Xmeans that if you are not running as a tool, stop reading commands from this
Xfile. Otherwise, set the autoprint variable. The test for redirection may
Xbe done to determine whether or not input, not output, has been redirected
Xto the program.
X.sp
X.in +2
X.nf
Xset hdr_format = "%S %25f %7d (%l/%c) %25s"
Xif (hdrs_only)
X exit
Xendif
X.in -2
X.fi
X.sp
XThis tells the program to set the hdr_format variable and check to see if
Xwe're running the program to read headers only. If so, stop reading this
Xfile (exit) and continue on with the program. This speeds up runtime quite
Xa bit for those who have lengthy initialization files because no other shell
Xvariables are necessary.
X.sp
X.in +2
X.nf
Xif !iscurses
X set crt = 24 screen = 18
Xendif
X.in -2
X.fi
X.sp
XThis segment checks to see if we're not running in curses mode and if not
Xit will set our crt and screen sizes. This is mostly because the curses
Xmode will set those values for us by looking at the size of our screen
Xfor us. The
X.B curses
Xcommand itself should never be called from an initialization file. Doing
Xso will cause terminal settings to be set incorrectly and unpredictable
Xresults from there. In fact, no interactive commands should be called
Xfrom any initialization file. These commands are not prevented because
Xit is impossible to trace which commands are aliased to interactive commands
Xand which might even be shell commands that are interactive. The
Xresponsibility of not running interactive commands is left to the user.
XSee the section on curses under THE CURSES INTERFACE for configuring your
Xenvironment so you enter the curses interface each time you runs the shell.
X.PP
XWhen initialization files are being read, no history expansion is done,
Xso the `!' need not be escaped for address aliasing.
XString evaluation is allowed and the operators, "==" and "!=" may be
Xused to determine their equality. Usually, variables are compared with
Xconstants for evaluation.
X.sp
X.in +2
X.nf
Xif $TERM == adm3a
X set pager = /usr/ucb/more
Xelse
X set pager = /usr/local/less
Xendif
X.in -2
X.fi
X.sp
XThis segment tests to see if the user's terminal type is "adm3a". If it is,
Xthen it sets the pager variable to be the "more" program. Note that the
Xvariable TERM will be gotten from the user's environment if a shell variable
Xis not set already. Otherwise, the pager variable is set to "less". This
Xexample exemplifies the fact that "less" normally fails to function correctly
Xfor the terminal type ``adm3a'' so we don't use it.
X.PP
XAfter sourcing the initialization file,
X.I Mush
Xreads all the mail out of the specified folder (the system spool directory
Xif no folder is given) and creates a list of messages. The current maximum
Xnumber of messages the user can load is set to 1000 by default. The system
Xadministrator who configures the program can reset this value higher or lower
Xif you ask nicely. If the user has the
X.B sort
Xvariable set, then when the current folder's messages are finally read,
Xthe messages are sorted according to the value of the
Xvariable (see the sort entry under the VARIABLES heading for more information).
XEach message has a number of message headers which contain information
Xabout whom the mail is from, the subject of the message, the date it was
Xreceived, and other information about the letter. This information is then
Xcompiled into a one line summary and is printed out sequentially in the
Xappropriate manner depending on the interface you're using.
X.PP
XAt this point, commands may be input by the user. The initialization file
Xis read
X.I before
Xany messages are read into the program. Message filtering commands should
Xnot be placed in this file unless you know you're going to resource the file
Xlater as a command. For example, a filtering file, "filter", might contain:
X.sp
X.in +2
X.nf
Xpick -f Mailer-Daemon | save mail_errors
Xpick -f yukko | delete
Xpick -s -i thesis | save +thesis_mail
Xpick -t unix-wizards | +wizmail
Xupdate
Xsort d
X.in -2
X.fi
X.sp
XThe first command the user could type might be
X.B source filter
Xand the following would happen. First, all messages that have Mailer-Daemon
Xin the from line will be saved in the file "mail_errors". Then, all mail from
Xthe user "yukko" will simply be deleted. Next, all mail that has in the
Xsubject field "thesis" (case ignored, so "Thesis" would also match) would be
Xsaved in the file $folder/thesis. The next command would find all messages
Xthat were addressed to the group "unix-wizards" (of which the user is an elite
Xmember of) and save them in the file $folder/wizmail. The folder will be
Xupdated, removing all deleted mail (saved mail may be marked as deleted),
Xand the folder is reread and sorted according to the date of the messages.
X.PP
X.SH THE TTY INTERFACE
XIn the line-mode, the user is given a prompt to which commands are issued
Xand arguments are passed to commands. When the user types at the prompt,
Xeach line is parsed and words (or, arguments) are separated into an array
Xof strings. This array, also called an
X.I argument vector,
Xis then modified by expanding history references, command line aliases,
Xor expanding variable references. A command line ends when the end of
Xthe line is encountered or a pipe (|) or semicolon (;) character are
Xencountered, separating discrete commands.
X.PP
XWhen a command line has been determined and placed in an argument vector, the
Xfirst argument in the vector (the `command') is searched for in a list of legal
X.I Mush
Xcommands. If found, the function associated with that command is called and
Xthe rest of the line is passed to that function as
X.I command line arguments.
X.PP
XBefore commands are called, however, the input the user gives is preprocessed
Xin a style reminiscent of
X.I csh. Mush
Xalso supports a subset from each of the following aspects of
X.I csh.
X.in +2
X\(bu Command history.
X.br
X\(bu Command line aliasing.
X.br
X\(bu A `piping' mechanism to redirect "input" and "output" of commands.
X.in -2
X.PP
X.I Command history.
X.PP
XThe history mechanism remembers commands up to the value of the
X.B history
Xvariable. To reference previously typed commands, the `!' character
Xis used in the same manner as
X.I csh.
X.sp
XExamples:
X.nf
X.in +2
X!-2:$ two commands ago, last argument.
X!3:2-4 the third command, arguments two through four.
X!! the last command in its entirety.
X.sp
X.in -2
X.fi
XThere is a limited implementation of history modification.
XSupported is the argument selector which references
Xcommand line arguments and 'p' (echo, but don't execute the command).
X.PP
XDuring the sourcing of initialization files (.mushrc), history is not
Xin effect and therefore the ``!'' character does not cause history expansion.
XThis includes startup of the program and when the command
X.I source
Xis issued. Uucp style addresses that contain the ``!'' character may
Xbe given without the need to be preceded by a backslash in the
Xinitialization file. However, ``!'' does need to be escaped if
X.B cmd's
Xare used to reference command line arguments.
X.PP
X.I Command line aliasing.
X.PP
XThis feature enables command substitution similar to
X.I csh.
XTo be backwards compatible with UCB's Mail, the
X.I alias
Xcommand is used for address aliasing. Thus, the command
X.I cmd
Xis introduced in place of
X.I alias.
X.PP
XExamples:
X.nf
X.in +2
Xcmd d delete
Xcmd t type
Xcmd dt 'd ; t'
Xcmd - previous
Xcmd r 'replysender \\!* -e -i'
X.in -2
X.fi
X.sp
XIn the last example, if the user types `r 5',
X.I Mush
Xwill reply to sender of the fifth message and pass all the other
Xarguments along to the
X.B reply
Xcommand. Note the escaping of the ! character.
XThis must also be done if set in the initialization file (.mushrc).
XHad the user not specified a message number on the command line (`r'),
X.B respond
Xwould reply to the "current message" rather than the fifth message.
X.PP
X.I Piping commands.
X.PP
X"Output" from a command is a
X.B message list,
Xnot the
X.I text
Xin a message. A
X.B message list
Xis defined as the set of messages which the user specifies in a command or
Xthe messages a command affects after it is through executing.
XWhen one command is piped to another, the effect is that the second command
Xwill "consider only those messages the affected by first command."
XIn most cases,
X.I Mush
Xis smart enough to know when piping is occurring and may suppress text output
Xthat a command might produce.
X.PP
XExamples:
X.sp
X.ti +2
Xpick -f fred | save fred_mail
X.sp
XThis will find all the messages from "fred"
Xand save them all in the file named "fred_mail".
X.sp
X.ti +2
Xlpr 4-8 | delete
X.sp
XThis will send messages 4, 5, 6, 7, and 8 to the printer and then delete them.
X.sp
X.ti +2
Xheaders :o | delete
X.sp
XDelete's all old (already read) mail.
X.PP
XBecause action is taken on mail messages, not files,
Xmetacharacters such as `*' and `?' are not expanded to file names as
X.I csh
Xwould do. Instead,
X.I Mush
Xcommands take as arguments, message lists (a list references one or
Xmessages) to take action upon. To reference message numbers, there is a
Xspecial syntax that
X.I Mush
Xwill understand.
X.sp
X.in +2
X.nf
X.ta 2i
X* All messages.
X^ The first message.
X$ The last message.
X. The current message.
XN-M A range of messages between N and M.
X.sp
X.fi
X.in -2
XIn the last case, N and M may be * ^ $ . or digits referencing
Xexplicit message numbers. The range must be in ascending order.
X.sp
XYou can also negate messages by placing the message list inside
Xbraces, `{' `}' -- thus, the expression "2-19 {11-14}" references
Xmessages 2 through 19 except for those between 11 through 14.
X.sp
XNote that message lists are parsed left to right. Indicating negated
Xmessages may be reset by turning them on again later in the argument list.
XA common error new users have is to specify a negated list without
Xspecifying any beginning messages.
X.ti +2
Xdelete { 6 }
X.sp
XIn this example, the user attempted to delete all messages
Xexcept for number 6. He should have specified the * before hand.
X.sp
X.ti +2
Xpreserve ^-. { 3 }
XHere, the user specifies a valid message list and causes
X.I mush
Xto preserve all messages from the beginning of the list (message 1)
Xto the current message excluding message 3.
X.PP
XAs discussed, the command line is parsed and the command given is
Xcalled and the rest of the arguments on the command line are passed to it.
XIf no command has been found for the one given, then the variable
X.B unix
Xis checked. If set, the command line given is attempted to be run as a regular
X.I UNIX
Xcommand.
X.PP
XIf it is not set, or if the command cannot be found in the user's PATH
Xenvironment, a message will be printed indicating that the command was
Xnot found.
X.PP
XSince no `messages' are affected by
X.I UNIX
Xcommands, piping is disallowed either to or from such commands. If the
Xuser wishes to execute
X.I UNIX
Xcommands which are to be piped to one another (or use any sort of redirection),
Xthe command,
X.B sh
Xis provided for such purposes. Since
X.I Mush
Xwill parse the entire command line, caution should be taken by enclosing
Xquotes around questionable shell variables or metacharacters.
XSee the COMMANDS heading below for more detail.
X.PP
XThis shell-like quality is for the convenience of the user and is not
Xintended to replace the functionality of
X.I sh, csh,
Xor any other command interpreter.
X.sp
X.SH THE CURSES INTERFACE
XThe curses interface utilizes the curses routines intrinsic to most
XUNIX systems these days. This interface is screen oriented rather
Xthan line oriented and allows the user to access commands and messages
Xmore quickly at the cost of history, piping, and a few commands.
X.PP
XMany users who prefer the curses interface might want to always start
Xall their mail sessions in the curses interface. Putting the curses
Xcommand in your initialization file is a no-no, so you can alias your
Xlogin shell mail command to include the -C option. If you use the Bourne
XShell, you're going to have to type it out all the time. Mush is going
Xto attempt to know not to run a shell if you're just sending mail to someone,
Xso the command line sequences:
X.sp
X.nf
X% alias mail 'mush -C'
X% mail fred
X.fi
X.sp
Xwill mail to fred and not enter the shell. However, if you just said, "mail"
Xwith no arguments, you'll enter the shell in curses mode if you have mail.
XIf you don't, you'll be told so. If you want to enter curses mode even if
Xyou don't have mail, use the -S option on the command line.
X.PP
XIn curses mode, the user's terminal has it's "echo" turned off so commands
Xthat are issued are not echoed on the screen. Certain commands cause the mode
Xto return to normal for typing purposes (sending mail, for example).
XIn normal operation, the screen will display the current set of message
Xheaders, the current message number is in the top left corner, the
Xmail status on the top line, and the cursor will be placed on the current
Xmessage. The number of message headers displayed is set by the variable,
X.B screen.
XIf the user does not have that variable set, the baud rate is checked and
Xthe size of the screen is set according to optimal refresh time. Usually,
X300 baud gives 7 lines, 1200 gives 14, 2400 gives 22 lines, and all higher
Xbaud rates give the size of the screen, whatever that may be.
XNote that the top line is reserved for "status" and the bottom line is
Xfor user interaction should it be required.
X.PP
XThe user may now type commands via key sequences which are not echoed
Xto the screen. Thus, function keys may be bound to "commands" by using the
X.B bind
Xcommand.
XA list of key-to-command bindings can be found at runtime by typing `?'
Xin curses mode or by using the
X.B bind
Xcommand.
X.PP
XThe commands which you can map sequences to are intended to be as self
Xexplanatory as possible, but admittedly, it's easier to figure out via
Xtrial and error than to try to wade through this documentation.
XA list of the legal curses commands can be obtained when executing the
Xbind command. Regular tty line-mode commands are not issued from
Xthe curses interface; only special curses mode commands are understood.
XThe current list of valid curses commands is:
X.sp
X.ta 1.5i 3i 4.5i
X.in +4
X.nf
Xgoto msg write write list save
Xsave list copy copy list delete
Xdelete list undelete undelete list reverse video
Xredraw next msg back msg first msg
Xlast msg top page bottom page screen next
Xscreen back show hdr source saveopts
Xsearch up search down search cont preserve
Xsort sort reverse quit! quit
Xexit! exit update folder
Xshell escape line mode lpr chdir
Xvariable ignore alias my hdrs
Xversion mail flags mail reply
Xreply all display top display next
Xbind unbind help
X.fi
X.in -4
X.sp
X.PP
XThe following is a list of default key-command bindings. If you specify
Xbind commands in your initialization file that conflict with these defaults,
Xyour settings will override the defaults. The default settings given here
Xuse the ^-character method to indicate control characters.
XThus, `^X' would mean control-X even though you'd have to type "\\CX" to set
Xthe binding and actually use the control key and the `X' key simultaneously
Xto really
X.I do
Xa Control-X. This is mostly because nroff makes printing the backslash
Xcharacter so amazingly difficult.
X.TP
Xt, p, T=top, n=next
XDisplay (type/print) message. Top will display the first
X.B crt
Xlines of a message. `n' will print the next message.
XIf the current message is deleted, the next undeleted message is found.
XYou might notice this is different than the line mode which will return
Xan error message that the current message is marked as deleted.
X.TP
X+, j, RETURN
XGo to next message.
X.TP
X-, k, ^K
XGo to previous message.
X.TP
Xz, Z
XPrint next/previous screenful of messages.
X.TP
XH
XHeader information for the current is printed. This only works when
Xthe user is provided with the "...continue..." prompt and he wishes to
Xview the current message header instead of redrawing the entire screen.
X.TP
Xf
Xchange folder. If current folder has changed, verification for update
Xwill be prompted.
X.TP
X^U
Xupdate folder.
X.TP
Xv
Xset regular variables.
X.TP
Xa
Xset aliases
X.TP
Xh
Xset personal headers
X.TP
Xi
Xset ignored headers
X.TP
X|
Xsend message to printer
X.TP
Xm, M
Xsend mail (prompt for mail flags).
X.TP
Xd, D, u U
Xdelete/undelete messages (prompt for message list).
X.TP
X^P
XPreserve current message (toggle).
X.TP
Xr, R
Xreply sender/reply all.
X.TP
Xs, S, c, C, w, W
Xsave, copy, or write messages (capitals prompt for message lists).
X.TP
X!
XShell Escape --prompts for command: RETURN invokes a shell.
X.TP
Xo, O
XOrder messages (sort). O reverses order. The order in which to
Xsort messages is prompted.
X.TP
X(, )
Xsource/saveopts --filename is prompted.
X.TP
X/, ^/ ^N
Xforward, backward, continue search for patterns. Entire messages are
Xnot searched for here. Only the text available on the screen is searched for.
X.TP
XV
XPrint version number.
X.TP
X{, }
XTop/bottom of screen.
X.TP
X^, $
XGo to first/last message.
X.TP
X%
Xchange directory.
X.TP
Xg, 0-9
XGo directly to message number.
X.TP
X:[cmd]
XEnter line mode for one command (RETURN exits curses-mode).
X.TP
XQ, q, X, x
XQuit. `x' does not update mail. `Q' does not prompt for update verification.
X`Q' and `X' may be typed at the "...continue..." prompt whereas `q' and `x'
Xmay not.
X.TP
X^R
XToggle reverse video mode (current message is in reverse video).
X.TP
X^L
Xredraw the screen.
X.PP
XWhen setting new key sequences to be bound to commands, the user may
Xuse control keys and the ESCAPE character for extended commands.
XExceptions are control-C, control-\\, and possibly other control characters
Xdepending on your system's configuration or your current tty interrupt
Xcharacter settings. The spacebar may not be bound since
Xit is the only obvious way to return to the top level curses mode from the
X"...continue..." prompt.
X.PP
XWhen assigning key sequences to commands, the user enters the
X.B bind
Xcommand and prompting is done. If the
Xuser wishes to have control characters or the escape character in a key
Xsequence, he must use special notation since control characters are not
Xechoed visibly on the screen. This same sequence is used if the user wants
Xto bind sequences in the initialization file.
X.PP
XTo bind control characters, the sequence, "\\Cc" is used where ``c'' is the
Xcharacter which the control key will translate to and must be in upper case.
XThe sequence, "\\CP" would map
Xto control-P. If the user wishes to indicate the RETURN key, this is specified
Xwith the string, "\\n" and the tab key is specified by the string "\\t".
XOn a Wyse-50 terminal, the 8th function key outputs the three characters:
XControl-A, H, line-feed. To map this function key to a command, the
Xuser would have to enter the sequence, "\\CAH\\n" as the key sequence,
Xthen follow up with a valid curses command. From then on, if the user
Xuses that function key, then the command mapped to it will be executed.
X.PP
XThe ESCAPE key is signified by the sequence, "\\E". On a Sun-3 workstation,
Xthe R1 key outputs the character sequence: ESC, [, 2, 0, 8, z.
XThe corresponding key sequence would be "\\E[208z".
XRestrictions are that key sequences may not contain the space key
Xor begin with a digit. Unfortunately, this makes mapping the spacebar
Xto a command impossible.
X.PP
XWhenever a command is entered, if the command causes
Xthe screen to scroll or be refreshed in anyway, the mode is left in the
X.I continue
Xmode. When in this mode, the user is given his line-mode prompt followed
Xby "...continue..." indicating that he may issue a new command or
Xreturn to the top level where the current message headers are displayed
Xon the screen. Remember that this is still the curses mode, but much time
Xis saved by avoiding to redraw the screen after each command. The user
Xmay move up and down messages using the appropriate commands (j/k by default)
Xor anything else the curses mode allows. Unknown commands do not return to
Xthe top level, only the spacebar, and the exit and quit commands will return
Xto the top level.
XBecause the exit and quit commands are used to do this, there are 2 additional
Xways to "quit" in the program and return to the login shell.
XThe two commands, "exit" and "quit" commands will quit from the top level, but
Xthe commands,
X.B exit!
Xand
X.B quit!
Xare used to exit from the "continue" level in the curses interface as well
Xas from the top level.
X.PP
XNote that the best way to understand the curses interface is to just use it.
XIn line mode, the command "curses" puts you into curses mode.
X.PP
X.SH THE GRAPHICS INTERFACE
XWhen running the window-based graphics interface, there will be 5
Xwindows displaying panels of commands, message headers and a text
Xwindow which is used for displaying messages or writing messages
Xto send to other users.
X.PP
XThe panel items have labels describing their functionality. Selecting
Xa panel item with the LEFT mouse button causes the action to be executed.
XThe RIGHT mouse button displays a menu of options that the command may
Xbranch to. For example, the
X.B save
Xpanel item by default will save messages to the file "mbox", but if the
XRIGHT mouse button causes a menu to be displayed the choices of where
Xto save the message increases to include the items in the menu. These
Xtypically include the files in the user's folder directory (see the
X.B folder
Xvariable below).
X.PP
XAt the end of each list of menu entries for panel items is an item
Xlabelled "help." When this item is chosen, help with that command
Xis displayed in the center of the console.
X.PP
XWhen composing letters, the interface is the same for the tool mode,
Xthe line mode and the curses mode. Tilde escapes are recognized by all
Xthe interfaces, but the tool interface allows the user to use the menu
Xmouse button to select the tilde escape desired.
X.PP
XIf the user wishes to review a mail message while in edit-mode, he may
Xdo as the other interfaces and enter the tilde escape command, ``~:print''.
XThis will cause the current message (or message number if given) to be
Xdisplayed in the window. Editing is temporarily put on hold till the user
Xenters a `q' in the message window to indicate that he is done reading the
Xmessage and input is to be directed again to the letter being composed.
X.PP
X.SH GENERAL USAGE
X.PP
XBecause there are three different interfaces available to the user,
Xthe tty characteristics (backspace, kill-word, kill-line, redraw line)
Xare simulated identically to all routines. When the user has to type
Xsomething, the 4.2BSD style of tty driver interface is simulated whether
Xyou're in the window system, the curses mode, the tty-line mode, and
Xeven on System-V machines. This means that backspacing causes a
Xbackspace-space-backspace effect (erasing the character backspaced over).
XThe user may reset his tty characteristics using the stty command.
X.PP
X.I "Displaying messages.\ "
X.PP
XDepending on the interface you use, you can display any message in your
Xlist of messages as long as the message is not marked for deletion. If
Xthe message is marked as deleted, then use the
X.B undelete
Xcommand supplied by the interface you are using.
XTo display a message in line mode, specify a message to be displayed using
X.B print, type, p, t,
Xor by typing the message number, that message will be printed on the screen.
X.sp
XIn the graphics mode, you move the mouse over the message you wish to
Xbe displayed and select the LEFT mouse button. If the message you want
Xis not visible (in the header subwindow), you may type in the message
Xsubwindow the number of the message and hit return. That message number
Xwill be displayed.
X.sp
XIn curses mode, you can move the cursor over the message you want and type
Xa `t' or `p' to read the message. The user may "bind" other keys to call
Xthe function which displays messages if `t' or `p' are uncomfortable.
X.sp
XIn the line or curses mode, if the message has more lines than the variable
X.B crt,
Xthen a
X.I pager
Xwill be invoked to allow the user to page through the message without
Xhaving it race by the screen. The pager used is determined by the variable,
X.B pager.
XIf that variable is unset, the a default pager will be used. Note that
Xif pager is set, but not to a value, then nothing will be printed.
X.PP
XIn the tool mode, if a message is larger than the size of the message
Xsubwindow, the amount of the message viewed is displayed and the user
Xmay page through the message via `+' (forward by lines), `-' (backwards
Xby lines), LEFT mouse button (forward by pages), or RIGHT mouse button
X(backwards by pages). The user may precede the `+' and the `-' keystrokes
Xwith a numerical
X.I count
Xto specify how many lines to scroll.
X.PP
XAn alternative to displaying messages is the
X.B top
Xcommand. This command will print just the top few lines of a message.
XThe number of lines is determined by the variable,
X.B toplines.
XIf this variable isn't set, ``top'' will print the value of the variable,
X.B crt,
Xnumber of lines.
X.sp
X.PP
X.I "Sending mail.\ "
XYou can send mail using the
X.B mail
Xcommand or by responding to other mail. In either case, when you are
Xsending mail, you are in a mode where everything you type is added to
Xthe contents of the message. When you are done typing your message, you
Xcan type ^D to signify the end of the message. If you have the variable,
X.B dot
Xset, then you can end a message with a "." on a line by itself.
X.PP
XWhile you are composing a message,
X.I Mush
Xtreats lines beginning with the character `~' specially.
XThis is called a
X.B tilde escape.
XFor instance, typing ``~i'' (alone on a line) will place a copy
Xof the "current message" into your message body. It will not include
Xthe message headers of the message, just the body of text. Each line of
Xthe message will be preceded by "> " to indicate that it is an included
Xmessage. You can set the variable string
X.B indent_str
Xto a string if you want to precede those lines with
Xsomething other than "> ".
X.sp
XAvailable
X.I tilde escapes:
X[OPTIONAL arguments in square brackets]
X.TP
X~e [editor]
XEnter the editor. `set editor', env EDITOR, vi.
X.TP
X~v [editor]
XEnter the visual editor. `set visual', env VISUAL, vi.
X.TP
X~p [pager]
XPage the message body. `set pager', env PAGER, more.
X.TP
X~i [msg#'s]
XInclude current msg body [msg#'s] indented by indent_str.
X.TP
X~H [msg#'s]
XSame, but include the message headers from included messages.
X.TP
X~f [msg#'s]
XForward mail. Not indented, but marked as "forwarded mail".
X.TP
X~t [list]
XChange list of recipients. If a list is given, this list is
X.B appended
Xto the current list. If no list is given, then the current list
Xis displayed and the cursor placed at the end of the list. You
Xcan backspace over the stuff in the list or you can append more
Xaddresses onto the end of the list as desired. System-v users
Xmay only replace the line, retyping it if necessary, to append new
Xusers; specifying a list on the tilde line is recommended in this case.
X.TP
X~s [subject]
XModify the subject header. If an argument is given (a new subject), then
Xthe subject line is
X.B replaced
Xby the new subject line. If none is given, then the subject line is
Xdisplayed for editing just as the ~t command.
X.TP
X~c [cc list]
XModify carbon copy recipients identical to ~t.
X.TP
X~b [bcc list]
XModify blind carbon recipients identical to ~t.
X.TP
X~h
XModify all message headers. Each header is displayed one by one and
Xeach may be edited.
X.TP
X~S[!]
XInclude Signature file [don't include] at end of message. The variable,
X.B autosign
Xdescribes the file or string to append to the message.
XSee the VARIABLES section for more information on this variable.
X.TP
X~F[!]
XAdd a fortune at end of letter [don't add] at end of message.
X.TP
X~w file
XWrite message buffer to file name.
X.TP
X~a file
XAppend message buffer to file name.
X.TP
X~r file
XRead filename into message buffer.
X.TP
X~q
XQuit message; save in dead.letter if "nosave" is not set.
X.TP
X~x
XExit message; don't save in dead.letter.
X.TP
X~$variable
XInsert the string value for variable into message. If a boolean variable
Xis listed, nothing is appended regardless of its value.
X.TP
X~:cmd
XRun the
END_OF_FILE
if test 41182 -ne `wc -c <'mush.1.a'`; then
echo shar: \"'mush.1.a'\" unpacked with wrong size!
fi
# end of 'mush.1.a'
fi
echo shar: End of archive 03 \(of 12\).
cp /dev/null ark03isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 10 11 12 ; do
if test ! -f ark${I}isdone ; then
MISSING="${MISSING} ${I}"
fi
done
if test "${MISSING}" = "" ; then
echo You have unpacked all 12 archives.
rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
echo You still need to unpack the following archives:
echo " " ${MISSING}
fi
## End of shell archive.
monmonm