argv@zipcode.com (Dan Heller) (04/22/91)
Submitted-by: Dan Heller <argv@zipcode.com>
Posting-number: Volume 18, Issue 73
Archive-name: mush/part16
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" != 16; 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' &&
It should not normally be needed, but is provided to allow users, through
the
.B cmd
facility, to alter the ways that certain conditions are recorded.
Multiple flag bits may be set or modified at once.
The modifiable flag bits are:
.sp
.nf
.ta 2i
.in +4
D deleted
f forwarded
N new
O old
P preserved
p printed
R read
r replied-to
S saved
U unread
.in -4
.fi
.sp
If a `+' or `\-' is included in the list of bits, the specified bits are
turned on or off respectively, without modifying other bits.
If no `+' or `\-' is given, then the list of bits is set explicitly and
all other bits are lost.
The `\-' modifier can be escaped with a backslash (i.e., \*Q\\\-\*U) to
prevent its interpretation as part of a message range, or it may be given
\fIafter\fR the list of bits for the same reason.
.sp
Message lists can be piped to the
.B flags
command; for example, you may use
.sp
.nf
.ti +4
cmd r 'flags \\!* + r | reply'
.fi
.sp
to mark as
.I replied-to
all messages included in a reply.
.TP
.BR folder " [\-N] [-n] [\-r] [ %[user] | # | & | file ]"
.RB ( fo )
Change current folder.
With no arguments, prints the name of the current folder.
The arguments are:
.nf
.ta 1i
.in +2
\-N No headers are displayed upon entering new folder
\-n The current folder is not updated
\-r Set Read-Only mode (can't alter new folder)
%[user] Change to /usr/spool/mail/[user] (default is yours)
# Switch back to the previous folder
& Change folder to $mbox (default is ~/mbox)
.in -2
.fi
.sp
File names that do not begin with `/' are interpreted relative to the current
directory unless they begin with one of the metacharacters `+' or `~'.
As in
.IR csh ,
the character `~' expands to the user's home directory (or to some other
user's home directory if used as \*Q~username\*U).
The character `+' is expanded to the name of the user's
.I folder
directory (defaults to \*Q~/Mail\*U or the value of the variable
.BR folder ).
For compatibility with other mailers, no `/' character needs to appear
between the `+' and the name of the folder (see \*QFilename metacharacters\*U
in the LINE-MODE INTERFACE section).
.sp
This command can only appear in a pipeline if it is the first command;
it returns a list of all the messages in the new folder.
This command cannot be used in initialization files before the shell
has started.
.sp
For compatibility with older versions, the argument `!' with
no leading `\-' is interpreted as \-n.
.TP
.B folders
List the names of the folders in your folder directory.
Your folder directory is the directory
.I Mail
in your home directory.
Or, you can set the variable
.B folder
to specify another folder directory.
.br
.TP
.BR from " [ + | \- ] [msg-list] [pattern]"
.RB ( f )
With no arguments,
.B from
prints the current message's header summary (see the variable
.BR hdr_format ).
If given a pattern,
.B from
prints the headers of those messages whose \*QFrom:\ \*U lines
match the pattern.
When a message list precedes the pattern, or when a message list is
supplied by a pipeline, the search is restricted to that list.
If only a message list is given (or piped),
.B from
prints the headers of the listed messages.
.sp
The special arguments `\-' and `+' can be given to move the
current message pointer to the previous or next message,
respectively, while also printing that message's header.
If a message list was given in addition to `\-' or `+', then
the current message pointer is set to the first or last
message, respectively, in the message list given.
Examples:
.sp
.ti +2
from + Dan
.sp
prints the headers of all messages that contain \*QDan\*U in
in the author's name and set the current message pointer to
the last one of that kind in the list.
.sp
.ti +2
from \- 10-30 {16}
.sp
prints the headers of messages 10 through 30 except for
message 16 and set the current message pointer to 10.
.sp
.ti +2
from +
.sp
prints the header of the message after the current message
and increments the current message pointer to the next message.
.sp
.ti +2
from $
.sp
prints the last message's header but does not move the current
message pointer.
.TP
.BR headers " [ [\-H][:c] ] [ + | \- ]"
.RB ( h ,
.BR z )
Prints a screenful of message headers listed in the
current folder.
If a message number is given on the command line,
the first message of the screenful of messages is
that message number.
The `z' command is identical to the \*Qh +\*U
command and remains for compatibility reasons.
The variable
.B screen
may be set to tell how many headers are in a screenful.
In the graphics tool mode, the variable
.B screen_win
contains the number of headers used in the headers subwindow.
.sp
A typical header may look like:
.sp
.ti +2
\&> 5 N argv@spam.istc.sri.com Feb 19, (10/278) Test
.sp
This line indicates that it is message number 5 and the `>'
indicates that the \*Qcurrent message pointer\*U is pointing to this
message.
The next two positions indicate the message status.
The first
may be one of, \*QN\*U (new and unread), \*QU\*U (old, but still
unread), \*Q*\*U (deleted), \*QS\*U (saved), \*QP\*U (preserved),
or \*Q \*U (read).
The second position may have an \*Qr\*U if the message
has been replied to, an \*Qf\*U if it has been forwarded,
or a \*Qp\*U if it has been printed.
.sp
The author of the example message header is
.IR argv@spam.istc.sri.com ,
the date is
.IR "Feb 19" ,
the number of lines in the message is
.IR 10 ,
the number of characters is
.I 278
and the subject of the message is
.IR Test .
The format of the message header shown here is described by
the string variable
.BR hdr_format .
The example given above has a hdr_format of
.sp
.ti +2
set hdr_format = "%25f %7d (%l/%c) %25s"
.sp
See the description of
.B hdr_format
in the VARIABLES section for more information on header formats.
.sp
You can print a special subset of message headers by using the
.I \-H:c
option, where `c' is one of:
.nf
.in +2
.ta 1i
.if t .ta 1.5i
a all messages
d deleted messages
f forwarded messages
m marked messages
n new messages
o old messages
p preserved messages
r replied to messages
s saved messages
u unread messages
.fi
.in -2
Note that the \-H is not required; \*Qheaders :c\*U is valid.
.sp
More options to the
.B headers
command include
.RI ` + '
and
.RI ` \- '.
Each prints the next or previous screenful of message headers.
The
.B z
command can also be used; `z' alone prints the next
screenful (thus, the `+' is optional)
and \*Qz \-\*U is equivalent to \*Qh \-\*U.
.sp
Headers affects all the messages it displays, so piping may be done
from the headers command.
Piping to the headers command causes the
message headers affected by the previous command to be printed.
This action is identical to piping to the
.B from
command.
.TP
.BR help " [topic]"
Help is provided on a per topic basis and on a general basis.
For general help, just typing
.I help
provides some general information as to how to get further help
and a list of topics suggested for more specific help.
There is also help provided for each command by using the \-?
option to most commands.
This option provides command line usage information as well as a
description of what the command does and how to use it.
.sp
If no help file is found, an error message is printed.
The location of the help files may be reset by setting the variables
.B cmd_help
and
.B tool_help
to the paths of the new help files.
.sp
The
.B tool_help
variable is recognized only by versions capable of using suntool mode
(tool mode need not be active).
.TP
.BR history " [\-h] [\-r] [N]"
This command displays the command history in chronological order; early
commands are printed first followed by more recent commands displayed last.
Option
.I \-h
suppresses printing of history event numbers with each history command.
Option
.I \-r
reverses the order of the history events displayed.
.sp
If a number
.I N
is given, then that number of previous commands is
echoed rather than the number set by the variable
.BR history .
.sp
See the LINE-MODE INTERFACE section for a description of referencing the
history in commands.
.TP
.BR ignore " [header-list]"
.ns
.TP
.BR unignore " [header-list]"
.rs
Display or set a list of headers to be ignored when displaying messages.
When reading messages, all the message headers are displayed with the text
body of the message.
Since these message identifier fields are cumbersome and uninteresting
in many cases, you can filter out unwanted headers by using this command.
For example,
.sp
.ti +2
ignore Received Date Message-Id
.sp
ignores the three specified fields.
Additional
.B ignore
commands are cumulative.
The command
.B unignore
is used to reverse the effects of
.BR ignore .
.sp
For another way to control this, see the variable
.BR show_hdrs .
.TP
.BR lpr " [-h] [-n] [\-Pname] [msg-list]"
Takes a message list and sends those messages, one by one, to the printer,
each separated by page feeds.
The \-h option suppresses printing of ignored headers (see the
.B ignore
command and the variables
.B show_hdrs
and
.BR alwaysignore ),
and the \-n option suppresses all headers.
A default printer name is supplied if one is not specified on the
command line
.RI (\-P printer-name ).
If you have the variable
.B printer
set, that printer name is used.
.sp
If the variable
.B print_cmd
is set, the command described by that variable is used instead
of the default system command.
In such cases, the -P option and the
.B printer
variable are ignored and the command is simply executed as is.
.sp
The \*Qprinted\*U status bit is set for each message printed by this command.
.sp
.IR Note \|:
If \*Qlpr \-Pprinter\*U produces an error message, your system administrator
may have configured
.I Mush
to require \-d in place of \-P.
.TP
.BR ls " [flags]"
This command duplicates the
.IR UNIX (TM)
command
.I /bin/ls.
By default,
.I ls
always uses the -C flag (columnate output).
.TP
.BR mail " [flags] [recipient ...]"
.RB ( m )
Send mail to a list of users.
If no recipient list is specified on the
.I Mush
command line, then a \*QTo: \*U prompt requests one.
A list of recipients must be supplied at some time before the message is
sent, but is not required to begin composing a letter.
This implementation of
.I Mush
supports mailing to files and programs as recipients.
Filenames must be full pathnames; thus, they must start with a `/' or there
is no way to know whether a recipient is a pathname or a user name.
The special characters `+' and `~' may precede pathnames since they are
expanded first to the user's folder directory (+), as described by the variable
.BR folder ,
and the user's home directory (~).
Mailing to programs is indicated by the pipe `|' character preceding the
program name.
Since the user's path is searched, full pathnames are not required for
programs that lie in the user's PATH environment variable.
.sp
Example:
.sp
.ti +2
mail username, /path/to/filename, "|program_name", +folder_name, ~user/mbox
.sp
Options are:
.nf
.in +2
.if n .ta 1.5i
.if t .ta 1.8i
\-b addr-list set list of blind carbon recipients
\-c addr-list set list of carbon copy recipients
\-E edit outgoing message headers
\-e immediately enter editor (autoedit)
\-F add random fortune to the end of message
\-f [msg-list] forward messages (not indented)
\-H file read file as prepared text (no headers)
\-h file read file as a draft (text and headers)
\-I [msg-list] include messages with headers (indented)
\-i [msg-list] include messages in letter (indented)
\-s [subject] prompt for subject [set subject explicitly]
\-U send draft immediately (use only with \-h)
\-u unsigned: no signatures or fortunes added
\-v verbose (passed to mail delivery program)
.in -2
.fi
.sp
The verbose option may not be available depending on the mail transport
agent on your system.
.sp
The \-e flag causes you to enter the editor described by the variable
.BR visual .
.sp
The \-E flag causes
.I Mush
to place the headers of the outgoing message in
the editor file so they can be changed.
See the description of the variable
.B edit_hdrs
for details.
.sp
The \-i flag includes the current message into the body of the
message you are about to send.
The included message is indented by
the string \*Q> \*U or by the string described by the variables
.BR indent_str ,
.BR pre_indent_str ,
and
.BR post_indent_str .
See the VARIABLES section for more information on these string values.
If a message list is given after the \-i option, then the messages
described by that list are included.
The \-I option is identical to the \-i option except that the headers of
the message are also included.
.sp
The \-s flag looks at the next argument and sets the subject to that
string.
If the string is to contain spaces, enclose the entire subject
in quotes.
If there is no following argument, then the subject is prompted for.
This flag is useful if the user:
.sp
.in +2
.nf
\(bu does not have the variable \fBask\fR set, or
\(bu wishes to change the subject used with \fBreply\fR
.in -2
.fi
.sp
The subject is not prompted for and is ignored completely if the \-f flag
is specified (see below).
.sp
The \-f flag is for message forwarding only.
An optional message list can be given just as the -i option has.
The forward option does not allow you to edit the message(s) being forwarded
unless the -e flag is also specified.
The subject of the message (if available) is the same as the
.I current
message; it is not necessarily the subject of the message being forwarded.
The subject of forwarded mail cannot be changed.
However, using the \-e flag
allows the user to change the subject once in editing mode either by
using the escape sequence, \*Q~s\*U, or by editing the \*QSubject:\*U header.
.sp
Forwarded mail that has not been edited by the user contains special
headers such as
.sp
.ti +2
Resent-To:
.ti +2
Resent-From:
.sp
and perhaps others, depending on your mail transport agent.
Sendmail, for example, may add a number of other \*QResent-*\*U headers.
.sp
The \-u option, meaning \*Qunsigned\*U, prevents signatures and fortunes
from being appended to the message.
It overrides the variables
.B autosign
and
.BR fortune ,
but affects the \-F option only if given after it on the command line.
.sp
The \-h option indicates that the given file is a previously prepared
message, possibly a partial one saved with \*Q~w\*U.
Such a file is called a \fIdraft\fR.
The file argument must be given, and
in the current implementation
all message headers must either be
present in the file or must be added manually by the user.
At minimum, there must be a \*QTo:\*U header;
.I Mush
adds \*QFrom:\*U and \*QDate:\*U headers when sending, if necessary.
To read a prepared text file that does not contain headers, use \-H.
If the \-U option is also given, then the letter is sent immediately without
further editing.
.sp
.TP
.BR map [ ! "] [string [expansion]]"
.ns
.TP
.BR unmap [ ! "] string"
.rs
The
.B map
command creates or lists macros for the line mode interface, and the
.B map!
command creates or lists macros for the message composition mode.
In either mode, macros act in such a way that, when
.I string
is typed, the effect is the same as if
.I expansion
had been typed instead.
The
.I string
is usually one or two control characters, or a sequence sent by
one of the \*Qfunction keys\*U of a particular terminal.
See the MACROS section for the syntax used to specify the
.I string
and the
.IR expansion ,
and for comments on the interactions of macros in the same and in
different modes.
.sp
If no arguments are given, these commands display the list of
macros and expansions for the appropriate mode.
If only a
.I string
is given, they display the
.I expansion
associated with that string for the appropriate mode.
Otherwise, they create a macro, associating the given
.I expansion
with the specified
.IR string .
.sp
Line mode macros are unset with the
.B unmap
command, and composition mode macros are unset with the
.B unmap!
command.
.TP
.BR mark " [\-[A|B|C|D|E]]"
.ns
.TP
.B unmark
This command places a tag on messages that you wish to reference later.
If a priority A through E is specified, that priority is assigned to the
message.
Message priorities are saved when the folder is updated.
The
.B sort
and
.B pick
commands can then be used to order or select messages based on their
priorities.
.sp
If no pririty is specified, the message is given a temporary mark.
Messages may have both a temporary mark and a priority,
but may not have more than one priority.
Priorities are shown by the appropriate letter code immediately following the
message number in the header display.
The presence of a temporary mark is shown by a `+' character.
Temporary marks are considered to have the highest priority for sorting and
are shown in place of the regular priority if both are set on a given message.
However, temporary marks are not saved when the folder is updated.
.sp
The command
.ti +4
headers \-H:m
(abbreviated as \*Q:m\*U) can be used to generate the list of messages
with temprary marks.
.sp
For example:
.sp
.ti +4
mark -C 7
.sp
assigns priority C to message 7. You can clear the priority of a message
by specifying a lone `\-' argument:
.sp
.ti +4
mark -
.sp
This does not remove temporary marks, only priorities.
The command
.B unmark
is used to remove temporary marks.
.TP
.BR merge " [\-N] folder-name"
Messages from the named folder are read into the current folder.
The header summaries of the merged messages are printed unless the \-N
option is given (see the
.B folder
command, above).
This command can only appear in a pipeline if it is the first command;
it returns a list of all the messages from the merged-in folder.
This command cannot be used in initialization files before the shell
has started.
.TP
.BR my_hdr " [header[: text]]"
.ns
.TP
.BR un_hdr " [header:]"
.rs
You can create personalized headers in your outgoing mail using this command.
.sp
.nf
Command usage:
.in +2
.ta 2.5i
my_hdr print all your headers
my_hdr header print value of header
my_hdr header: string set header to string
un_hdr header: unset header
.in -2
.sp
.fi
To set a header, the first argument must be a string
that contains no whitespace (spaces or tabs) and must end with
a colon (:).
The rest of the command line is taken to be the
text associated with the mail header specified.
If any quotes are used in the header and the header itself is not set in
quotes, then quotes should be escaped (preceded) by a backslash.
This holds true for semicolons, pipe characters
or any other metacharacter that
.I Mush
might interpret as a command line modifier.
.sp
If the variable
.B no_hdrs
is set, then your headers are not added to outgoing messages,
but no headers are unset.
The
.B un_hdr
command may take `*' as an argument to un_hdr everything set.
.sp
Example:
.sp
.ti +2
my_hdr Phone-Number: (415) 499-8649
.sp
.I Mush
treats the the header \*QFrom:\*U as a special case.
If you have set your own From:, a simple test is performed to determine
whether the address given is valid.
Any UUCP or domain address that directs mail to your login at the local
machine should be acceptable, but certain configurations may prevent some
combinations from being recognized.
If the address is valid, your From: header is used; otherwise, an
address known to be valid is generated and used instead.
Some mail transport agents are \*Qpicky\*U and do not allow
.I Mush
to supply a From: header; in these cases, your From: header is silently
removed at send time, and replaced with one generated by the MTA.
.sp
Note: You cannot set the \*QDate:\*U.
Attempting to do so does not result in any
error messages; your date is simply overwritten
by the system when your mail is sent.
.TP
.BR pick " [flags] [<pattern>]"
Allows the user to select particular messages from a folder.
The <pattern> is a \*Qregular expression\*U as described by
.IR ed .
You can search for messages from a user, for a particular subject line,
between certain dates, and limit searches to a range of messages.
You can also find all messages that do not
match the same arguments mentioned above.
.sp
.nf
Options:
.ta 1.5i
.in +2
+<num> keep only the first <num> messages matched (head).
\-<num> keep only the last <num> messages matched (tail).
\-ago <format> search for messages relative to today's date.
\-d [+|\-]date messages sent on or [+ after] [`\-' before] date.
\-e take all remaining arguments to be the pattern.
\-f search for pattern in \*QFrom\*U field only.
\-h header search for pattern in specified header only.
\-i ignore case of letters when searching.
\-p priority select messages with given priority (A,B,C,...)
\-r msg-list search only the listed messages.
\-s search for pattern in \*QSubject\*U field only.
\-t search for pattern in \*QTo\*U field only.
\-x select messages that do \fInot\fR match the pattern.
.in -2
.fi
.sp
The
.I \-ago
option can be abbreviated as
.IR \-a .
Only one of \-a, \-d, \-f, \-h, \-p, \-s and \-t can be specified at once,
but multiple \-p options may be specified to select several priorities.
Entire messages are scanned for the <pattern>
unless \-a, \-d, \-f, \-h, \-p, \-s or \-t is specified.
Messages marked for deletion are also searched.
No patterns can be specified with the \-a or \-d options.
The \-x option may not be used in conjunction with
.IR + n
(head) and
.IR \- n
(tail).
.sp
For the \-d option, \*Qdate\*U is of the form:
.sp
.ti +2
month/day/year
.sp
with an optional `\-' to specify that the messages of interest are those
older than that date.
Omitted fields of the date default to today's values.
Examples of selecting on date:
.nf
.in +2
.ta 2.0i
.sp
pick \-d 4/20 on April 20, this year.
pick \-d \-/2/85 on or before the 2nd, this month, 1985.
pick \-d +5/4 on or after May 4 of this year.
pick \-d / today only.
.fi
.in -2
.sp
At least one `/' char must be used in a date.
There is no strong date checking; 2/30 is considered a valid date.
.sp
For the \-ago option, the format is very simple. Specify the number of
days followed by the word \*Qdays\*U, or the number of weeks followed by
the word \*Qweeks\*U, and so on with months and years. Truncation is allowed,
since only the first character is examined, so all of the following are
equivalent:
.sp
.in +2
.nf
pick \-ago 1 day, 2 weeks
pick \-ago 2Weeks 1Day
pick \-ago 2w,1day
pick \-a 2w1d
.fi
.in -2
.sp
These examples find all messages that are exactly 2 weeks and 1 day
old. All \*Qago\*U dates collapse into \*Qday\*U time segments. This
means that months are 30.5 days long. If more precise date selection is
required, use the \-d option and specify specific dates.
.sp
Also note that the \-ago option allows
the \*Qbefore\*U (\-) and \*Qafter\*U (+)
arguments. Thus, you may pick all messages older than 1 week with:
.sp
.ti +2
pick \-ago \-1 week
.sp
Other examples of
.B pick:
.sp
.nf
.ti +2
pick \-d 2/5/86 | pick \-d \-2/5/87 | pick \-s "mail stuff" | lpr
.fi
.sp
Will find all the messages between the dates February 5, 1986, and
February 5, 1987, that contain the subject "mail stuff" and send them
to the printer.
.sp
.ti +2
pick -s Re: | delete
.sp
Deletes messages that have \*QRe:\*U in the Subject header.
.sp
.ti +2
folder +project | pick \-f frank
.sp
Finds all messages from frank in the folder described by +project.
.sp
.ti +2
pick \-h return-path ucbvax
.sp
Searches all messages that have the header "Return-Path:" and determines
if the string \*Qucbvax\*U is in the header.
Note that case sensitivity
applies only to the pattern searched, not the header itself.
.sp
.ti +2
pick \-ago +1w | save +current
.sp
This finds all messages that are a week or less old and saves them in the file
called \fIcurrent\fR, which is found in the user's \fIfolder\fR variable.
.sp
.ti +2
pick +3 mush-users
.sp
Finds the first three messages containing the string \*Qmush-users\*U.
.sp
.ti +2
eval -h "pick +2 \-r .-$ \-s %s" | pick \-1
.sp
Finds the next message with the same subject as the current message.
.TP
.BR pipe " [\-p pattern] [msg-list] unix-command"
Allows the user to send the texts of a list of messages to a
.IR UNIX (TM)
command.
The list of messages may either be given explicitly or may come from a
.I Mush
pipeline (see \*QPiping commands\*U under the LINE-MODE INTERFACE section).
If a list is neither given nor piped, the current message is used.
All headers are considered part of the message text for purposes of this
command unless the value of the variable
.B alwaysignore
includes the word \*Qpipe\*U (see
.B alwaysignore
in the VARIABLES section for more information).
For example,
.sp
.in +4
.nf
pipe 3 5 7 patch
.fi
.in -4
.sp
sends the text and headers of messages 3, 5 and 7 to the
.I patch
utility.
.sp
If a
.I pattern
is specified with the \-p option, \fIMush\fR searches
the message for a line beginning with that string.
The matching line and all succeeding lines are sent to the
.IR unix-command .
If \-p is not given, and the
.I unix-command
is omitted, \fIMush\fR searches for a line beginning with \*Q#!\*U
and feeds that line and all succeeding lines to \*Q/bin/sh\*U.
Thus,
.B pipe
with no arguments treats the current message as a shell script.
.sp
The pattern may also be of the form
.ti +4
.I /pattern1/,/pattern2/
in which case printing begins with the line containing
.I pattern1
and end with the line containing
.I pattern2
(inclusive).
Patterns of this form must still match at beginning of line, and
regular expressions are not currently allowed.
.sp
The
.B pipe
command can also be invoked as
.B Pipe
(note capitalization), in which case only the body of the messages,
and none of the message headers, are sent to the unix command.
.sp
When the variable
.B unix
is set,
.IR UNIX (TM)
commands can appear anywhere
.I except as the first command
in a
.I Mush
pipeline without explicitly using
.BR pipe .
However, it is still necessary to specify
.B Pipe
in order to exclude all headers.
.sp
.IR Note :
All messages listed as arguments to
.B pipe
or
.B Pipe
are sent to the standard input of the
.I same
process as a continuous stream, in message number order! This is probably
not desirable when extracting shell scripts in particular, so take care.
.TP
.B preserve
.RB ( pre )
When the system folder is updated, preserved messages are saved in that
folder rather than in your mbox folder.
The
.B preserve
command sets this preserved status on the listed messages unless they have
been explicitly deleted.
The variable
.B hold
causes all messages (except those saved or deleted) to be held in your
system folder automatically.
.TP
.B print
.RB ( p ,
.BR type ,
.BR t )
Takes a message list and displays each message on the user's terminal.
If the first letter of the command is a capital letter (`P' or `T')
then \*Qignored\*U headers are not ignored
.I provided
that the variable
.B alwaysignore
is either not set or is set to one of its possible values.
If this variable is set with no value, the ignored headers are
ignored regardless of the command used to display the message.
See the
.B ignore
command for more information about ignored message headers.
.sp
The `+' and the `\-' keys can be used to display the \*Qnext\*U
and \*Qprevious\*U messages respectively.
The `+' key has the caveat that the
message is not paged at all and none of the messages headers are displayed.
.TP
.B pwd
Prints the current working directory.
.TP
.B quit\ \
.RB ( q )
Updates the current folder and exits from
.IR Mush .
If the current folder is your system folder and the variable \*Qhold\*U is
set, all messages not marked for deletion are left in your system folder.
Otherwise, messages that have been read are saved to
.I ~/mbox
or to the file described by the string variable
.BR mbox .
Messages marked for deletion are discarded.
Unread messages are copied back to the current folder in all cases.
.TP
.BR reply / replyall " [msg-list] [-r path] [flags] [users]"
.RB ( r / R )
Messages are replied to by sending mail to the sender of each message
in the given message list.
The command
.B replysender
is equivalent to
.BR reply .
.B Replyall
responds to all the recipients as well as the sender of the message.
These commands understand all the same flags as the
.B mail
command.
.sp
When constructing a return mail address to the author of a message,
.B reply
searches for special mail headers in the author's message that
indicate the most efficient mail path for return mail.
.I Mush
searches for the \*QReply-To:\*U,
\*QFrom:\*U, and \*QReturn-Path:\*U headers, in that order, by default.
.sp
If none of these fields are found in the message, the first line of the
message is parsed if possible;
this \*QFrom\ \*U line is different from the \*QFrom:\ \*U line.
If the user wishes to change the order or the actual fields to search for
return paths, then the variable
.B reply_to_hdr
may be set to a list of headers to be used (in the order specified).
If it is set, but has no value, the first \*QFrom\ \*U line is used
regardless of what headers the author's message contains.
The \*QFrom\ \*U line may be specified explicitly as an item in the
list of reply-to headers by specifying the header
.RB \*Q From_ \*U.
See the VARIABLES section for more information about
.B reply_to_hdr.
.sp
When replying to all recipients of the message using the
.B replyall
.RB ( R )
command, only the original author's address can be obtained from
the message headers.
There is no way to determine the best path to the
other recipients of the message from message headers aside from taking
their addresses directly from the \*QTo:\*U and \*QCc:\*U lines.
.sp
Example:
.sp
.ti +2
replyall 3,4,5 -i 4,5 7 -s response mail-group
.sp
Here, messages 3, 4 and 5 are replied to (all the authors are obtained
from each of those messages as well as the recipients from those messages)
and the text from messages 4, 5 and 7 are included in the body of the reply.
The subject is set to "response" and the alias mail-group is appended to
the list of recipients for this message.
.sp
The -r flag prefixes the address of each recipient in the address list
with the indicated path. This overrides the value of \fBauto_route\fR,
but has the exact same functionality. See the explanation of the variable
in the VARIABLES section. Also see the MAIL ADDRESSES section for more
information concerning replying to messages.
.nf
.TP
.BR save / write / copy " [\-f] [\-s | \-a] [msg-list] [filename / directory]"
.fi
.RB ( s / w )
With no arguments,
.B save
and
.B write
saves the current message to the file
.I mbox
in the user's home directory (or the file specified by the
.B mbox
variable).
If a message list is given, then the messages specified by
the list are saved.
If a filename is given, then that filename is used instead of mbox.
The \-s option forces the filename used to be that of the subject of
the message. Similarly, the \-a option causes the filename used to be
that of the author of the message being saved. If more than one message
is being saved, the subject or author name used is that of the smallest
message number. With these two options, a directory name may be given
to specify a directory other than the current directory where the files
are to be created.
.sp
If the file exists and is writable, the specified command
appends each message to the end of the file.
If \-f is given, then the file is overwritten causing whatever contents it
contains to be lost.
For compatibility with older versions, the character `!' may be substituted
for \-f (no `\-' is used with `!').
Note that \-f has no effect when used with \-a or \-s.
.sp
If the current folder is the system mailbox, then saved messages are
marked for deletion when the user exits using the
.B quit
command.
If the variable
.I keepsave
is set or the current folder is not the system mailbox, then messages are
not marked for deletion.
.sp
The
.B write
command differs from
.B save
and
.B copy
in that the message headers are
.I not
saved in the file along with the body of text.
The
.B copy
command is is like
.B save
except that messages are never marked for deletion, whether or not
.B keepsave
is set.
.TP
.BR saveopts " [file]"
The complement of
.BR source ,
.BR saveopts ,
saves all settable variables, aliases
and cmd's in the initialization file.
(See the INITIALIZATION
section for more information on initialization files.)
If an argument is given, that file is used.
Beware that this overwrites files, so any \*Qif\*U expressions
are lost, as are settings that have changed since entering
.IR Mush .
Using saveopts is highly discouraged
and is intended for the naive user only.
.TP
.BR set " [[?]variable [= value]]"
.ns
.TP
.BR unset " variable"
.rs
With no arguments,
.B set
prints all variable values.
Otherwise, it sets the named
.IR variable .
Arguments are of the form \*Qvariable=value\*U (whitespace is allowed).
Boolean options such as
.I autoedit
need not have \*Q=value\*U associated in the command.
Multivalued variables are set in the same way as other variables, and
the list of values should be enclosed in quotes if whitespace is used
to separate the items.
See the VARIABLES section for details of the format of each type of variable.
.sp
The special command
.sp
.ti +2
set ?all
.sp
prints all known variables utilized by the program and a brief
description of what they do.
The user may set and manipulate his own set of variables, but internal
variables that are utilized by the program are the only ones displayed.
.sp
The command
.sp
.ti +2
set ?variable_name
.sp
prints the same information for one variable instead of all variables.
You may unset everything by issuing the command \*Qunset *\*U.
Note that some variables are essential to the operation of the program
and are restored to a default value even when they are explicitly unset.
.sp
It is possible to set a variable to a list of messages returned by another
command by using the piping mechanism. For example,
.sp
.ti +2
pick \-s Status Reports | set reports
.sp
The variable
.I reports
now contains a message list which can be used
as the message list argument to any command which accepts a list.
.sp
.ti +2
mail \-i $reports boss
.sp
This command sends mail to \*Qboss\*U and includes the text of all the
messages held in the \fIreports\fP variable.
.TP
.BR sh " [command]"
Invokes an interactive version of the shell.
The shell spawned is described by the variable
.BR shell .
If the optional argument
.I command
is given, then that command is executed under the Bourne Shell (/bin/sh).
If the special character `&' is at the end of any shell command,
then the command is executed in background.
.TP
.BR source " [file]"
Read
.I Mush
commands from a file.
If no filename is specified, the files searched
for are .mushrc or .mailrc in the user's home directory.
If the environment variable
.I MUSHRC
or
.I MAILRC
is set, then the file named by the variable is sourced instead.
If a filename is given on the command line, that file is sourced.
See the INITIALIZATION heading and the
.B home
variable descriptions for more information.
.TP
.BR sort " [\-i] [[\-r] \-a | \-d | \-l | \-p | \-R | \-s | \-S]"
This command sorts messages according to author, date, status or subject
(with or without considering the \*QRe:\ \*U, in replied messages).
In addition, the messages can be sorted in reverse order (same arguments).
.sp
.nf
Options:
.in +2
.ta 1i
\-i ignore case in alphabetical sorts
\-r reverse sort order of next option
\-a sort by author (alphabetical)
\-d sort by date
\-l sort by length of message
\-p sort by message priority
\-R sort by subject including \*QRe:\*U
\-s sort by subject (alphabetical)
\-S sort by message status
.in -2
.fi
.sp
By default (no arguments),
.B sort
sorts messages by
.IR status .
New, unread messages are first, followed by preserved messages,
and finally deleted messages are placed at the end of the list.
If status is otherwise the same, priority is used to order the messages.
If \-r is the only option given, the status ordering is reversed.
.sp
Sorting by priority orders marked messages first, followed by messages
having a priority setting (A having higher precedence than B, and so on),
and finally messages having neither a mark nor a priority.
See the
.B mark
command for information on attaching marks and priorities to messages.
.sp
When sorting by date, the boolean variable
.B date_received
is checked. If it is set, then sorting goes by date received.
Otherwise (default), sorting is by date sent by the original author.
.sp
If more than one sort option is specified, they are applied in
left-to-right sequence to each comparison.
Thus:
.sp
.ti +2
sort \-a \-d
.sp
sorts messages by author and, if the author of any set of messages
is the same, sorts within that set by date.
Note that the \-r option applies to only one other option at a time;
to reverse the sort of both author and date requires:
.sp
.ti +2
sort \-r \-a \-r \-d
.sp
The options can also be grouped:
.sp
.ti +2
sort \-ra \-rd
.ti +2
sort \-rard
.sp
Currently, only the line mode interface supports multiple sort criteria,
but the other interfaces allow subsorting indirectly
when appropriate actions are taken, as discussed below.
.sp
It is also possible to sort a consecutive sublist of messages by using pipes.
If the mailbox is already sorted by author,
.sp
.ti +2
pick \-f argv@zipcode.com | sort \-s
.sp
finds all messages from the user \*Qargv@zipcode.com\*U
and sort them by subject.
You may specify the exact message list by specifying
that message list on the command line and using a pipe:
.sp
.ti +2
10\-. | sort d
.sp
This command means to sort the messages from 10 to the current message
according to the date.
.sp
To specify subsorting from with the curses interface, the temporary
curses escape key must be used (the colon `:') and the command issued
at the `:' prompt (as if giving an \*Qex\*U command to \*Qvi\*U).
When the command is finished, the \*Q...continue...\*U prompt is given and
the user may continue or return to the top level of the curses mode.
.sp
In the tool mode, subsorting can be specified only by typing message numbers
in the \*QRange:\*U item at the top of the main frame, before selecting the
\*QSort\*U item.
The sort range must consist of consecutive messages.
Reversed sorting is not currently available in tool mode.
.sp
If the variable
.I sort
is set, messages are sorted each time the user's system mailbox is
read as the current folder.
The
.I sort
variable can be set either to nothing or to legal "sort" arguments.
.sp
\fINote\fR: For compatibility with older versions, sort options are
recognized even if they are not preceded by a `\-'.
Also, if a `\-' is given by itself (separated by spaces from any following
arguments) it is interpreted as \-r.
.TP
.B stop\ \
For systems with job control, stop causes
.I Mush
to send a SIGTSTP to itself.
The command was introduced to facilitate
the stop-job action from a complex command line alias rather than the user
having to type his stop character explicitly.
.TP
.B top
Takes a message list and prints the top few lines of each.
The number of lines printed is controlled by the variable
.B toplines
and defaults to the size of the value of the variable
.B crt.
This command is ignored in the tool mode.
.TP
.BR undigest " [-m] [-p pattern] [msg-list] [filename]"
A \*Qdigest\*U is a mail message which is a collection of other mail messages
mailed to a \*Qmoderator\*U by other users. The moderator compiles all the
messages into a folder and sends the result to all the subscribers of the
mailing list. The
.B undigest
command disassembles the entries into the set of messages which comprises
the digest.
.sp
The -m option merges these messages into the current folder. Otherwise,
if a filename is specified, a new folder is created and the user can change
folders to read the messages separately.
.sp
The -p option specifies an alternate pattern to be used as the digest
article separator.
This pattern must match literally at the beginning of the line.
The default pattern is \*Q\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\*U (eight hyphens).
This is the defacto USENET standard digest article separator and should
work for most digests, but some use another separator.
The -p option is also useful for \*Qbursting\*U forwarded messages out
of a wrapper message; for example:
.sp
.ti +4
undigest -m -p "--- Forward"
.sp
bursts out messages forwarded by another user of
.I Mush
and merges them into the current folder.
.sp
If a message list is specified, each digest in the list is disassembled to
the same filename (if given).
If no filename is given and the user did not request
a merge, then a temporary file is made.
The name of the temporary file is generated from the subject of the digest.
.TP
.BR update " [-r]"
Updates your current folder, writing back changes just as if you had
.BR quit ,
except that the `N'ew status does not change to `U'nread.
Headers are not listed when the folder is read back in.
The \-r option puts the folder into read-only mode
.I after
updating it.
.sp
See the
.BR folder
command for complete information.
.sp
.SH VARIABLES
Shell variables are controlled via the
.B set
and
.B unset
commands.
Options may be either boolean, in which case it is only
significant to see whether or not they are set;
string, in which case the actual value is of interest;
numerical, in which case the numerical value is important;
or multivalued, in which case they may be set to a list of values.
Some variables may have attributes
of boolean and string or multivalued at the same time.
.PP
If you or the program references a variable that is not explicitly set,
then the environment variables are checked and that data is returned.
A few variables (notably
.BR prompt ,
.BR cmd_help ,
and
.BR tool_help )
do not check the environment.
.PP
Variable values can be modified by one of four variable modifiers, or by a
numeric string.
The modifiers `:h', `:t', `:l' and `:u' may be applied to the variable names.
The current implementation allows only one `:' modifier on each `$' expansion.
.TP
:t
The variable is treated as a file path name, and the name of the file
(the \*Qtail\*U of the path) is substituted for the variable.
That is, everything to the right of the last `/'
is returned.
.TP
:h
The variable is treated as a path name, and the \*Qhead\*U of the pathname
is substituted for the variable.
That is, everything up to, but not including, the last `/' is returned.
.TP
:l
All alphabetic characters in the variable's value are converted to lower case.
.TP
:u
All alphabetic characters in the variable's value are converted to upper case.
.TP
.RI : number
The value of the variable is converted to a list of space-separated words,
which are numbered from one (1), and the word described by
.I number
is selected and returned.
It is not an error for
.I number
to be greater than the actual number of words; an empty string is returned
in this case.
.PP
Following is a list of all variables with predefined meanings.
.TP
.B alwaysignore
(Boolean/Multivalued)
If set with no value, the mail headers set by the
.B ignore
command are always ignored.
Normally, ignored headers are not ignored when sending messages to
the printer, when interpolating messages into letters with ~f or ~I,
when the `P' or `T' command is given (see the \fBprint\f command),
or with the \-I flag to the
.B mail
or
.B reply
commands.
Setting
.B alwaysignore
ignores those headers even in the situations mentioned here.
No headers can be ignored during updates and when using the
.B save
command since the user may ignore headers that are required by
.I Mush
or any other mail system to read those folders.
.sp
This variable can also be set to a list of words
separated by commas or spaces.
Currently recognized words, and their meanings, are:
.nf
.ta 1.5i
.in +4
.\" \& escapes are to make obvious the tab after each word
forward\& Ignore headers when forwarding messages (~f).
include\& Ignore headers when including messages (~I).
pipe\&\& The \fBpipe\fR command ignores headers.
printer\& The \fBlpr\fR command ignores headers.
.in -4
.fi
.sp
Also see the
.B ignore
command and the
.B show_hdrs
variable for more information.
.TP
.B ask
(Boolean)
If set, you are prompted for a subject header for outgoing mail.
Use the tilde escape \*Q~s\*U to set the header once in the message
or specify the \-s option on the
.B mail
command line at the
.I Mush
prompt.
.TP
.B askcc
(Boolean)
If set, you are prompted for a Cc (carbon copy) list when you are
finished editing a letter to be sent.
If the variable
.B edit_hdrs
is set, prompting does not occur, but a Cc: line is added to the
edit file.
This also applies to the tool mode.
.TP
.B autodelete
(Boolean)
When exiting mail, all messages that have been read
.I "regardless of whether they have been marked for deletion"
are removed.
Only messages that haven't been read or that have been marked as
.B preserved
are not removed.
.TP
.B autoedit
(Boolean)
If set, you are automatically put into your editor whenever you
send or reply to mail.
.TP
.B autoinclude
(Boolean)
When replying to any mail, a copy of the message being replied to
is automatically inserted into your message body indented by
the string described by the variable
.BR indent_str .
.TP
.B autoprint
(Boolean)
After you delete a message, the next message is printed automatically.
.TP
.B auto_route
(Boolean/String)
If set boolean (not to a string), all the recipients in a message that
is being replied to (via \fBreplyall\fR), is routed through the path
back to the original author.
.sp
For example, if the original sender of a message came from the remote host
.B c3p0
and the list of recipients looked like
.sp
.nf
.in +2
XFrom: c3p0!user1
To: yourhost!you
Cc: r2d2!user2, r2d2!user3
.in -2
.fi
.sp
then clearly, \*Quser1\*U on the machine c3p0 can talk to your machine
and the machine named r2d2.
However, you would not be able to respond to those users if your machine
did not exchange UUCP mail with the host r2d2.
.sp
.I Mush
attempts to solve this problem by reconstructing the addresses
for \*Quser2\*U and \*Quser3\*U according to the address of the original
sender, \*Qc3p0\*U.
The new addresses for \*Quser2\*U and \*Quser3\*U should therefore become
.sp
.ti +2
c3p0!r2d2!user2, c3p0!r2d2!user3.
.sp
If your machine not only talks to c3p0,
but talks to r2d2 as well, it becomes unnecessary to route the mail
through both c3p0 and r2d2.
So, the variable
.B known_hosts
may be set to a list of hosts which you know your machine to have
UUCP mail connections with.
This list is checked when constructing mail addresses for replies only and
the shortest path is made by removing from the UUCP path those hosts
that do not need to be called or are redundant.
See the entry for
.B known_hosts
for more information.
.sp
If
.B auto_route
is set to a specific \fBpathname\fR (host names separated by !'s),
all addresses in the reply have this route prepended to their addresses.
This ignores the original path of the author. This is quite useful for
hosts which talk uucp to a node which is connected to the internet or uunet
since both of those machines tend to be one-hop away from all other hosts
(or reroute accordingly). For example, if a message was addressed like so:
.sp
.in +2
.nf
To: root@ucbvax.berkeley.edu, argv@zipcode.uucp
Cc: ucbcad!foo!bar
.sp
.fi
.in -2
If auto_route is set to "ucbcad", then replies to this address are
directed addressed like so:
.sp
.in +2
.nf
To: ucbcad!ucbvax.berkeley.edu!root, ucbcad!zipcode.uucp!argv
Cc: ucbcad!foo!bar
.sp
.fi
.in -2
.sp
This assumes that the host in question talks uucp with ucbcad. This example
demonstrates several things. First, notice that all addresses are converted
to uucp-style format. Whenever routing is changed, the format is converted
like this. Secondly, note that the Cc: line did not change. This is because
all redundant hostnames from UUCP pathnames are removed
to avoid unnecessary UUCP connections and speed up mail delivery.
.sp
Another example of how auto_route truncates UUCP paths:
.sp
.ti +2
pixar!island!sun!island!argv
.sp
Here, mail was probably originally sent to users at pixar and sun from
somewhere undetermined now.
Since sun and pixar do not talk to each other, the users on those machines may
have responded to mail creating the type of addresses stated above.
Here, it can be seen that we can reduce the path to the host
.IR island :
.sp
.ti +2
pixar!island!argv
.sp
See the MAIL ADDRESSES section for more detailed information
about legal mail addresses.
.sp
Note that the -r flag to \fBreply\fR and \fRreplyall\fR overrides the
value of \fBauto_route\fR.
.TP
.B autosign
(Boolean/string)
Append a signature to outgoing mail.
If this variable is set, but not to a string (e.g., boolean-true)
then the file ~/.signature is used.
.sp
Otherwise, the variable is interpreted in one of four ways.
By default, the string is interpreted as a pathname relative to the
.I current
directory.
For this reason, it is advisable to use full pathnames here.
As usual, the special characters `~' and `+' are expanded.
If a file is found, it is opened and its contents are read into the
message buffer.
.sp
If the variable is set to a string that begins with `$', then that string
is interpreted as a user-definable variable and is expanded and appended
to the letter.
.sp
If the variable is set to a string that begins with a backslash (\\)
then the string itself (minus the `\\' character) is used; no expansion
is done and no files are read.
.sp
Finally, if the variable is set to a string that begins with a vertical
bar (or \*Qpipe\*U) character (|), the rest of the string is interpreted
as a command whose output is used as the signature.
The special characters `~' and `+' are NOT expanded in the command name,
but the command is run via /bin/sh so $PATH is searched and redirection
can be specified.
The list of addresses to which the letter is sent is passed to
the command as its arguments, in the same form that they are passed
to the Mail Transport Agent (MTA).
Depending on your MTA, each address may be followed by a comma.
.sp
In the latter three cases, it is advisable to set the variable using single
quotes to protect the `$', `\\' and `|' characters from being interpreted.
Examples:
.sp
.nf
.ti +2
set autosign = '$foo'
.ti +2
set autosign = '\\ Dan Heller zipcode!argv@ucbcad.berkeley.edu'
SHAR_EOF
true || echo 'restore of mush.1 failed'
fi
echo 'End of part 16'
echo 'File mush.1 is continued in part 17'
echo 17 > _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.