Usenet 1994 October/usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso/misc/volume18/mush/part17

Internet Message Format | 1991-04-22 | 50.4 KB

From: [e-mail] (Dan Heller)
Newsgroups: comp.sources.misc
Subject: v18i074:  mush - Mail User's Shell, Part17/22
Message-ID: <[e-mail]>
Date: 22 Apr 91 15:33:52 GMT
Approved: [e-mail]
X-Checksum-Snefru: a63000e5 b49b1ec7 b1396970 25963bd6

Submitted-by: Dan Heller <[e-mail]>
Posting-number: Volume 18, Issue 74
Archive-name: mush/part17
Supersedes: mush: Volume 12, Issue 28-47

#!/bin/sh
# this is Part.17 (part 17 of a multipart archive)
# 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" != 17; 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' &&
.\" Need a pipe example?
.fi
.sp
.BR Warning :
if redirection from the calling shell is used,
no signature or fortune is added to outgoing mail.
For example,
.sp
.ti +2
% mush \-s report manager < report_file
.sp
In this command, mail is being sent to the user \*Qmanager\*U and the
subject is set to \*Qreport\*U and the file \*Qreport_file\*U is being
redirected as input.
In this case, \fIno\fR signature is appended.
.sp
.IR Note :
The `|' syntax for calling a program to sign the letter is a little
counterintuitive and may change in future releases.
.TP
.B autosign2
(String)
This alternate signature is available for special cases where the default
signature is not desired or if no signature is desired for special addresses
or if only special addresses require a signature.
The format for this variable is:
.sp
.ti +2
autosign2 = \*Qaddress1, address2, ... : <signature>\*U
.sp
Each address can be one of these types:
.RS
.TP
1)  address
Legal mailing addresses that do not contain comment
fields (see the sections MAIL ADDRESSES for more information on legitimate
mail addresses) match literally.
.TP
2)  *username
If the username is present on the recipient list, regardless of what
remote site the user may reside on (including locally), the pattern matches.
.TP
3)  !hostname !host1!host2...
Any user who appears as a recipient matches the pattern provided he
resides on the specified hostname.
If a path of hosts is specified, then the user must reside on the last
host of the specified path.
.\" Nroff note: there is a problem with the @sub.domain line,
.\" because .TP uses @ as a delimiter for width computations.
.\" The .br manages to deal with this in this special case.
.TP
4)  @sub.domain
.br
The user must reside on any host within the domain specified.
Neither the user or the hostname needs to match; only the domain name must
be required to match.
.RE
.\" Nroff note: RE takes us all the way out of TP, so step back in again.
.RS
.sp
Example:
.sp
.nf
.ti +2
set autosign2 = \*Q!zipcode @sun.com @mit.edu *schaefer root: \--dan\*U
.fi
.sp
This means that any mail sent to 1) anyone at zipcode, 2) anyone within
the sun domain, 3) anyone within the mit domain, 4) Bart Schaefer
(at any host anywhere -- even locally),
and 4) root on the local machine only (or, root@local-machine-name)
is signed with the \*Qalternate\*U signature.
If any address on the
recipient list fails to satisfy these four matches, the mail is
signed by my regular signature.
.sp
One can have a local signature and a remote signature by specifying
the autosign2 to include the hostname of the home machine the user
is logged into.  Note the \*Qzipcode\*U example above.
.sp
The list of recipients, after alias expansion and comment removal, is
then scanned and the following patterns are matched against those addresses
specified in the autosign2 or fortunates variable according to these rules.
.sp
The signature description is the same as described by
.B autosign
variable.  The colon (:) separates the list of addresses from the signature
description.  If there is no colon or the address list is missing, the
entire string is considered the signature (except for the colon).
.sp
If
.B autosign
is not set, then autosign2 works ONLY if the tilde command \*Q~S\*U
is specified.  In this way, a user may never have autosign set and just
set autosign2 to be some signature value.  The user may then issue the
tilde command to automatically sign the letter.
If a list of addresses is given (terminated by a colon), then all
recipients of the message must be in the list of addresses in autosign2;
otherwise, the signature in \fBautosign\fR (if set) is used instead.
A null signature in autosign2 does not sign the letter.
.sp
Example:
.sp
.nf
.ti +2
set autosign2 = "fred, barney, wilma, betty: ~/flintstone.sig"
.fi
.sp
If a message is sent to:
.sp
.ti +2
To: fred, wilma
.sp
Then the file ~/flintstone.sig is used.
However, if the address are:
.sp
.ti +2
To: barney, betty, bambam
.sp
Then autosign2 is not used because bambam is not in the list.
.sp
Note that mail sent via redirection from the calling shell does not
sign letters or append fortunes.
.RE
.TP
.B cdpath
(String)
Set to a string of pathnames separated by spaces to use when searching
for a directory when the
.B cd
command is issued.
The current directory is always checked before any directory in
.BR cdpath .
.TP
.B cmd_help
(String)
This variable gives the path name of the general help file, which is read
by the
.B help
command.
This variable is normally reset only in the system initialization files,
when the default location of the help file has changed.
.TP
.B complete
(String)
Setting this variable enables word completion.
The first character of the value of
.B complete
is used as the
.IR "completion character" ;
if
.B complete
is set, but not to a value, the escape character is used as the default.
When the completion character is typed at the end of a word prefix,
.I Mush
interactively completes that word.
If the prefix is not unique, the word is completed as far as possible
and a bell sounds (see, however, the variable
.BR quiet ).
If the word contains filename metacharacters,
.IR "all possible matches are completed" .
If the list overflows the command line buffer, it gets truncated, so
this feature should be used with care.
Metacharacters recognized are the same as in
.IR csh .
.sp
The second character of the value of
.B complete
is used as the completion listing character.
When this character is typed, the possible completions are printed, and
.I Mush
prompts again with the original prefix.
If
.B complete
is set to only a single character, completion listing is disabled;
if it is set with no value, control-D (^D) is used as the default
listing character.
.sp
If the first and second characters of
.B complete
are the same character, then
.I Mush
completes unique matches as usual
However, partial matches produce a listing
of the possible completions before completing as far as possible.
This can become rather verbose.
See the description of the variable
.B fignore
for ways to exclude filenames from completions.
.sp
Word completion is currently supported only for file names.
Command name and alias completion may be added in a future version.
Completion is not possible if the \-e (\-echo) flag was given.
Tool mode does not check the value of
.BR complete ,
but instead provides simple completion only, using the ESC key.
.TP
.B compose_icon
(Boolean/String)
Set to a pathname for an alternate icon pixmap to use when the
.I Mush
message composition window is closed.
If this variable is set but does not have a value, a default icon is used.
If this variable is not set, the composition window is hidden when it
is not open, and no icon appears.
The \*QCompose\*U button is used to re-open the window in this case.
.TP
.B crt
(Numeric)
Set to a value that describes the number of lines a message
must have before invoking the
.B pager
to view a message.
.TP
.B crt_win
(Numeric)
Set to the height (in lines) of the message display window in tool mode.
Resetting this variable after the program is running will not change
the height of the display, and may confuse other operations.
.TP
.B curses_help
(String)
This variable may be set to a space-separated list of curses mode command
names (see the CURSES section for the possible choices).
If set but without a value, a default list established by your
.I Mush
maintainer is used.
When it is set, a display of the current bindings for the listed commands
appears at the bottom of the screen in curses mode.
This help display normally shortens the display of headers, but the
user may explicitly scroll over the help display if he wishes to see
more headers.
.TP
.B cwd
(String)
The
.B "current working directory"
string is automatically set upon startup of
.I Mush
and is reset each time the commands
.B cd
and
.B pwd
are called.
It may be changed like any other shell variable, but this is not recommended.
.TP
.B date_received
(Boolean)
When message headers are printed, the date normally shown is
the time and date the sender sent the message.  If this variable
is set, then the date displayed is the date received.
.sp
When sorting messages by date, this variable is queried to determine
whether the messages should be sorted by date sent or date received.
.sp
\fBWarning:\fR For mailers that store messages \fIwithout\fR a line
that starts with \*QFrom \*U, this option does nothing.
.TP
.B dead\ \
(String)
File to use instead of dead.letter when interrupted mail is saved.
May be set to a \fIunix\fR command by prefixing the value with `|'.
For more information, see the variable
.B nosave.
.TP
.B domain_route
(Boolean/String)
In combination with
.BR auto_route ,
this variable specifies that addresses containing a fully-qualified domain
should be short-circuited to mail directly to the rightmost fully-qualified
domain.
If set boolean (not to a string), only short-circuiting is done.
If set to a string, the address is rewritten to UUCP form and the value
of the variable is prepended.
Domain short-circuiting applies \fIonly\fR to addresses containing a
fully-qualified domain, but short-circuits in spite of any path specified
with the \-r flag of
.B reply
or through the string value of
.B auto_route
(thus possibly omitting the auto_route or \-r paths altogether).
See
.B auto_route
for more information.
.TP
.B dot
(Boolean)
Causes
.I Mush
to accept a `.' on a line by itself,
in addition to `^D', to terminate messages.
.TP
.B editor
(String)
Specifies the editor to use when the \*Q~e\*U escape or the
.B edit
command is used.
Default is the value of the environment string EDITOR or the variable
.BR visual .
.TP
.B edit_hdrs
(Boolean)
When in letter-composition mode (via \fBmail\fR or \fBreply\fR, etc),
the headers of the outgoing message are stored in the same buffer as
the text of the letter.
So, if the editor is called to edit the message
buffer, the headers of the message can be edited as well.
However, there are some restrictions.
.sp
There must be a To: header.
Without this,
.I Mush
does not deliver the letter.
Instead, the editor must be reentered and a To: header with
a valid recipient must be inserted.
A valid Cc: header does not remove this restriction.
You may have as many To: and Cc: headers as you like.
.sp
The From: header normally should not be changed.
If you change this header to an address that
.I Mush
is unable to identify as
authentic, the original From: header is silently put back.
.sp
The Date: header is always replaced by one with a more accurate
time and date stamp.
Therefore, changing or removing this header has no effect.
.sp
You cannot add a Status: header, and blank headers are dropped.
For example, if an empty Cc: header exists, the header does
not show up in the outgoing message.
Therefore, leaving empty headers has no effect.
.sp
Aliases specified on the command line are expanded and put into the
message buffer in their expanded form regardless of the value of
.B no_expand.
However, if the user changes the headers using the editor and specifies
aliases, those aliases are not expanded if
.B no_expand
is set.
Otherwise, they are expanded as usual.
.sp
The headers Bcc: and Fcc: are removed as expected.
.sp
One added side effect of
.B edit_hdrs
is that you can add an Fcc: header to specify a \*QFile Carbon Copy\*U.
This must be a pathname to a file or program.
For programs, the pathname must be preceded by a pipe character (|).
Note that \fIall\fR addresses on the Fcc: line that do not begin with `|'
are interpreted as file names; don't put other kinds of addresses there.
.sp
When using
.B edit_hdrs,
certain tilde escapes don't work.
Specifically, any tilde escape that allows you to add or set headers or to
empty the file are inactive.
These functions are to be done in the editor only.
.sp
Once a letter is being edited,
.B edit_hdrs
cannot be set or unset; the user must end the letter (either
by sending it or forcefully terminating it) first.
.sp
Header editing is required (and happens automatically) when using the
\*QCompose\*U tool mode item.
.TP
.B escape
(Character)
When composing a mail message (not in an editor), and the
.B escape
character is the first character on the line, the next character
is examined and a corresponding function associated with that
.I "escape command"
is executed.
See
.B "tilde escapes"
for more information.
.TP
.B fignore
(String)
This variable is tested when filename completion is used (see the variable
.B complete
for details).
The value of
.B fignore
may be a list of filename extensions (\*Q.c\*U, \*Q.o\*Q, etc.), a list
of filename patterns containing metacharacters (*?{}[]), or a mixture of
the two.
Each element in the list must be separated from the others by a space.
When a filename completion occurs, any filenames with the extensions
listed in
.BR fignore ,
or matching the patterns given there, are omitted from the completion.
.sp
For example,
.sp
.ti +4
set fignore = ".o .s [Mm]ake*"
.sp
causes any filename ending in \*Q.o\*U or \*Q.s\*U, and any filename
beginning with \*QMake\*U or \*Qmake\*U, to be excluded from completions.
.sp
If all files in the current directory match the extensions or patterns,
.B fignore
is disabled and completion occurs.
For this reason, it is usually not a good idea to include \*Q*\*U in the list.
.TP
.B folder
(String)
The folder variable is set to the path of a directory where folders are kept.
This path is used by various commands to expand the `+' metacharacter (see
the
.B folder
command for details).
\*Q~/Mail\*U is the default expansion of `+'.
.TP
.B fortune
(Boolean/string)
If fortune is set, a random fortune is appended to the end of
all outgoing mail using the
.IR UNIX (TM)
command
.B /usr/games/fortune
(may vary from system to system).
If fortune is set to something that starts with
a `\-', then it is interpreted as a flag to fortune (e.g., \*Q\-o\*U).
If
.B fortune
starts with a `/', then the program described by
the string is executed (thus not doing fortune at all, if you want).
By default,
.I "fortune \-s"
(short fortunes) is used.
.TP
.B fortunates
(String)
When fortunes are added to messages, sometimes it is desirable to
make sure that only a selected group of people get a fortune since
certain people may not understand the messages at the end of your
mail.  Therefore, you can set a list of addresses (either pure addresses
or aliases that are expanded to addresses) to be the only people who
receive fortunes if one is to be appended.  Therefore,
if the To: and Cc: lines contain only address listed in this string
variable, then a fortune is appended to the message.
If those lists contain names that are not on the fortunates
list, then no fortune is added.
This cannot be overridden; using the
tilde command \*Q~F\*U does not force a fortune to be added unless the
individuals on the recipient list are all included in the fortunates
list.  The list is made up of addresses or aliases separated by spaces or
commas.
.I "NOTE: fortune must be set in order for fortunates to work."
.TP
.B hangup
(Boolean)
If this variable is set,
.I Mush
updates your folder before exiting when it receives a SIGHUP signal.
This is useful if you frequently read mail when dialed in over a noisy phone
line that often drops carrier.
.sp
.IR WARNING \|:
Certain errors are ignored during this update, because it is presumed to be
impossible to query the user for instructions.
Except in the event of a write error, the folder is forced to contain
exactly those messages that were not deleted at the time of the hangup.
In particular, this means that if an error occurs when loading new mail before
the update, the new mail is lost.
Write errors still cause both the working tempfile and as much of the
folder as possible to be preserved.
.TP
.B hdr_format
(String)
This variable controls the format of the headers displayed by the
.B headers
command and in the curses and tool modes.
The format style of this variable string is similar to printf in C.
When printing the information, the variable is evaluated and each
character in the string is echoed unless a `%' character is
encountered.
If one is found, the following string substitutions are made:
.sp
.in +2
.nf
.ta 0.5i
%a    address of the author
%c    number of characters (bytes) in the message
%f    entire \*QFrom:\*U field (author)
%l    number of lines in the message
%i    the message-id (may not be present)
%n    name of the author
%s    subject of the message
%t    \*QTo:\*U field (recipients)
%u    user name (login) of the author
%d    date and time of the message
%T    time only of the message
%N    day number of the month of the message
%W    day of the week (Sun, Mon, etc.)
%M    month name of the message
%Y    year of the message
%y    last two digits of %Y
%Z    time zone of the message
\\n    a newline
\\t    a tab
.fi
.in -2
.sp
A field width specifier may be used in all options.
Thus, \*Q%20f\*U prints the first 20 characters of the from line.
No matter what the formatting string, the message number is printed,
possibly preceded by a `>' (for current message).
.sp
The \*Qaddress\*U and \*Qname\*U of the author
are extracted from the \*QFrom:\*U field of the message.
The name may be given in parentheses and
the rest of the line is the address, or the address is given in angle
brackets (`<' and `>') and the rest of the line is the name.
Sometimes the address is the only thing on the line,
in which case the name and address are the same.
.sp
A special format is also provided to obtain the contents of any header
not listed above.
If a format of the form \*Q%?header-name?\*U (both leading and following `?'
characters are required) appears in the value of
.BR hdr_format ,
the named header is looked up.
For example,
.sp
.ti +4
set hdr_format = "%a %n %?phone?"
.sp
causes the electronic address, name, and (if a \*QPhone:\*U header is present)
phone number of the sender to be displayed.
.TP
.B history
(Numeric)
This variable is set to the number of commands the shell interface
remembers.  It is just like the history variable used in
.I csh.
If unset, the last command can always be referenced, but none other.
.TP
.B hold\ \
(Boolean)
Normally, when updating the system folder, read messages are saved in
your mbox (except those marked as preserved).
Setting
.B hold
prevents this from happening, and messages remain in the sytem folder
(usually /usr/spool/mail/username or /usr/mail/username).
This does not apply to folders other than the system folder, obviously.
.TP
.B home\ \
(String)
This variable describes the user's home directory.
The variable is initialized to the value of the environment variable HOME,
but can be modified at any time during the
.I Mush
session.
The home directory is the same directory where temporary
files are kept for editing and so forth.
If the home directory cannot be found or read/write access is denied, an
alternate directory, typically /tmp, is used.
.TP
.B hostname
(String)
This is the name of your computer.
It is used to compose a correct \*QFrom:\*U line for use with Mail Transport
Agents that do not create this header automatically.
This aids the recipients of your mail in replying to your messages.
The hostname is also used in auto-routing.
.sp
Note: the user should not have to set
this variable since it should be set automatically by the system.  However,
it may happen that the system's hostname cannot be queried and the user may
have to set this variable manually.
.TP
.B ignore_bang
(Boolean)
If set,
.I Mush
ignores the `!' character as a history reference.
Note that this severely limits use of the
.B cmd
facility, which depends upon history references for argument substitutions.
.TP
.B ignoreeof
(Boolean/string)
If set, `^D' does not cause an exit from
.IR Mush .
If set to a string, that string is executed as a command
when `^D' is typed.
This does not effect termination of messages under the
.B mail
and
.B reply
commands.
.TP
.B indent_str
(String)
When including messages into the text of a letter you are editing,
each line of the messages is preceded by the value of
.BR indent_str .
The value may contain formatting characters as described for
.BR hdr_format ,
which are expanded from the headers of the message that is being indented.
If it is unset, the message body is indented by the string \*Q> \*U.
See also the variables
.B pre_indent_str
and
.BR post_indent_str .
.TP
.B in_reply_to
(String)
This variable may be set to a string that completes the
header \*QIn-Reply-To:\*U.
The format of this string is identical to the options for the variable
.BR hdr_format .
.sp
For example, if the user responds to a message
from Dan Heller that was sent on October 21, 1987, at 10:39pm, with
.B in_reply_to
set to the string
.nf
.in +2
.sp
%n's message as of %d.
.sp
.ti -2
the header line
.sp
In-Reply-To: Dan Heller's message as of Oct 21, 1987, 10:39pm.
.in-2
.fi
.sp
is added to the message.
.TP
.B keepsave
(Boolean)
If set, the commands
.B save
and
.B write
do
.I not
mark messages for deletion.
.TP
.B known_hosts
(String)
Used in conjunction with the variable
.BR auto_route ,
this variable is set to a list of hosts, separated by spaces, tabs,
and/or commas, and describes
the hosts with whom you know your machine shares UUCP connections.
When replying to mail, the return path constructed will often have hostnames
that your site could contact directly, but instead
the mail is routed through a number of different machines first.
.sp
For example, if you respond to mail that contains the path
.sp
.ti +2
unicom!pixar!root
.sp
but your know your machine already calls pixar, then sending the mail
to unicom first is unnecessary.
If you have set your known_hosts string to include pixar in its list,
the resulting address looks like
.sp
.ti +2
pixar!root
.sp
Also see the command
.B replyall
for more information on constructing correct return addresses.
.TP
.B logfile
(String)
Set to a filename which logs the headers of outgoing messages.  The message
body of the message is not logged, unlike the copy stored in the
.B record
filename.
The logfile can be read as a folder to scan for the fact that
messages have been sent.
If \fBlogfile\fR and \fBrecord\fR are both set,
then the logfile and the record files match closely.
In this case, the record file can be quickly scanned by scanning the log
file instead.
.sp
If set, but not to a string, the log file defaults to ~/mail.log.
.TP
.B mail_icon
(String)
Set to a pathname for an alternate icon pixmap to use when the
.I Mush
tool is closed.
The number of messages in the mailbox is displayed as an icon label unless
the string
.I iconlabel
appears as one of the values of the variable
.BR quiet .
See also the variable
.B newmail_icon
for the icon displayed when new mail arrives or is present.
.TP
.B mbox\ \
(String)
Set to the pathname of a file
.I Mush
should use as the default folder for read mail.
When
.B mbox
is not set, \*Q~/mbox\*U is used.
.TP
.B metoo
(Boolean)
When replying to mail, you are normally deleted from the list of
recipients.
If metoo is set, you remain on the list.
See the
.B alternates
command for information on how
.I Mush
determines whether you are on the list.
.TP
.B mil_time
(Boolean)
Whenever the time is displayed in a message header or in the prompt,
it can be displayed in either 12-hour am/pm format, or in 24 hour
military time format.
The default is the 12 hour format, but can be
reset to use the 24 hour format by setting this variable.
.TP
.B msg_win
(Numeric)
Set to the height (in lines) of the message composition (editing) window in
tool mode.
.TP
.B newline
(Boolean/string)
When set, an empty command (carriage return with no text) typed at the
line-mode prompt is ignored.
If set to a string, that string is executed as a command when a
carriage return is typed.
Otherwise, carriage return acts as an implicit
.B next
command, and prints the next undeleted message.
.TP
.B newmail_icon
(String)
Set to a pathname for an alternate icon pixmap to use
when new mail is available.
.TP
.B no_expand
(Boolean)
When a
.I Mush
alias is used to reference a list of addresses, the list is expanded on
the To: and Cc: lines to indicate the complete list of all the recipients of
the message.
When no_expand is set, aliases are not expanded and the headers
reflect the same information as typed by the user.
.TP
.B no_hdrs
(Boolean)
If set, this variable tells
.I Mush
not to include your personalized mail headers in messages.
This does not unset your headers, it just disables them.
.TP
.B no_reverse
(Boolean)
In curses mode and in the tool mode, reverse video is not used to indicate the
.I "current message"
if this variable is set.
In the tool mode, if reverse video is not in use,
text is displayed in \*Qbold\*U.
.TP
.B nonobang
(Boolean)
If this variable is set, history references that don't match anything
are left unexpanded, rather than generating error messages.
This is useful if you want argument referencing in
.B cmd
expansions, but do
not want to remember to escape every `!' you type in UUCP addresses.
It is also recommended for use with curses mode, because history is not
kept for line mode escapes from that interface.
.TP
.B nosave
(Boolean)
When composing a letter, the user can terminate the letter without sending
it by using the tilde escape \*Q~q\*U or by sending two \*Qinterrupt\*U
signals.
When the message is terminated, a copy of it is saved to the
file \*Qdead.letter\*U in the user's home directory or to the file described
by the variable
.BR dead .
If the variable
.B nosave
is set, then a backup copy of the message is not saved.
.TP
.B output
(Read-only string)
This variable holds a message list representing the output of the last
successful command.
This is useful for recovering from broken pipes or to capture the output
of a command without affecting the information it displays (some commands
limit or suppress output when used in a pipeline).
Commands which return an error status (see the variable
.BR status )
do not affect the value of
.BR output ,
but successful commands that return no message list clear it.
Also, many curses mode commands return an error status to indicate that
the display has been altered, even if no actual error occurred.
This variable is thus most useful in line mode and in scripts.
.TP
.B pager
(String)
If a message is longer than the number of lines that the variable
.B crt
is set to, then this program is executed to view a message.
If the user does not have this variable set, the user's environment PAGER
is checked.
If this isn't set, then the default value for pager (set up
by the system manager) is used.
This may or may not be the internal pager.
To use the internal pager, you may set the variable pager to
.RI \*Q internal \*U
or to a null string.
.TP
.B pre_indent_str
(String)
If this variable is set, when including the body of a message into an outgoing
mail message (using the \-i option to
.I reply
or
.IR mail ,
or when using the \*Q~i\*U escape),
a line preceding the first line of
included text is printed using the string value of the variable.
This string uses the same printf style formatting characters as the
.B hdr_format
variable.
For example, you could set
.B pre_indent_str
as follows:
.sp
.ti +2
set pre_indent_str = '[In the message entitled "%s", on %7d\\n %n writes:]'
.sp
You can then include a message body using \*Q~i\*U, and you might
get something like this:
.sp
.in +2
.nf
[In the message entitled "This is a test.", on Jan 19,
X Dan Heller writes:]
> This is a test message to show how
> pre_indent_str might be used.
.ti -2
.sp
.fi
This example assumes that the string value of
.B indent_str
is not set.
.TP
.B post_indent_str
(String)
This variable has the same function as
.B pre_indent_str
except that the string is inserted into the message body
.I after
the text of the included message rather than before.
The purpose of this variable is to complement the string described by
the variables
.B pre_indent_str
and
.BR indent_str .
For example,
.sp
.in +2
.nf
set pre_indent_str = "/*"
set indent_str = " * "
set post_indent_str = " */"
.sp
.ti -2
An included message might look something like this:
.sp
/*
X * This is a test message to show how
X * post_indent_str and pre_indent_str
X * can work together with indent_str.
X */
.fi
.in -2
.TP
.B printer
(String)
Used to set the default printer for the lpr command.
.TP
.B print_cmd
(String)
This string should describe a
.IR UNIX (TM)
command other than "lpr" for sending
messages to the line printer.
Some people may choose to use a device independent
troff style program, but virtually any UNIX command suffices.
Common usage might include:
.sp
.ti +2
set print_cmd = 'ptroff \-ms \-Plp'
.ti +2
lpr .\-$
.sp
This command sends all messages from the current message to the last
message through the ptroff command, supplying the appropriate arguments.
.TP
.B prompt
(String)
You can set your prompt to tell you many different pieces of information.
By default, the prompt is set to the string
.sp
.ti +2
\*QMsg %m of %t: \*U
.sp
If you have 10 messages and your current message is 5, then your prompt
looks like:
.sp
.ti +2
Msg 5 of 10:
.sp
The string value that prompt is set to is printed as your prompt.
If the string contains a `%', then that character is
ignored, the next character is evaluated and an appropriate
value is printed in its place:
.sp
.nf
.in +2
.ta 0.5i
%F    full path name of the current folder
%f    name of the current folder (tail of %F)
%m    \*Qcurrent message\*U number
%t    total number of messages
%n    number of \*Qnew\*U messages
%u    number of unread messages
%d    number of deleted messages
%T    current time (hours and seconds)
%N    today's date (Number of the day in the month)
%W    weekday name (Sun, Mon, Tue, ...)
%M    current month
%Y    this year
%y    last two digits of %Y
\\n    a newline
\\t    a tab
.fi
.in -2
.sp
To include the values of variables in the prompt string, the format
\*Q%$variable\*U can be used, where
.I variable
is the name of any variable.
If the `$' character is
.I not
preceded by a `%', it is included literally,
rather than introducing a variable name.
Thus, two equivalent ways of including the name of the current folder
in your prompt are:
.nf
.in +4
set prompt = '%F> '
set prompt = '%$thisfolder> '
.in -4
.fi
.sp
Note the use of single quotes to prevent the value of
.B thisfolder
from being expanded at the time the prompt is set.
The only difference between these settings is that \*Q%F\*U adds the
string \*Q[read-only]\*U if the folder was loaded in read-only mode.
.TP
.B quiet
(Boolean/Multivalued)
This variable tells
.I Mush
to be quiet in various circumstances.
If set, but not to any values, the currently running version of
.I Mush
is not printed on startup.
Otherwise,
.B quiet
may be set to one or more words separated by spaces or commas.
Currently recognized words are:
.sp
.nf
.ta 1.5i
.in +4
.\" \& escapes are to make obvious the tab after each word
autosign    Suppress messages when appending signature.
await\&\&    Suppress \fBawait\fR's bell for new mail.
complete    Suppress word completion error bells.
fkey\&\&    Suppress warnings about unset function keys.
fortune\&    Suppress messages when appending fortune.
iconlabel    Suppress showing message count as icon label.
newmail\&    Suppress new mail notification messages.
pick\&\&    Suppress descriptions of pick searches.
startup\&    Suppress the startup message.
tool\&\&    Suppress tool mode bell for new mail.
.in -4
.fi
.sp
Error conditions for signatures and fortunes are still reported.
See the variables
.BR autosign ,
.BR complete ,
and
.B fortune
for more details.
The
.I newmail
setting does not prevent automatic inclusion of new mail, it only
suppresses the announcement of its arrival, including tool mode bells.
The
.I fkey
setting applies only to tool mode.
.TP
.B realname
(String)
Set to the name of the user.
The name is initialized to the value of the environment variable
.B NAME
upon invocation of the program.
If that isn't set, then the name is obtained from the password file if
available.
If this variable wants to be reset or changed after the
program has started, the user should issue the command:
.sp
.ti +2
set realname = "Your name here"
.TP
.B record
(String)
Set to the name of a file to record all outgoing mail.
This should be a full pathname or the current directory is searched.
The pathname may begin with `+' (indicating the user's ~/Mail directory
or the value of the
.B folder
variable) or with a `~' (or \*Q~user\*U)
indicating the user's home directory.
.TP
.B reply_to_hdr
(String)
When replying to mail,
.I Mush
searches for return paths from the message by searching for
the message headings \*QReply-to\*U, \*QFrom:\*U, and \*QReturn-path\*U,
in that order.
If none are found, then the first line of the
message created by the delivery system is parsed and the address
given there is used.  This special message header is created by most
mail delivery programs, but not all of them (MMDF, for one).  This line
is called the
.B From_
header because it is a colon-less header, but contains the return address
of the author of the message.
If the variable
.B reply_to_hdr
is set to a list of headers (delimited by spaces or commas), then that list
is searched.  If none of the headers listed in the variable exist
in the message, then a warning message is printed and the default
headers are used.  The special case From_ header can be specified
as one of the headers to search for.
.sp
.nf
.ti +2
set reply_to_hdr = "sender reply-to return-path from_"
.fi
.sp
This example shows that
.I Mush
searches (in order) the headers listed in the reply_to_hdr variable.
If one header isn't found, then
.I Mush
looks for the next in the list.
If none of the headers in the list are found, the default headers (mentioned
above) are searched.
The last header listed in the example is the special \*QFrom \*U header.
Also see the
.B reply
command.
.TP
.B save_empty
(Boolean)
Normally, when all messages in a folder are deleted and the user updates
the folder or changes to a new folder, the empty folder is deleted.
.B save_empty
prevents the folder from being deleted and it is left zero length.
Note: the main system mailbox is never deleted, even when empty.
.TP
.B screen
(Numeric)
May be set to the number of message headers to display at a time in the
line and curses modes.
.TP
.B screen_win
(Numeric)
May be set to the number of message headers to display in the tool mode.
A subwindow is created for message headers, and its size is large
enough to hold $screen_win headers.
Resetting this variable after the program is running will not change
the height of the display, and may confuse other operations.
.TP
.B sendmail
(String)
If set, the program and arguments described by this variable
are executed to actually deliver mail sent by
.I Mush.
.TP
.B show_deleted
(Boolean)
If true, deleted message headers are displayed along with
other messages (`*' indicates a deleted message) for the \fBheaders\fR
command.  Also, deleted messages can be displayed using any command which
displays a message.
In curses mode, this variable is ignored and deleted messages are always
displayed with other messages to facilitate undeleting messages.
.TP
.B show_hdrs
(Multivalued)
Set to a list (space and/or comma separated) of headers that are to be the
only headers displayed when viewing a message.
This variable disables the headers suppressed by the
.B ignore
command.
For example,
.sp
.ti +2
set show_hdrs = \*Qfrom date subject to cc\*U
.sp
only displays the headers
.B From: Date: Subject: To: Cc:
in their entirety.
.TP
.B sort\ \
(Boolean/string)
The value of this variable is the same as the arguments to the
.B sort
command.
This variable is used for the initialization file to presort
mail in the system mailbox upon entering
.IR Mush .
See the COMMANDS section for more information.
.TP
.B squeeze
(Boolean)
Whenever messages are read, piped, or saved, if this variable is set,
all consecutive blank lines are squeezed into one blank line.
.TP
.B status
(Read-only numeric)
This variable records the success or failure status of the most recently
executed command.
All line-mode commands return 0 (zero) for success and a negative value for
error.
Some curses mode commands return an error status to indicate that the
display has been corrupted, even when no actual error has occurred.
This variable is most useful in scripts to test the success of an operation
before proceeding.
.TP
.B tmpdir
(String)
This variable describes the path to use as the directory
for all tempfiles that
.I Mush
uses.  By default, the user's home directory is used.  If that
cannot be accessed, a directory writable by all is used (typically, /tmp).
If \fBtmpdir\fR is set, then it is used first.
.TP
.B thisfolder
(Read-only string)
The full path name of the current mailbox.
This variable cannot be modified or displayed by the
.B set
command; its value changes whenever a new folder is entered with the
.B folder
command.
During sourcing of the initialization files,
.B thisfolder
is not set, because the current folder has not yet been read.
If you refer to \*Q$thisfolder\*U in an initialization file
.RI ( e.g. ,
.IR .mushrc ),
be sure to do so inside an \*Qif $?thisfolder\*U test.
.TP
.B toplines
(Numeric)
The number of lines of a message to print when the
.B top
command is issued.  If unset, the value of
.B crt
determines the number of lines printed.
Note that the message body only is printed when using the
.B top
command; message headers are not counted as lines since they are not displayed.
.TP
.B unix\ \
(Boolean)
If set, commands that are not
.I Mush
commands are considered to be
.IR UNIX (TM)
commands.
This removes the inconvenience of requiring the user to do
shell escapes to do quick
.I UNIX
commands.
For systems that support job control, SIGTSTP stops the entire
.I Mush
shell as well as the process being executed.
When SIGCONT is delivered, both receive the
signal and
.I Mush
continues to wait for the job to finish.
.sp
Due to the lack of real job control, input/output redirection and UNIX command
piping, this mode of
.I Mush
is not intended to be used as a login shell.
.sp
If a
.I Mush
command name conflicts with a
.I UNIX
command, use the command
.B sh
to force execution as a shell command or use the full pathname of the command
(e.g. starting with a '/').
.sp
.BR Warning :
.I "Be aware that Mush pipes transmit message lists, NOT TEXT."
You cannot pipe the output of
.I UNIX
commands to or from
.I Mush
commands or other
.I UNIX
commands with the
.I Mush
pipe mechanism.  You can, however, pipe
.I Mush
commands to a final UNIX
command (see the \fBpipe\fR command for more information).
UNIX commands should be simple commands without pipes or metacharacters.
.sp
This feature is not available for the tool mode.
.TP
.B verbose
(Boolean)
Passes verbose flag to mail delivery systems when sending mail, and
causes
.I Mush
to print additional information about the sending process.
.TP
.B verify
(Boolean/Multivalued)
This variable causes mush to request confirmation of certain actions.
If set only as a boolean (no string value),
.B verify
asks just before sending mail whether you want to send, continue
editing, or abort the message altogether.
Otherwise,
.B verify
can be set to one or more of these words:
.sp
.nf
.ta 1.25i
.in +4
.\" \& escapes are to make obvious the tab after each word
mail\&\&    Confirm sending of mail (as above).
save\&\&    Confirm save-item selections (tool only).
.in -4
.fi
.sp
Appending of messages to files that are not folders is verified regardless
of the setting of this variable.
.TP
.B version
(Read-only String)
The value of this variable is the version string, printed by
.I Mush
at startup (unless
.B quiet
is set) and included in the \*QX-Mailer:\*U header in messages.
.TP
.B visual
(String)
May be set to the visual editor to use when ~v is specified.
Default is vi or the environment string VISUAL.
The visual editor is invoked by the \-e arguments to the
commands,
.B respond
and
.BR mail .
.TP
.B warning
(Boolean)
If set, warning messages are printed when:
.in +4
.ti -2
\(bu A command line alias (\*Qcmd\*U) looks like a command.
.br
For example,
.ti +2
cmd mail 'set fortune; \\mail'
.ti +2
cmd respond 'unset fortune; \\respond;'
.ti -2
\(bu The date format of a message is unknown.
.br
The date of a message is taken from the \*QDate:\*U header.
If the date on that header is unknown, other headers are searched for a
valid date format until a legal one is found.
This date may not be
correct in that it was the date the message was received, not sent.
.ti -2
\(bu A variable is unset without first being set.
.br
For example, if you give the command
.ti +2
unset metoo
and the variable
.B metoo
is not set, you are notified that the variable is not defined.
.ti -2
\(bu No header can be found for a digest article.
.br
This occurs when the
.B undigest
command encounters what appears to be an article separator but cannot
find a \*QFrom:\*U or \*QDate:\*U header in the following text.
.in -4
.sp
The intent is so that users who are used to their own environments
become aware of changes in other environments should they be forced
to use them.
There may also be warning messages of failed routines
or assertions that are not fatal enough to interrupt normal running
of the program.
.TP
.B wrap\ \
(Boolean)
Normally, when the last message is deleted, the current message
pointer remains pointing to the last message and the user is done
reviewing his mail.
If the
.B wrap
variable is set, the current message pointer wraps around to the
beginning of the user's messages again to the next undeleted message.
This also applies to the
.B next
command.
.TP
.B wrapcolumn
(Numeric)
May be set to a column number at which line wrap occurs when
composing messages.
If set, but given no value, column 78 is assumed.
When
.I Mush
is able to determine the number of columns on your screen, it
enforces a maximum value for
.B wrapcolumn
of two less than that number of columns.
Line wrapping can be disabled either by unsetting
.B wrapcolumn
or by setting it with the explicit value of 0 (zero).
.sp
Line wrapping occurs only at whitespace (spaces or tabs).
Lines containing no whitespace to the left of the specified column
are not wrapped.
If \fIMush\fR was started with the \-e (echo mode) option, or is in tool mode,
line wrapping cannot be done due to I/O incompatibilities.
.PP
In addition to the named variables described above, three special
variable forms are recognized.
.TP
.B $$
This string returns the process id (PID) of the current
.I mush
process.
Colon modifiers are not recognized for this special variable.
.TP
.BI $[ %fmt ]
The string \fI%fmt\fR is interpreted as a header formatting string
(as in the
.B hdr_format
variable) and is expanded using the headers from the current message.
Colon modifiers are allowed to follow the format.
For example,
.sp
.ti +4
save $[%4n]:l
.sp
saves the current message in a file whose name is the first four
characters of the name of the author, converted to lower case.
.TP
.BI $( %c )
The string `\fI%c\fR' is interpreted as a prompt format
(as in the
.B prompt
variable) and is expanded.
Colon modifiers are allowed.
For example,
.sp
.ti +4
echo $(%T)
.sp
prints the current time.
Note that \*Q$(%F)\*U is equivalent to \*Q$thisfolder\*U.
.PP
NOTE:  Evaluation of many \*Q$[%...]\*U or \*Q$(%...)\*U values in a single
command is inefficient.
If expansion of several formats is desired, it is better to use the \-h
and \-p options of
.B echo
or
.BR eval ,
which also provide better quoting of the interpolated strings.
.SH "MUSH SCRIPTS"
One of the most useful features of
.I Mush
is the ability to write scripts of
commands, which can be read by the
.B source
command from within
.IR Mush ,
or by redirecting input from the script and using the \-i option.
If your operating system supports the \*Q#!\*U interpreter mechanism,
a script can be even be executed as a program.
Script files can use all the usual
.I Mush
commands; the only restriction is
that the `!' history notation for referencing arguments of
.B cmd
aliases is disabled in scripts, so only very simple
.BR cmd s
work.
.PP
For example, a filtering file, \*Qfilter\*U, might contain:
.sp
.nf
.in +2
set newfolder = /usr/spool/mail/$USER
if is_shell
.in +4
if -z $newfolder
.ti +4
set newfolder = $mbox    # mbox must be set!
endif
if -e $newfolder
.ti +4
folder $newfolder
else
.ti +4
quit
endif
.in -4
endif
.sp
pick -f Mailer-Daemon | save mail_errors
pick -f yukko | delete
pick -s -i thesis | save +thesis_mail
pick -t unix-wizards | +wizmail
update
sort d
.in -2
.fi
.sp
Then the first command the user types when beginning a
.I Mush
session might be \*Qsource filter\*U, and the following happens:
.sp
.in +2
First, a new variable called \fBnewfolder\fR is set to the user's spool
mailbox (the system mailbox).
A test is made to see if the shell is running, because the \fBfolder\fR
command can only be used from the shell.
Then a test is done to see if the spool mailbox is zero length, and if it is,
the variable is reset to the value of the user's \fBmbox\fR variable
(mbox must already be set by this time or this fails).
A final test assures that the new folder exists.
If it does, \fIMush\fR changes folders to the new folder.
If it doesn't exist, the program exits (via \fBquit\fR).
.sp
Once the correct folder has been loaded, all messages that have
\*QMailer-Daemon\*U in the From header are saved in the file mail_errors.
Then, all mail from the user \*Qyukko\*U is simply deleted.
Next, all mail that has in the Subject field, \*Qthesis\*U
(case ignored, so \*QThesis\*U would also match) are
saved in the file $folder/thesis.
The next command finds all messages that are addressed to
the group \*Qunix-wizards\*U (of which the user is an elite
member) and saves them in the file $folder/wizmail.
Last, the folder is updated, removing all deleted mail
(saved mail may be marked as deleted)
and the folder is reread and sorted according to the date of the messages.
.in -2
.PP
If the \*Q#!\*U mechanism is supported, the \*Qfilter\*U script can be
made into a program by adding as the first line:
.sp
.ti +4
#! /usr/local/bin/mush -F
.sp
(The actual location of
.I mush
may vary from system to system; /usr/local/bin is used as an example.)  Then
make the file executable:
.sp
.ti +4
chmod +x filter
.sp
Now, when the command \*Qfilter\*U is typed at the user's regular shell
prompt, the
.I mush
program is invoked by the operating system.
.I Mush
first reads the commands from the \*Qfilter\*U file and performs them,
exactly as described above, and then continues into the usual interface.
If it is preferable for
.I mush
to exit after reading the script, the first line can be changed to:
.sp
.ti +4
#! /usr/local/bin/mush -F!
.sp
The \-F! option should also be used when running
scripts in the background or in other circumstances where the standard
input cannot be a terminal, and the only commands to be executed are those
in the script itself.
.PP
Note that any additional arguments passed to a \*Q#!\*U script are
interpreted by
.IR mush ;
they are not passed along in any way that makes them accessible to the script.
Thus,
.sp
.ti +4
% filter \-f mbox
.sp
applies the commands in the \*Qfilter\*U script to the \*Qmbox\*U folder.
.SH MACROS
Macros are available in several different modes in
.IR Mush .
.I "Curses mode macros"
are created by using the
.B bind
command with the special function
.B macro
(or by using
.BR bind-macro ,
which is synonymous).
These macros are effective only when the curses interface is active.
.I "Line mode macros"
are created with the
.B map
command, and are effective only in the line-oriented command interface.
Finally,
.I "composition mode macros"
are created with the
.B map!
command, and are effective only when composing mail messages.
Macros are not available in the
.I tool
mode, nor when composing messages from the tool mode.
Line and composition mode macros are also nonfunctional when
.I Mush
is started with the \-e (echo) option.
.PP
In general, macros consist of two parts:  a
.I "key sequence"
and an
.IR expansion .
The
.B "key sequence"
is the character or string of characters which, when typed in the
appropriate mode, is recognized by
.I Mush
as a reference to a macro.
The
.B expansion
part of a macro is the string that is actually \*Qseen\*U by
.I Mush
when the key sequence is recognized.
Macros are like an interactive search-and-replace function;
if a key sequence appears in the input, the associated expansion is
substituted in its place.
Thus, if you create a macro whose key sequence is \*Q^X^W\*U (control-X
control-W) and whose expansion is \*Qsave\*U, then when you hold down the
control key and type the two characters `x' and `w', the effect is
as if you had actually typed the four characters `s', `a', `v' and `e'.
This is called \*Qexpanding\*U the macro.
More detailed examples of macros are presented in the subsections
for each mode in which macros can be used.
.PP
Key sequences are usually made up of control characters or special
strings of characters generated by \*Qfunction keys,\*U
but may in fact be almost any string the user desires.
Keys that generate a signal or an end-of-file from the keyboard
(for example, on BSD systems, control-Z generates a TSTP signal and
control-D generates an end-of-file) can never appear
in key sequences, and macros in line or composition modes cannot
.I begin
with a newline, control-D, or any of the editing keys
(erase, word-erase, line-erase, etc.).
Otherwise, there are no restrictions.
It should be kept in mind, however, that for the line and composition
modes, key sequences should be unusual characters or combinations of
characters, not individual lower-case letters.
If common characters or strings are used for key sequences, much
confusion can result when typing commands or messages.
This is not important in the curses mode.
.PP
In the line and composition modes, a
.I timeout
is used for key recognition; that is, once the first character of the
key sequence has been typed, the succeeding characters must be typed
after it relatively quickly, or
.I Mush
fails to recognize them as a continuous sequence.
It is for this reason that key sequences are usually either very short,
SHAR_EOF
true || echo 'restore of mush.1 failed'
fi
echo 'End of  part 17'
echo 'File mush.1 is continued in part 18'
echo 18 > _shar_seq_.tmp
exit 0
exit 0 # Just in case...
--
Kent Landfield                   INTERNET: [e-mail]
Sterling Software, IMD           UUCP:     uunet!sparky!kent
Phone:    [phone]         FAX:      [phone]
Please send comp.sources.misc-related mail to [e-mail].