Path: utzoo!utgpu!news-server.csri.toronto.edu!rpi!zaphod.mps.ohio-state.edu!swrinde!cs.utexas.edu!uunet!sparky!kent
From: argv@zipcode.com (Dan Heller)
Newsgroups: comp.sources.misc
Subject: v18i072:  mush - Mail User's Shell, Part15/22
Message-ID: <1991Apr22.000501.19029@sparky.IMD.Sterling.COM>
Date: 22 Apr 91 00:05:01 GMT
Sender: kent@sparky.IMD.Sterling.COM (Kent Landfield)
Organization: Sterling Software, IMD
Lines: 1608
Approved: kent@sparky.imd.sterling.com
X-Checksum-Snefru: be92c2b4 2d1f6374 0bc333ae fd918d9a

Submitted-by: Dan Heller <argv@zipcode.com>
Posting-number: Volume 18, Issue 72
Archive-name: mush/part15
Supersedes: mush: Volume 12, Issue 28-47

#!/bin/sh
# do not concatenate these parts, unpack them in order with /bin/sh
# file mush.1 continued
#
if test ! -r _shar_seq_.tmp; then
	echo 'Please unpack part 1 first!'
	exit 1
fi
(read Scheck
 if test "$Scheck" != 15; then
	echo Please unpack part "$Scheck" next!
	exit 1
 else
	exit 0
 fi
) < _shar_seq_.tmp || exit 1
if test ! -f _shar_wnt_.tmp; then
	echo 'x - still skipping mush.1'
else
echo 'x - continuing file mush.1'
sed 's/^X//' << 'SHAR_EOF' >> 'mush.1' &&
Saves the contents of the letter to \*Qdead.letter\*U
(unless the `!' is specified) and then clears the message buffer; the user
remains in editing mode.
If the variable
.B nosave
is set, then `!' need not be specified.
.TP
~e [editor]
Enter the editor.
Defaults to variable
.BR editor ,
environment EDITOR, or
.IR vi ,
except in tool mode, where ~e is equivalent to ~v.
.TP
~F[!]
Add a fortune [don't add] at end of message.
Accessed via the \*QFortune\*U panel item in tool mode.
.TP
~f [msg-list]
Forward mail.
The included messages are not indented,
but are marked as \*Qforwarded mail\*U.
Accessed via the \*QInclude\*U panel item in tool mode.
.TP
~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 
advances the input cursor to each of the other headers in turn.
The mouse cursor changes to a \*Qbent arrow\*U when automatic
input cursor advance is active.
.TP
~I [msg-list]
Same as ~i, but also include the message headers.
Accessed via the \*QInclude\*U panel item in tool mode.
.TP
~i [msg-list]
Include the body of the current message (or listed messages).
Accessed via the \*QInclude\*U panel item in tool mode.
See the descriptions of the variables
.BR indent_str ,
.BR pre_indent_str ,
and
.BR post_indent_str .
.TP
~p [pager]
Page the message body; not available in tool mode.
Defaults to variable
.BR pager ,
environment PAGER, or the default pager set up by the system administrator.
This may be the internal pager.
.TP
~q
Quit message; save in ~/dead.letter if
.B nosave
is not set.
Not available in tool mode.
.TP
~r file
Read filename into message buffer.
Accessed via the \*QImport\*U panel item in tool mode.
.TP
~S[!]
Include [don't include] signature at end of message.
The variables
.B autosign
and
.B autosign2
describe the file or string to append to the message.
See the VARIABLES section for more information on these variables.
Accessed via the \*QAutosign\*U panel item in tool mode.
.TP
~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
.I replaced
by the new subject line.
If none is given, then the subject line is
displayed for editing just as in the ~t command.
.TP
~t [list]
Change list of recipients (\*QTo\*U list).
In tool mode, moves the cursor to the To: header.
In other modes,
if a list is given, this list is
.B 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.
.TP
~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 blanks to the previous length of the file.
.TP
~v [editor]
Enter the visual editor; works in tool mode.
Also accessible through the \*QEdit\*U button in tool mode.
Defaults to variable
.BR visual ,
environment VISUAL, or
.IR vi .
.TP
~w file
Write message buffer to the indicated file.
Accessible in tool mode via the \*QExport\*U panel item.
When the header editing is in use (the variable
.B edit_hdrs
or the \-E option of
.BR mail ),
this tilde-command can be used to create a \fIdraft file\fR.
Draft files are partially completed letters that you wish to save for
editing and eventually sending later.
See the
.B mail
command for a description of rereading and sending drafts.
.TP
~x
Exit message; don't save in dead.letter.
Accessible in tool mode via the \*QAbort\*U panel item.
.TP
~$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.
.TP
~:command
Run the
.I Mush
command specified by \*Qcommand\*U; 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.
.TP
~~
A line beginning with two escape characters is unaffected by
.I Mush
except that only a single tilde is inserted into the letter.
.PP
The variable
.B escape
may be set to describe a character other than `~' to be used as the
escape character.
However,
.I "tilde escapes are normally NOT interpreted when"
Mush
.IR "is started with redirected input" .
If tilde-interpretation is desired, use the \-i option when starting
.IR mush .
.PP
.IR "Mail Aliases" .
.PP
Mail aliases are shorthand names for long mail addresses.
These are supported in the same manner as UCB Mail supports them.
Because
.I Mush
has command line history reminiscent of
.IR 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 these files are being sourced.
See the INITIALIZATION and LINE-MODE INTERFACE sections for more
information on initialization file format and the history mechanism.
.PP
Aliases reference normal mailing addresses as well as other aliases.
If a loop is detected, then the user is notified and the message is forced
into the file
.B dead.letter
in the user's home directory.
The
.B unalias
command is used to reverse the effects of the
.B alias
command.
XFrom the tool mode, aliases can be set and unset in an
.IR "aliases subwindow" .
Press the RIGHT mouse button on the \*QOptions\*U item in the main
frame, and select \*QAliases\*U from the menu.
.PP
.IR Help .
.PP
.I 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
.B help
command gives information on both general usage and a few specific help
categories.
.PP
In text mode, most help is obtained by typing \-? as an argument to a
command.
Almost every command has the \-? option.
When this option is specified, most commands 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 is
given to fully explain a concept.
.PP
In line mode, typing `?' as a command displays a list of possible commands.
In the curses mode, the `?' key displays 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.
.PP
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 \*Qmenu button\*U) when pointing to any
panel button and a number of items appear in a menu.
The last command in the menu list is often one labeled \*Qhelp\*U.
If a button does not have a menu or has no help item, check the
menu of the \*QHelp\*U button for related topics.
Selecting any help item opens a new scrollable window with help text.
.I "Note:  The limited number of file descriptors in SunOS 3.5 forces"
Mush
.I "to display help information in the"
.IR "message window in the main frame" .
.\" Some nroffs can't handle long .IR arguments
.SH INITIALIZATION
After the command line arguments have been interpreted
.I Mush
reads commands from one or more
.B "initialization files"
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,
.I Mush
reads the user's personal initialization file.
.PP
The user's file is determined by first looking for the environment variables
.I MUSHRC
or
.IR MAILRC .
If neither of those environment variables is set, then the file
.I .mushrc
is searched for in the home directory of the user.
If that file cannot be found,
.I Mush
attempts to read the file
.I .mailrc
from the same directory.
Finally, if that file cannot be read, no initialization is done
and the default values are in effect.
.PP
If the user has no home directory, or permissions prevent read/write access
to $HOME, /tmp is used as the home directory.
See the
.B home
variable under the VARIABLES section.
.PP
Once in the shell, the
.B source
command may be used to specify a file if you want to read commands
from a file other than the default.
The command
.B saveopts
saves all variable settings, aliases, and all other
.I Mush
settable attributes, to aid in creating an initialization file.
If no filename is given on the command line,
the
.B source
and
.B saveopts
commands choose a file in the manner described above.
.B Saveopts
does not overwrite the file if it exists.
In such cases, you are prompted to confirm overwrite.
If you confirm overwriting the existing file, remember that existing \*Qif\*U
expressions or other manually entered comments or non variable-setting type
commands that previously existed in the file are lost.
.PP
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
.IR UNIX (TM)
commands that are interactive.
The responsibility of not running interactive commands is left to the user.
Because the initialization file is read
.I 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
.IB re- source
the file later as a command.
.PP
.IR "Initialization File Format" .
When reading the initialization file,
.I Mush
recognizes 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 in quotes (single or double), then it is not
considered a comment.
Examples:
.sp
.ti +2
set shell = /bin/csh  # set the shell variable
.ti +2
# this entire line has been commented out.
.ti +2
set prompt = "Message #%m: "  # The `#' is within quotes
.PP
The
.B exit
command has special meaning in the initialization file.
If the command is found,
.I Mush
does not exit, but rather, discontinues reading from the file immediately.
.PP
There may be \*Qif\*U expressions within the initialization file to determine
certain runtime states of
.IR Mush .
No parentheses are allowed and only one boolean expression may be
evaluated per line; that is, no \*Q&&\*U or \*Q|\||\*U may be used in
expressions.
An \*Qelse\*U on a line by itself may precede alternative
actions.
\&\*QIf\*U expressions may be nested to any reasonable depth, but
there must always be an \*Qendif\*U matching each \*Qif\*U expression.
The statements associated with an \*Qif\*U expression are never on the
same line with the conditional expression.
.PP
Conditional expressions understood include the internal variables
.IR istool ,
.IR iscurses ,
.IR is_shell ,
.IR hdrs_only ,
.IR is_sending ,
and
.IR redirect .
These are internal variables whose values cannot be referenced using the
\*Q$variable\*U method of variable expansion.
If
.I istool
is true, the program is going to run in the tool mode.
If
.I 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
.I is_shell
is true, then
.I Mush
has entered the shell;
.I is_shell
is always false at startup when initialization files are read,
and is always true when files are sourced after initialization with the
.B source
command or the \-F option.
.PP
If
.I hdrs_only
is true, then the -H flag on the command line has been given.
If
.I 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
.I 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
.B \-i
option on the command line is required to run the shell if redirect is on.
If \-i is specified, the value for
.I redirect
is set to false.
Note that any time
.I Mush
runs when not connected to a terminal, it
believes that input has been redirected.
See the MUSH SCRIPTS section for more details.
.PP
The `!' operator may be used to negate expressions, thus,
.sp
.nf
.in +2
if !istool
.ti +4
exit
else
.ti +4
set autoprint
endif
.in -2
.fi
.sp
means that if you are not running as a tool, stop reading commands from this
file.
Otherwise, set the autoprint variable.
.sp
.in +2
.nf
set hdr_format = "%25f %7d (%l/%c) %25s"
if hdrs_only
.ti +4
exit
endif
.in -2
.fi
.sp
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.
.sp
.in +2
.nf
if !iscurses
.ti +4
set crt = 24 screen = 18
endif
.in -2
.fi
.sp
This segment checks to see that we're not running in curses mode, and if not
it sets our crt and screen sizes.
This is mostly because the curses mode sets 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.
.PP
String evaluation is allowed in \*Qif\*U expressions, and the operators
\*Q==\*U and \*Q!=\*U may be used to determine equality or inequality,
and \*Q=~\*U and \*Q!~\*U may be used for pattern-matching.
Usually, variables are compared with constants for evaluation.
.PP
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
\*Q$?variable\*U (as in
.IR csh )
but there is not currently any way to test for an empty string value.
.sp
.in +2
.nf
if $TERM == adm3a
.ti +4
set pager = more
else
.ti +4
set pager = less
endif
.in -2
.fi
.sp
This segment tests to see if the user's terminal type is \*Qadm3a\*U.
If it is, then it sets the pager variable to be the 
.I more
program.
Note that the variable TERM is obtained from the user's environment if a
shell variable is not set already.
Otherwise, the pager variable is set to \*Qless\*U.
This exemplifies the fact that
.I less
frequently fails to function correctly
for the terminal type \*Qadm3a\*U so we don't use it.
.sp
Also supported in \*Qif\*U expressions are the test flags \*Q-e\*U
and \*Q-z\*U.  These flags test to see if a file exists (\*Q-e\*U) or
if it is zero-length (\*Q-z\*U).
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.
.PP
After sourcing the initialization file,
.I 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
.B 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
.B 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.
.PP
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
.B source
command.
Such files use the same format as the initialization files and may use all
the same tests in \*Qif\*U expressions.
Sourcing of a file of filter commands such as those in the example above
can be automated by using the \-F option when \fIMush\fR is started.
Also see the MUSH SCRIPTS section for other uses.
.SH "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
.IR "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.
.PP
When a command line has been parsed and placed in an argument vector, the
first argument in the vector (the \*Qcommand\*U) is searched for in a list
of legal
.I Mush
commands.
If found, the function associated with that command is called and
the rest of the line is passed to that function as
.IR "command line arguments" .
.PP
Before commands are called, however, the input the user gives is preprocessed
in a style reminiscent of the C-shell
.RI ( csh ).
.I Mush
also supports a subset from each of the following aspects of
.IR csh :
.in +2
\(bu Command history.
.br
\(bu Command line aliasing.
.br
\(bu \*QPiping\*U mechanism to
redirect \*Qinput\*U and \*Qoutput\*U of commands.
.br
\(bu Filename metacharacters.
.in -2
.PP
.BR "Command history" .
.PP
.I Mush
supports a history mechanism similar to that supplied by
.IR csh .
A subset of
.I csh
history modifiers are supported to reference previously
issued commands and to extract specified arguments from these commands.
.PP
The history mechanism remembers a list of past commands whose length is
bounded by the value of the
.B 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
.IR csh .
There is a limited implementation of history modification;
supported are the argument selectors that reference
command line arguments and \*Q:p\*U (echo, but don't execute the command).
.sp
Examples:
.nf
.in +2
.ta 1i
!-2:$	two commands ago, last argument.
!3:2-4	the third command, arguments two through four.
!!:p	print the last command in its entirety.
.in -2
.fi
.PP
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
.I 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
.BR cmd 's
are used to reference command line arguments.
.PP
.BR "Command line aliasing" .
.PP
Command aliases are different from mail aliases in that they are used
to expand to commands.
This feature enables command substitution similar to
.IR csh .
To be backwards compatible with UCB Mail, the
.B alias
command is used for address aliasing.
Thus, the command
.B cmd
is introduced in place of
.BR alias .
.PP
Examples:
.nf
.in +2
cmd d delete
cmd t type
cmd dt 'd ; t'
cmd - previous
cmd r 'reply \\!* -e -i'
.in -2
.fi
.sp
In the last example, if the user types \*Qr 5\*U,
.I Mush
replies to sender of the fifth message and pass all the other
arguments along to the
.B 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,
.B reply
would respond to the \*Qcurrent message\*U rather than the fifth message.
.PP
.BR "Piping commands" .
.PP
.I Mush
commands can be \*Qpiped\*U 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 \*Qtext\*U that is returned
(as it is in
.I sh
and
.IR csh ),
but instead is a
.B "message list"
of the messages that were affected.  A
.B "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
considers only those messages affected by the first command.
In most cases,
.I Mush
is smart enough to know when piping is occurring and may suppress text output
that a command might produce.
.PP
Examples:
.sp
.ti +2
pick -f fred | save fred_mail
.sp
This finds all the messages from \*Qfred\*U
and saves them all in the file named fred_mail.
.sp
.ti +2
lpr 4-8 | delete
.sp
This sends messages 4, 5, 6, 7, and 8 to the printer and then deletes them.
.sp
.ti +2
headers :o | delete
.sp
Deletes all old (already read) mail.
.PP
Because action is taken on mail messages, not files,
metacharacters such as `*' and `?' are not expanded to file names as
.I csh
does.
Instead,
.I Mush
commands take
.I "message lists"
as arguments (a list references one or messages) to take action upon.
When referencing message numbers,
.I Mush
understands the following special syntax:
.sp
.in +2
.nf
.ta 1.0i
*	All messages
^	The first message
$	The last message
\&.	The current message
N\-M	A range of messages between N and M, inclusive
.sp
.fi
.in -2
In the last case, N and M may be * ^ $ . or digits referencing
explicit message numbers.
The range must be in ascending order.
.sp
You can also negate messages by placing the message list inside
braces, `{' `}' \*- thus, the expression \*Q2-19 {11-14}\*U references
messages 2 through 19 except for messages 11 through 14.
.sp
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.
.sp
.ti +2
delete { 6 }
.sp
In this example, the user attempted to delete all messages
except for number 6.
He should have specified `*' beforehand.
A correct example:
.sp
.ti +2
preserve ^-. { 3 }
.sp
Here, the user specifies a valid message list and causes
.I Mush
to preserve all messages from the beginning of the list (message 1)
to the current message, excluding message 3.
.PP
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
.I Mush
command has been found that matches the one given, then the variable
.B unix
is checked.
If it is set,
.I Mush
attempts to run the command line as a
.IR UNIX (TM)
command.
.PP
If
.B unix
is not set, or if the command could not be found in the user's PATH
environment, a message is printed indicating that the command was
not found.
.PP
Since no \*Qmessages\*U are affected by \fIUNIX\fR
commands, those that appear within \fIMush\fR
pipelines are executed by the \fBpipe\fR command.
A \fIUNIX\fR command may never be the first command in a pipeline
unless the \fBpipe\fR command is used explicitly.
If the user wishes to execute \fIUNIX\fR
commands that are to be piped to one another (or use any sort of redirection),
the command \fBsh\fR is provided for such purposes.
Since \fIMush\fR parses the entire command line, caution should be
taken to enclose questionable shell variables or metacharacters with
quotes to prevent \fIMush\fR from expanding them.
See the COMMANDS heading below for more detail.
.PP
This shell-like quality is for the convenience of the user and is not
intended to replace the functionality of
.IR sh ,
.IR csh ,
or any other command interpreter.
.PP
.BR "Filename metacharacters" .
.PP
.IR 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 (\*Q~/Mail\*U
or the value of the variable
.BR folder ).
Another user's home directory can also be referenced as \*Q~username\*U,
and for this reason files in the user's home directory must be referenced
as \*Q~/filename\*U.
However, the `/' character is optional when referring to folders;
that is, \*Q+filename\*U and \*Q+/filename\*U both refer
to the same file in the folder directory.
.PP
If filename completion is enabled by setting the variable
.BR complete ,
the command interpreter expands
.IR 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
.B complete
for limitations of this facility.
.SH "CURSES INTERFACE"
The curses interface utilizes the curses routines intrinsic to most
.I 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.
.PP
Many users who prefer the curses interface might want to always start
all their mail sessions in the curses interface.
Putting the
.B 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.
.I Mush
attempts to know not to run a shell if you're just sending mail to
someone, so the
.I csh
command sequences:
.sp
.ti +2
% alias mail 'mush -C'
.ti +2
% mail fred
.sp
sends mail to fred but does not enter the shell.
However, if you just said \*Qmail\*U
with no arguments, you enter the shell in curses mode if you have mail.
If you have no mail, you are told so, and the shell does not start.
If you want to enter curses mode even if
you don't have mail, use the \-S option on the command line.
.PP
In curses mode, the user's terminal has its \*Qecho\*U 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 displays 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 is placed on the current
message.
The number of message headers displayed is set by the variable
.BR 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 \*Qstatus\*U and the bottom line is
for user interaction should it be required.
.PP
The user may now type commands via key sequences that are not echoed
to the screen.
Thus, function keys may be bound to \*Qcommands\*U by using the 
.B bind
command.
A list of key-to-command bindings can be found at runtime by typing `?'
in curses mode or by using the
.B bind
command in line mode.
.PP
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:
.sp
.ta 2i 4i
.in +4
.nf
alias	last-msg	saveopts	
back-msg	line-mode	screen-back	
bind	lpr	screen-next	
bind-macro	mail	search-again	
bottom-page	mail-flags	search-back	
chdir	map	search-next	
copy	map!	shell-escape	
copy-list	mark	sort	
delete	my-hdrs	sort-reverse	
delete-list	next-msg	source	
display	preserve	top	
display-next	quit	top-page	
exit	quit!	unbind	
exit!	redraw	undelete	
first-msg	reply	undelete-list	
folder	reply-all	update	
goto-msg	reverse-video	variable	
help	save	write	
ignore	save-list	write-list	
.fi
.in -4
.sp
.PP
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 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' means control-X even
though you have to type \*Q\\CX\*U to set
the binding and actually use the control key and the `X' key simultaneously
to really
.I do
a Control-X.
.TP
\&., t, p, T=top, n=next
Display (type/print) message.
Top displays the first
.B crt
lines of a message.
Next prints 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 returns
an error message that the current message is marked as deleted.
.TP
+, j, J, RETURN
Go to next message.
.TP
-, k, K, ^K
Go to previous message.
.TP
^, $
Go to first/last message.
.TP
{, }
Go to top/bottom of screen.
.TP
a
Set aliases.
.TP
b, B
Set/unset bindings.
.TP
d, D, u, U
Delete/undelete messages (capitals prompt for message list).
.TP
f
Change folder.
If current folder has changed, verification for update is requested.
.TP
g, 0-9
Go directly to a specified message.
When the \*Qgoto\*U command
is selected, a prompt at the bottom of the window prompts for a
.BR "message list" .
Anything that describes a message list may be used.
Since
.I Mush
commands return message lists, a legal
.I Mush
command enclosed in backquotes may be used to go to a particular message.
The new current message pointer points to the next
message, returned by the command, that is below the old current message.
An example:
.sp
.ti +2
goto msg: `pick \-f argv`
.sp
This causes the current message to move to the first message
in the current folder from the user \*Qargv\*U that comes after the
message pointed to when the \*Qgoto\*U was issued.
So, if messages 1 and 5
are from the user \*Qargv\*U and the current message the user was on
was message 3, then the new current message is message 5, since it
is the first message found after message 3 that is from \*Qargv\*U.
If none of the messages are found after the current message, the new
current message is the first one returned by the command.
.TP
h
Set personal headers.
.TP
i
Set ignored headers.
.TP
m, M
Send mail (capital prompts for mail flags).
.TP
o, O
Order messages (sort; capital reverses order).
A prompt requests the sort constraints.
.TP
q, Q, x, X
Quit/exit.
\&`q' tests 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!) works even when typed at the
\*Q...continue...\*U prompt, whereas `q' and `x' do not.
.TP
r, R
Reply/reply all.
.TP
s, S, c, C, w, W
Save, copy, or write messages (capitals prompt for message lists).
.TP
v
Set regular variables (as opposed to environment variables).
.TP
V
Print version number.
.TP
z, Z
Print next/previous screenful of message headers.
.TP
^L
Redraw the screen.
.TP
^P
Preserve current message (toggle).
.TP
^U
Update folder.
A prompt requests confirmation.
.TP
^R
Toggle reverse video mode (current message is in reverse video).
.TP
*
Toggle mark for this message (see the \*Qmark\*U command).
.TP
|
Send message to printer
.TP
!
Shell Escape.
Prompts for command; RETURN invokes a shell.
.TP
%
Change directory.
.TP
(, )
Source/saveopts.
Prompts for file name.
.TP
/, ^/, ^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.
.TP
&&
Create a curses mode macro.
.TP
&:
Create a line mode macro.
.TP
&!
Create a composition mode macro.
.TP
:[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).
.PP
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.
.PP
When assigning key sequences to commands, the user enters the
.B 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.
.PP
To specify control characters in ASCII format for the bind command, the
sequence \*Q\\Cc\*U is used where `c' is the
character that the control key translates to and must be in upper case.
The sequence \*Q\\CP\*U maps to control-P.
If the user wishes to indicate the RETURN key, this is specified
with the string \*Q\\n\*U and
the tab key is specified by the string \*Q\\t\*U.
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 must enter the sequence \*Q\\CAH\\n\*U 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 is executed.
.PP
The ESCAPE key is signified by the sequence, \*Q\\E\*U.
On a Sun-3 workstation,
the R1 key outputs the character sequence: ESC, [, 2, 0, 8, z.
The corresponding
.B bind
key sequence is \*Q\\E[208z\*U.
Restrictions are that key sequences may not contain the space character
unless bound in line mode, and can never begin with a digit.
.PP
Whenever a command is entered, other than `^L'
.RB ( redraw ),
which causes the screen to scroll or be refreshed in any way,
.I Mush
is left in the
.I continue
mode.
When in this mode, the user is given his line-mode prompt followed
by \*Q...continue...\*U 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 return to the top level.
Because of this, there are 2 additional
ways to \*Qquit\*U from curses mode and return to the login shell.
The \*Qexit\*U and \*Qquit\*U commands quit from the top level, but
the commands
.B exit!
and 
.B quit!
are used to exit from the \*Qcontinue\*U level in the curses interface as well
as from the top level.
.PP
Note that the best way to understand the curses interface is to just use it.
In line mode, the command \*Qcurses\*U puts you into curses mode.
.SH "GRAPHICS TOOL INTERFACE"
When running the window-based tool interface, there are 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 \*Qvi\*U movements (j, k, ^U, ^D, etc.),
in addition to having scrollbars.
.PP
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 affect the message.
Possible actions are to display the message, delete or undelete it, reply to
it, save it, preserve it
(see the
.B preserve
command), or print it (hardcopy).
.PP
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
.B Save
panel item by default saves messages to the file \*Qmbox\*U, 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
.B folder
variable below).
.PP
At the end of most lists of menu entries for panel items is an item
labeled \*Qhelp\*U.
When this item is chosen, an new window is opened where help for that
command is displayed.
The help windows can be scrolled in the same ways as the message
display window.
.I "Note:  The limited number of file descriptors in SunOS 3.5 forces"
Mush
.I "to display help information in the"
.IR "message window in the main frame" .
.\" Some nroffs can't handle long .IR arguments
.PP
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 \*QSending mail\*U, under the summary of tilde escapes,
for more details of composition frame command items.
As long as the composition frame is open, all
.I Mush
command output is
redirected from the small window in the main frame to the small window here.
\fINote:  This subwindow is not present in SunOS 3.5 due
to the limited number of file descriptors; command output stays in the
main frame in that case\fR.
The SunView
.I 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.
.SH COMMANDS
Described below are legal commands understood by
.I 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, \*Qd*\*U deletes all messages, and \*Qu1-7 {4}\*U undeletes
messages 1 through 7 except for message number 4.
.B NOTE:
\fIThis \*Qtoken splitting\*U may have unexpected side effects, especially
for \fRUNIX\fI commands whose names contain digits.\fR
.PP
The ability to customize commands using the
.B cmd
facility allows users to customize
.I 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
.I 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.
.PP
The following is a list of all recognized commands.
Since most commands accept a
.I "message list"
as an argument, arguments are noted only when they differ from a message list.
.TP
.B about
Gives information about the authors of this wonderful software.
.TP
.BR alias " [name] [address-list]"
.ns
.TP
.BR unalias " name"
The
.B 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,
.sp
.nf
.ti +2
alias dan dheller@cory.berkeley.edu argv@zipcode.com
.fi
.sp
This defines the name \*Qdan\*U to be shorthand for two addresses,
both of which happen to be Dan Heller.
.sp
The command
.B unalias
can be used to remove an alias definition.
.sp
With no arguments,
.B 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.
.\" Note: .TP may use @ as delimiter for some computations.
.\" Can't have "user@host" in the line, so use "address".  Bleah.
.TP
.BR alternates " [host-list] [*[user]] [address] [!path!user]"
.RB ( alts )
This command
is useful if you have accounts on several machines.
It can be used to inform
.I Mush
that your login name at each of the listed hosts is really you.
When you
.B reply
to messages,
.I Mush
does not send a copy of the message to your login name at any of the
hosts listed on the
.B alternates
list.  If the special symbol \*Q*\*U is used, then your login name is
matched against all pathnames and local addresses.
A user name may be appended to the \*Q*\*U, in which case that name is
matched instead of your login name.
.sp
If you have another login name on the local or remote machine, then
that login may be specified either as \*Quser@machine\*U or
by preceding the login name or a UUCP path to the login name by a `!'
character.
.sp
For example,
.sp
.nf
.ti +2
alts zipcode maui1 dheller@cory.berkeley.edu !root
.fi
.sp
are all either hostnames or pathnames to accounts owned by the same user.
The last item, \*Q!root\*U matches mail to \*Qroot\*U only if it is
destined for the local machine, e.g. a workstation.
Root accounts elsewhere are not considered to be equivalent.
The address \*Qdheller@cory.berkeley.edu\*U indicates that at the machine
\*Qcory.berkeley.edu\*U the user \*Qdheller\*U is the same person as the
current user at the local machine.
This could also have been specified in UUCP format:
.sp
.nf
.ti +2
alts !cory.berkeley.edu!dheller
.fi
.sp
The leading `!' character is required to differentiate paths ending in a
login name from those to which the user's login name should be appended.
.sp
If the
.B alternates
command is given with no arguments, the current set of alternate
names is displayed.
Names entered in \*Quser@machine\*U form are displayed in UUCP format.
Note that
.B alternates
is not cumulative; any arguments given to the
.B alternates
command removes the current list and replace it.
.TP
.BR await " [\-T timeout]"
Directs the shell to wait for the arrival of new mail.
New mail is checked approximately every 30 seconds, or every
.I 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 \*Qawait\*U appears in the value of the variable
.BR quiet ,
the terminal bell rings when
.B await
reads in a new message (see the VARIABLES section for details).
.TP
.BR bind " [string [command [parameters]]]"
.ns
.TP
.BR unbind " string"
.rs
Bind the sequence of keystrokes specified by
.I string
to the curses-mode function,
.IR command .
The
.I string
is usually one or two characters, or a sequence sent by
one of the \*Qfunction keys\*U 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
.I parameters
are currently recognized only for the special
.B macro
function; see the
.B bind-macro
command for details.
.sp
If no arguments are given to
.BR bind ,
the current set of curses bindings are listed;
if only a
.I string
argument is given, the binding for that string is listed;
and if both a
.I string
and a
.I command
are given, a curses binding is created such that when the
.I string
is typed in curses mode, the function specified by
.I command
is executed.
.sp
Bindings can be removed by using the
.B unbind
command.
.TP
.BR bind-macro " [string [expansion]]"
This command is an abbreviation, which invokes the
.B bind
command with the special function
.B macro
as the second argument.
The effect of binding a curses macro is that whenever the
.I string
is typed in curses mode, the effect is the same as if the
.I expansion
had been typed instead.
A special syntax is provided for including non-printing (control)
characters in both the
.I string
and the
.IR expansion ;
see the CURSES INTERFACE section and the MACROS section for details.
.sp
If no arguments are given,
.B bind-macro
lists the current curses mode macros.
It is otherwise identical to
.in +4
.B bind
.I string
.B macro
.IR expansion .
.in -4
.TP
.B cd
Change the working directory to that specified, if given.
If no directory is given, then changes to the user's home directory.
.TP
.BR cmd " [name [command]]"
.ns
.TP
.BR uncmd " name"
.rs
Command line aliases are set and unset using these commands.
More extensive information is given in the LINE-MODE INTERFACE section.
.B Uncmd
may take `*' as an argument to uncmd everything set.
.TP
.BR curses " [off]"
The
.B curses
command causes
.I 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
.IR .mushrc )
this command is the same as giving the \-C (\-curses) switch on the
.B mush
command line.
.sp
The argument
.I off
may be used
.I only
in initialization files, including those read with \-I (\-init),
and has the effect of turning off the \-C switch.
.I Off
is ignored at all other times, even in files read with \-F (\-source).
.TP
.BR 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.
.sp
If the user suspects memory allocation problems, a debugging
level of 5 or higher prevents memory from being freed so that
memory bounds won't get overwritten.
.sp
If the user suspects Mail Transport Agent errors,
a debugging level of 3 or higher prevents the MTA from starting
and outgoing mail is directed to the standard output instead of actually
being sent.
.TP
.BR delete / undelete
.RB ( d / u )
Takes a message list as argument and marks them all as deleted.
Deleted messages are not saved in
.IR mbox ,
nor are they be available for most other commands.
If the folder has not been updated, deleted messages can be recovered
with
.BR undelete .
.TP
.B dp
.R (also
.BR dt )
Deletes the current message and prints (types) the next message.
.TP
.BR 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.
.sp
Examples:
.sp
.nf
.ti +2
echo -h This message is from %a and is dated %d.
.br
might produce:
.ti +2
This message is from zipcode!argv and is dated Dec 14, 1988.
.sp
.ti +2
echo -p There are %n new messages to read in %F.
.br
might produce:
.ti +2
There are 5 new messages to read in /usr/spool/mail/argv.
.fi
.sp
Note that -h and -p cannot be specified together.
.TP
.B edit\ \ 
.RB ( e ,
.BR 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 are notified and the temporary file used to edit
the message is not removed.
.TP
.BR eval " [\-h | \-p] arg ..."
As in most shells, the list of arguments to
.B eval
is re-parsed and then executed as a command.
This is useful primarily for causing multiple levels of variable expansion.
.sp
If the \-h option is given,
.B eval
expands header format strings in the argument list before executing the
command.
Similarly, the \-p option expands prompt format strings in the argument
list before executing.
These formats are expanded \fIlast\fR, 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 
.I current
message.
For example,
.sp
.ti +2
eval \-h pick \-f %a
.sp
finds all messages from the same author as the current message.
See the the entries for
.I hdr_format
and
.I prompt
in the VARIABLES section for more details.
.sp
Note that -h and -p cannot be specified together.
.TP
.B exit\ \ 
.RB ( x )
Terminates
.I Mush
immediately without modifying the current folder or system spool directory.
In scripts and initialization files,
.B exit
is handled specially and discontinues the file without leaving the program.
However,
.I x
terminates the program as usual.
.TP
.BR expand " alias-list"
Aliases, given as arguments, are expanded as they are when you
send mail to each.
Nested alias references are fully expanded.
.TP
.BR flags " [ [ + | \- ] [ D f N O P p R r S U ] ] [msg-list]"
This command modifies the flag bits set on the listed messages.
SHAR_EOF
true || echo 'restore of mush.1 failed'
fi
echo 'End of  part 15'
echo 'File mush.1 is continued in part 16'
echo 16 > _shar_seq_.tmp
exit 0
exit 0 # Just in case...
-- 
Kent Landfield                   INTERNET: kent@sparky.IMD.Sterling.COM
Sterling Software, IMD           UUCP:     uunet!sparky!kent
Phone:    (402) 291-8300         FAX:      (402) 291-4362
Please send comp.sources.misc-related mail to kent@uunet.uu.net.