v06i028: Elm mail system (elm), Part03/14

[sources-request at mirror.UUCP]

Submitted by: Dave Taylor <pyramid!hplabs!hpldat!taylor>
Mod.sources: Volume 6, Issue 28
Archive-name: elm/Part03

# Continuation of Shell Archive, created by hpldat!taylor

# This is part 3

# To unpack the enclosed files, please use this file as input to the
# Bourne (sh) shell.  This can be most easily done by the command;
#     sh < thisfilename


if [ ! -d doc ]
then
  echo creating directory doc
  mkdir doc
fi

# ---------- file doc/Ref.guide ----------

filename="doc/Ref.guide"

if [ -f $filename ]
then
  echo File \"$filename\" already exists\!  Skipping...
  filename=/dev/null		# throw it away
else
  echo extracting file doc/Ref.guide...
fi

cat << 'END-OF-FILE' > $filename
.PH ""
\"
\"  Reference guide to the ELM mail system.
\"  format with 'troff -mm Elm.guide > Elm.format
\"  or something similar.
\"  (C) Copyright 1985 Dave Taylor
\"
\"  Last update: May 14th, 1986
\"
.SA 1
.nr Hy 1
.nr Pt 1
.nr Pi 8
.lg
.rs
.ds HF 3  3
.ds HP 12 12 10 10 10
.PF ""
.HM 1 1
.ce 99
.sp 5
.ps 20
\fBElm Reference Guide\fR
.sp 5
.ps 12
\fIA comprehensive list of all commands, 
options and such to the \fBElm\fP mail system\fR
.sp 5
Dave Taylor
.sp
Hewlett-Packard Laboratories
1501 Page Mill Road
Palo Alto CA
94304
.sp
email: taylor at hplabs or hplabs!taylor
.sp 10
.ps 18
\fB\(co\fR\s12 Copyright 1986 by Dave Taylor
.ce 0
.SK
.ce 99
.ps 14
\fBElm Reference Guide\fR
.ps 10
.sp
(version 1.1)
.sp 2
Dave Taylor
Hewlett-Packard Laboratories
1501 Page Mill Road
Palo Alto CA
94304
.sp
email: taylor at hplabs or hplabs!taylor
.sp 2
\*(DT
.ce 0
.nr P 1
.PH "'Elm Reference Guide''Version 1.1'"
.PF "''Page \\\\nP''"
.sp 3 
.H 1 "Introduction"
.P 1
There are many parts to a complex software system and \fBElm\fR
is no different.  This guide describes fully all the options 
available in the mailer, including the starting options,
the commands (in considerably more detail than
in the \fIUsers Guide\fR) and the \fI.elmrc\fR file.
.P 1
To be more explicit, this document covers;
a discussion of the \fI.elmrc\fR file,
starting options of \fBElm\fR, 
outgoing mail processing,
responses of various commands,
the mail archive file,
the \fInotes\fR system,
the Alias system,
system aliases etc,
more on the \fBElm\fR utilities,
and a section for expert mail users.
.P 1
Without any further ado, then, let's get this show on the road!!
.sp 2
.H 1 "The .elmrc File"
.P
The mailer, like lots of other software on the
Unix\v'-.3'\s5TM\s10\v'.3' system, has the ability to automatically read 
in a configuration file at each invocation.  The file must be
called \fI.elmrc\fR and reside in your home directory for it
to be found, and can have any of the following entries
in any order;
.sp 2
.ps 12
.ne 8
String Variables
.ps 10
.VL 13 0
.LI "alternatives"
This is a list of other machine/username combinations
that you receive mail from (forwarded).  This is used 
when the \fIgroup reply\fR feature is invoked to ensure that
you don't send yourself a copy of the outbound message.
(no default)
.LI "calendar"
This is used in conjunction with the "<" \fIscan message for
calendar entries\fR command.  The default place to put
calendar entries if found is \fI$HOME/calendar\fR.  This
variable can be set to specify something else..
.LI "editor"
The editor to use when typing in new mail.
(default is to use the value of the $EDITOR in your
current environment)
.LI "fullname"
This is the name the mailer will use when sending mail 
from you.  It is highly recommended that you use your
full name and nothing strange or unusual, as that can
appear extremely rude to people receiving your mail.
(Default is to use the "gecos" field from the \fI/etc/passwd\fR file)
.LI "mailbox"
This is where to put incoming mail after you've read it.
When you answer `n' to the "keep messages in incoming mailbox?" prompt, this
is where the messages go!
(default is the file \fImbox\fR in your home directory)
.LI  "maildir"
This is the default mail directory, and is used to expand filenames
in the mailer when specified using the `=' metacharacter*.  That
.FS *
Note that `%' and `+' are synonymous with `=' throughout \fBElm\fR
.FE
is, if you save to file \fI=/stuff\fR then the `=' will be expanded
to the current value of maildir.
(no default)
.LI "prefix"
When you \fIreply\fR to a message or \fIforward\fR a message to another person,
you can optionally include the original message.  Defining the
prefix value here allows you to indicate what the prefix of 
each included line should be.  (default is "> " and is
fairly standard in the Unix community)
.LI "print"
This indicates how to print out a message.  There are two
possible formats for this string, either a command that
can have a filename affixed to (as a suffix) and then
sent to the system for execution, or a string that 
contains the meta-sequence `%s' which will be replaced
by the name of the file and then also sent to the
shell.  Examples of each are;
.nf

	print = print -formfeed
	print = pr %s | lpr

.fi
(no default)
.LI "savemail"
This is where outgoing mail will have a copy silently (and
quickly) saved.  This will only be used if the flag \fIcopy\fR
is turned on.  Also note that if the \fIsavename\fR flag
is turned on then this line is ignored since each outgoing
message is saved according to whom it's being sent to.
(default is to have this option disabled)
.LI "shell"
This defines the shell to use when doing ``!'' escapes and
such.  Note that the program also reads the $SHELL variable
out of the current environment, but that defining this
in the .elmrc file will override the environment definition.
.LI "sortby"
This is something new and deluxe!  When reading mailboxes, 
either incoming or saved, you can have them sorted by any
number of different ways.  This can be changed without leaving
the \fBElm\fR system by changing the \fIoptions mail-sorted-by\fR
field, but it can also be predefined to any of the following;
.sp
.VL 15 3
.LI "from"
This will sort according to whom each message is \fIfrom\fR.
.LI "sent"
This will sort \fIleast recently sent\fR to 
\fImost recently sent\fR.
.LI "received"
This will sort \fIleast recently received\fR to 
\fImost recently received\fR.
.LI "subject"
This will sort according to the \fIsubject\fR of each message.
.LI "lines"
This will sort \fIshortest\fR to \fIlongest\fR by message.
.LI "status"
This will sort by priority, action, new, tagged, then deleted
order.
.LE
.sp
Each of these fields can also optionally be prepended with the
sequence "reverse-" to reverse the order of the sort.  The 
sorting method in the sample \fI.elmrc\fR, for example, 
is \fIreverse-sent\fR, to have the new
mail always be listed first in the headers (note that this doesn't
imply anything about the location of the message in the \fImailbox\fR
itself!)
.LI "weedout"
When specifying this option, you can then list headers that
you \fBdon't\fR want to see when you are read mail.
This list can continue for as many lines as desired, as 
long as the continued lines all have leading indentation.
(no default)
.LE
.sp 2
.ps 12
.ne 8
Numeric Variables
.ps 10
.VL 13 0
.LI "bounceback"
This is a hop count threshold value and allows you to
set up the mailer so that when you send mail more than
\fIn\fR machines away, it'll automatically include a
"Cc:" to you through the remote machine.  In practice
this should be very rarely used.  (Note: this refuses to
bounce mail off an Internet address.  The default is to
have it set to zero, which disables the function)
.LI "timeout"
On more advances systems, it's nice to start up the 
mailer in a window and let it sit in background 
unless new mail arrives (see \fIwnewmail\fR for
another window oriented mail program) at which point
it can be brought up to the forefront of the system 
and read.  In this case, it would be quite convenient
to have the mailer internally resynchronize every
``delta'' seconds.  That's exactly what this particular
option allows.  
.sp
This is also useful for normal terminals, for example you can
leave \fBElm\fR running at night (I usually do) and when you
come in in the morning it'll be all ready to read your mail!
.sp
(The default is a 30 second timeout period).
.LE
.sp 2
.ps 12
.ne 8
Boolean Variables
.ps 10
.VL 12 0
.LI "alwaysdelete"
When set, this changes the default answer
of the prompt "Delete messages?" to the indicated value.  (default is
to have the answer be \fINo\fR (alwaysdelete=OFF))
.LI "alwaysleave"
This changes the default answer on the "keep mail in incoming mailbox?"
prompt to the value indicated (default
is to have the default answer be \fINo\fR (that is, alwaysleave=OFF)
.LI "arrow"
Sometimes your are forced to use a slow, or ``dumb'' terminal.  In this
case, you can force the current message pointer to be the ``->''
sequence rather than the inverse bar.  (Note that this is
identical in function to the `-a' starting option) (default is OFF
unless you're on an IBM 3270) (I'll bet you think I'm joking...)
.LI "autocopy"
This is a boolean flag, and if set will automatically copy
the text of each message being replied to into the edit
buffer.  (default is OFF)
.LI "copy"
This, in combination with the \fIsavemail\fR filename, will
allow you to have silent copies of all outgoing mail
made on the outbound step.  
(default is OFF)
.LI "editout"
This rather primitive facility allows you to edit the headers of
your message (and create some new ones!) after editing an 
outbound message.  At that point you can also optionally return
into the editor.  (default if OFF)
.LI "keypad"
If on, this tells \fBElm\fR that you have an HP terminal and enables
the <NEXT>, <PREV>, <HOME> and <SHIFT-HOME> keys.  (default is OFF)
.LI "movepage"
If this is turned on then commands that move through the
mailbox by pages (notably the `+' and `-', <PREV> and <NEXT>
keys) will also move the current message pointer to the
top of that page of messages.  If this is turned off 
then moving through the pages doesn't alter the
current message pointer location.
(default is OFF)
.LI "noheader"
This boolean flag tells the mailer not to include the 
headers of messages when copying a message into a file
buffer for replying to or forwarding.
(default is OFF)
.LI "pager"
This is the system to be used when paging through messages.  It
will be handed the message line by line from standard input...
(default is "/usr/bin/more" on Bell systems and "/usr/ucb/page" 
on Berkeley systems)
.LI "pointnew"
If this is turned on, the mailer will automatically 
pointing to the first new message in your mailbox when started, instead
of at message #1.  Note that this is only used for the incoming mailbox!
(default is ON)
.LI "resolve"
This is a boolean flag that defines the behaviour of the
program for such actions as deletion, saving a message 
and so on.  
(default is ON)
.LI "savename"
One of the problems with electronic mail systems is that one
tends to get very large, one-dimensional (flat) files that
contain lots of completely unrelated mail.  If this option
is turned on, \fBElm\fR will use a more intelligent 
algorithm - on incoming mail, when you \fIsave\fR it, the default
mailbox to save to (changeable by pressing anything other than
<return> of course) is a file that is the \fIlogin name\fR of the
person who sent you the message.  Similarly, when sending mail out,
instead of just blindly saving it to the \fIsavemail\fR file, \fBElm\fR
will first try to save it to a file that is the login name of the 
person who is to receive the mail*.
.FS *
When sending to a group, it's saved to the first person in the 
list only.  One day we'll have \fIpointers\fR to messages, then...
.FE
If the file doesn't already exist, then it will save the mail in
the \fIsavemail\fR file.
.P 0
In practice, this means that important people that you communicate
with (those that you tend to save mail from) have files that are
actually \fIa recorded log of the discussion in both directions\fR
and those others (random mailings) are all stuffed in the \fImailsave\fR
file for easy editing/removing. (The default is OFF)
.LI "signature"
This can be turned on which will allow the mailer to automatically
append a ".signature" file from your home directory to all outbound
mail as you enter the editor.  (default is OFF)
.LI "softkeys"
If on, this tells \fBElm\fR that you have an HP terminal with the
HP 2622 function key protocol and that you'd like to have them available
while in the program.  (default is OFF)
.LI "titles"
This flag allows you to have the first line of a message
titled with:
.sp
.nf
Message #\fIN\fR from \fIusername\fR                Mailed \fIdate\fR at \fItime\fR
.fi
.sp
where all the information has been previously extracted
from the message.
This is especially useful if you weed out all the headers of each
message with a large `weedout' list...
(default is OFF)
.LI "weed"
This is a boolean flag that, in combination with the
"weedout" list, allows you to custom define the set of
headers you would like to not have displayed while reading
messages.  
(default is OFF)
.LE
.sp
One more thing: the format for each of the lines is;
.nf

	variable = value

.fi
and for boolean variables, \fIvalue\fR can be `ON' or `OFF' only.
.sp
For a better idea of how this all works, here's my \fI.elmrc\fR file.
While looking through it, notice that you can have lots of comments
and blank lines for readability and that you can also use `shell
variables' and the `~' metacharacter for your home directory, 
and they are expanded accordingly when read in by the mailer.
.nf

 #
 # .elmrc - automatic variable defines for the `Elm' mailer.
 #
 # Personalized for Dave Taylor
 # 
 
 fullname = Dave Taylor
 
 # where to save my mail to, default directory
 maildir  = $HOME/Mail
 
 # where to save messages to, default file
 mailbox  = ~/Mail/mailbox
 
 # where to put calendar file entries
 calendar = ~/.Agenda

 # what editor to use
 editor   = $EDITOR

 # how to sort mailboxes
 sortby  = Reverse-Sent
 
 # where to save outbound mail if not specified somewhere else
 savemail = ~/Mail/mail.sent
 
 # how to print a message (`%s' is the filename)
 print    = pr %s | lpr 
 
 # prefix sequence for including message text in other messages...
 prefix = ">"
 
 # what headers I DON'T want to see, ever.
 
 weedout  = "Via:"  "Sent:"  "Date:"  "Status:"  "Original"
 	   "From"  "Phase"  "Subject:"  "Fruit"  "Sun"
 	   "Lat"  "Buzzword"  "Return"  "Posted" "Telephone"
 	   "Postal-Address" "Origin" "X-Sent-By-Nmail-V"
 	   "Resent" "X-Location"  "Source" "Mood"  "Neuron"
 	   "Libido" "To:" "X-Mailer:"  "Full-Name:" "X-HPMAIL" 
 	   "Cc:" "cc:" "Mmdf" "Network-" "Really-" "Sender:"
 
 # threshold for bouncing copies of remote uucp messages...
 # zero = disable function.
 bounceback = 0
 
 # Set the main prompt timeout for resynching...
 timeout = 60
 
 # automatically copy message being replied to into buffer? 
 autocopy = OFF
 
 # save a copy of all outbound messages? 
 copy     = ON
 
 # emulate the mailx message increment mode (only increment after something
 # has been `done' to a message, either saved or deleted)
 resolve  = ON
 
 # enable the weedout list to be read...
 weed     = ON
 
 # when messages are copied into the outbound buffer, don't include headers
 noheader = ON
 
 # display message title when displaying pages of message
 titles	 = ON
 
 # edit the headers as the message leaves the machine (sort of)
 editout	 = OFF
 
 # save messages, incoming and outbound, by login name of sender/recipient
 savename = ON
 
 # when using the page commands (+ - <NEXT> <PREV>) change the current
 # message pointer...
 movepage = ON
 
 # try to include a ".signature" file from my home directory on 
 # outbound mail..
 signature = ON
 
 # should we always leave messages as pending (change the default 
 # answer to yes)
 alwaysleave = ON
 
 # should we always delete messages we've marked for deletion (change the
 # default answer to yes)
 alwaysdelete = ON
 
 # set pager accordingly
 pager = "/usr/bin/page"
 
 # we're running on an HP terminal...
 keypad = ON
 
 # alternative addresses that I could receive mail from (usually a
 # forwarding mailbox) (lots, huh!)
 alternatives = hpcnof!dat, hpcnof!d_taylor, hpcnou!d_taylor,
 	hpcnou!root, hpcnou!postmaster, hpcnoe!d_taylor, hpcnoe!dat,
 	hpcnoa!d_taylor, hpcnoa!dat, hpfcla!d_taylor, hpldat!taylor, 
	taylor at hpldat, taylor%hpldat, root at hpldat, hpldat!root, 
 	postmaster, taylor, root

.fi
.sp 2
.H 1 "The Starting Parameters"
.P
There are a number of starting options to the
.B Elm
program, with only one that needs to be remembered: ``-?''or ``-h'' for help.
.P 0
The flags are;
.VL 13 0
.LI "-a"
Arrow.  This allows you to have the "->" arrow pointer
rather than the inverse bar.  This can also be set in
the \fI.elmrc\fR file - check the boolean variable \fIarrow\fR).
.LI "-c"
Check only.  This is useful for expanding aliases 
without sending any mail.  The invocation is just
like sending mail: \fBelm -c\fI alias or aliases\fR.
.LI "-d\fIn\fR"
Set debug level to \fIn\fR.  Useful for debugging the 
.B Elm
program.  The results of using the debug option is
much less drastic than in the previous versions of 
the program - it creates a file in your home directory
called \fIElm.debug.info\fR and creates a (verbose) log
of activity as the program is used.  
.sp
Level \fIn\fR can be 1 thru 5, where the higher numbers generate
more output.
.LI "-f \fIfile\fR"
File.  Read specified file rather than the default input mailbox.
Note that you can use the same metacharacters as when 
you \fIchange mailboxes\fR from within the program.
.LI "-h or -?"
Help.  Gives a short list of all these options and exit.
.LI "-k"
Keypad - This option, when used, lets the \fBElm\fR program
know that you're on an HP terminal, and it can then interpret
the <PREV>, <NEXT> and <HOME>/<SHIFT>-<HOME> keys accordingly.  If you
are not on an HP terminal, it is recommended that you do
NOT use this option. (see the \fIkeypad\fR option in
the \fI.elmrc\fR section)
.LI "-K"
Keypad + softkeys.  The \fBElm\fR mailer can, to a rather limited
extent, use the HP softkeys as an alternative form of
input.  If you specify this option be sure that you're on
an HP terminal that can accept the standard 2622 terminal
escape sequences! (see the \fIsoftkeys\fR option in
the \fI.elmrc\fR section for more information)
.LI "-m"
Inhibit display of the 3-line menu when using the mailer.  This,
of course, gives you three more message headers per page instead.
.LI "-s \fIsubject\fR"
In batch mode, this is how to indicate the subject of the
resulting message.  Please see the section on "Non-Interactive
Uses of Elm" in the \fIElm Users Guide\fR for more information.
.LI "-z"
Zero.  This causes the mailer not to be started if you don't
have any mail.   This emulates the behaviour of programs
like \fImailx\fR.
.LE
.P
All the above flags default to reasonable options, so there is
usually no need to use them.   
.sp 2
.H 1 "Special Outgoing Mail Processing"
.sp
.P
There are a few extra features that the mailer offers on
outgoing mail that are worthy of mention;
.sp
.P
The first, and probably the most exciting feature*, is the
.FS *
Unfortunately, at many non-US sites, it's quite probable that
you won't be able to use this feature since you won't have
the "crypt()" library available due to licensing restrictions.
.FE
ability to send \fIencrypted\fR mail! To do this is 
extremely simple:  You need merely to have two key lines
``[encode]'' and ``[clear]'' in the message body.
.P 0
Consider the following outgoing message:
.nf

	Joe,
		Remember that talk we had about Amy?  Well,
	I talked to my manager about it and he said...

	uhh...better encrypt this...the usual `key'...

	[encode]

		He said that Amy was having family problems
	and that it had been affecting her work.

		Given this, I went and talked to her, and 
	told her I was sorry for getting angry.  She said
	that she understood.

		We're friends again!!
	[clear]
	
		Exciting stuff, eh?   

					 Mike

.fi
While this is obviously quite readable while being typed into 
the editor, as soon as the message is confirmed as wanting
to be sent, the \fBElm\fR mailer prompts with;
.nf

	Enter encryption key: @

.fi
and accepts a key (a series of 8 or less characters) without
echoing them to the screen.  After entry, it will ask for the
same key again to confirm it, then *poof* it will encrypt and
send the mail!
.P
If you have the \fIcopy\fR option enabled, the program will save
your copy of the message encrypted too.  (This is to ensure
the privacy and security of your archived mail too!)
.P
If the mailer doesn't ask for the encryption key, it's because
you don't have the ``[encode]'' entered as the first 8 characters
of the line.  It MUST be so for this to work!!
.P
On the other end, a person receiving this mail (they must also
be using \fBElm\fR to receive it, since this mailer has a
unique encryption program) will be reading the
message and then suddenly be prompted;
.nf

	Enter decryption key: @

.fi
and will again be asked to re-enter it to confirm.  The
program will then on-the-fly decrypt the mail and display
each line as it is decoded.  The `[clear]' line signifies
that the block to encrypt is done.
.P
For those sites not running \fBElm\fR, a separate program
suitable for a filter for use with other mailers is available.
.P 0
Note that it is not possible currently to \fIpipe\fR or \fIprint\fR
encrypted mail.
.sp
.P
The other option on outgoing mail is the ability to
specify what section of the message you want to have
archived (assuming \fIcopy\fR is enabled) and what section
you don't.  This is most useful for sending out source
file listings and so on...
.P
To indicate the end of the section that should be
saved in the archive, you need merely to have the
line
.nf

	[nosave]

.fi
appear by itself on a line.  This will be removed from 
the outgoing mail, and will indicate the last line of
the message in the saved mail.
.sp 2
.H 1 "Responses..."
.sp
.P
This section will discuss each command in the 
.B Elm
program in more detail than above, including the 
prompts the user can expect upon executing the
command, the meaning of different options etc etc.
.sp
.VL 10 3
.LI ?
Help.  This command used once puts you in the \fIexplain key\fR
mode, where any key you press will result in a one-line description
of the key.  Pressed again at this point will produce a summary 
two pages listing each command available.
<escape> or `.' will leave the help mode and return you to the
main menu level.
.LI !
Shell.  This allows you to send a command to the shell without
leaving the program. 
.LI |
Pipe.  This command allows you to pipe the current message
or the set of \fItagged\fR messages
through other filters as you desire.  The shell used for
the entire command will be either the one specified in
your \fI.elmrc\fR file, or, if none, \fI/bin/sh\fR.
.LI \/
Pattern match.  This command, on the top level, allows the
user to search through all the \fIfrom\fR and \fIsubject\fR lines of
the current mailbox starting at the current message and
continuing through the end.  If the first character of the
pattern is a `/', then the program will try to match the
specified pattern against \fBany\fR line in the mailbox.  Again,
this works from one after the current message through the
end.  Both searches are case insensitive.
.LI <n>
Specify new current message.  Typing in any of the digits one
thru nine will result in the 
.B Elm
program producing the prompt `Set current to : n', where `n' is
the digit entered.  
Note that changing the current message to a message not on the 
current page of the headers will result in a new page of headers
being displayed.
.LI "<"
Scan message for calendar entries.  A rather novel feature of 
the \fBElm\fR mailer is the ability to automatically incorporate
calendar/agenda information from a mail message into the users
calendar file.  This is done quite simply; any message that has
either the pattern;
.DS
      -> \fIcalendar entry\fR
.DE
or
.DS
      - \fImulti-line\fR
      - \fIcalendar entry\fR
.DE
will be automatically added to the users \fIcalendar\fR file (see
the \fIcalendar\fR option of the \fI.elmrc\fR file) if the `<'
command is used.  The main difference between the two formats is that
the first is assumed to be a \fIcalendar(1)\fR entry (the `->' is
stripped off), and the second is a more generic format (only the `- '
is stripped off).
.sp
For example, let's say we had a message with the text
.DS
	Anyway, here's the appointment entry for the seminar;

	-> 8/03 3:00pm: AI Seminar with Ira Goldstein of HP Labs

	if you're using ELM you can just "<" it...
.DE
then using the `<' command would add the line;
.DS
8/03 3:00pm: AI Seminar with Ira Goldstein of HP Labs
.DE
to the users \fIcalendar\fR file.
.LI a
Alias.  The alias system is a way by which more complex mail addresses
can be shortened for the mail user.  For example;
.nf

  joe, bleu : Joe Bleu : joe at hpcfla

.fi
which allows mail to `joe' or `bleu' with the system expanding
the address properly.  As is obvious, this not only saves remembering
complex addresses, it also allows the address to be optimized to
go through the minimum number of machines without anyone having to
be informed of the change.  A more detailed discussion can
be found in either the section entitled \fIThe Alias System\fR in
this document or the \fIElm Alias Guide\fR.
.LI b
Bounce mail.  This ``remails'' mail to someone else in such a
way as to make the return address the original sender rather
than you (as opposed to the \fIforward\fR command, which makes
the return address \fIyou\fR rather than the original sender)
.LI c
Change mailbox.  Specifying this command allows the user to change
the mailbox file that is currently being read.  This is intended 
for perusal and reply to previously archived messages.
The prompt is `Name of new mailbox : ' and entering <return>
cancels the operation, while entering a filename causes the program
to read that file as the new mailbox file, if possible.
As with the \fIsave\fR command, this command expands filenames
with `~' being your home directory and `=' being your
\fImaildir\fR directory, if defined.  This command also allows the
special character `!' to be used to allow you to change to
the default incoming mailbox.
.LI "d, u"
Delete and Undelete.  Neither of these two commands have any prompts
and indicate their action by either adding an asterisk to the current
message index entry (indicating deletion pending) or removing the
asterisk (indicating that the deletion is cancelled).
.LI "<control>-D"
This command allows you to easily mark for deletion all messages 
that have a specific pattern.  After <control>-D is pressed,
the program will prompt for the string to match (currently it
only matches either the \fIfrom\fR or \fIsubject\fR lines of
the message).
.LI e
Edit mailbox.  This allows you to modify the current mail file at
a single keystroke.  This is mostly useful for editing down messages
before saving them.  Modifying headers should be done with extreme
caution, as they contain routing information and other vital stuff
for full functionality.
.LI f
Forward.  Allows the user to forward the current message to another user.  
This copies the message into the edit
buffer and allows the user to add their own message too.
The prompt is `Forward to:' and will expand an alias if
entered.
(see \fIbounce\fR above, too)
.LI "j, k"
These two keys work similarly to what they would do in \fIvi\fR or
any of the other (precious few) screen oriented programs.  The `j' key moves
the current message pointer down to the next message (going to
the next page if needed) and the `k' key moves the current
message pointer back to the previous message (also changing 
pages if needed)
.LI m
Mail.  Send mail to a specified user.  The prompt that is associated
with this command is `Send mail to :'.  Entering an alias name results
in the full address being rewritten in parenthesis immediately.  This
prompt is followed by `Subject:' which allows the user to title their
note.  The final field is `Copies to: ', which allows other people
specified to receive "carbon copies" of the message. 
Upon entering all three items the 
.I vi
editor (or any other editor specified by $editor) 
is invoked and the message can be composed.
.LI n
Next message.  See \fI<return>\fR.
.LI o
Options.  This full-screen display allows you to alter the settings
of a number of parameters, including the current sorting method,
the method of printing files, the calendar file, the save file, and
so on.  It's self-documenting (where have you heard \fIthat\fR
before?) so isn't explained in too much detail herein.
.LI p
Print.  This allows you to print out the current
message or the tagged messages to a previously defined printer 
(see the section on the \fI.elmrc\fR discussing the \fIprint\fR variable)
.LI q
Quit.  This command's action is dependent on the current state of
the 
.B Elm
program.
For example, if the current mailbox is the default mailbox the messages
that are not deleted are saved in the file $home/mbox, whereas
if it is a specified mailbox the to-be-deleted messages are 
removed from the
file.  The possible prompts are `Save to mailbox?' if the default mailbox
is being read and there is at least one message to save, 'Delete all
messages' if all messages in any mailbox are marked for deletion 
or `Delete message(s)?'
if not reading the default mailbox and there are some messages that
should be saved.  A response of `n' (no) to either of these questions will
result in the quit command aborting, and the files being untouched.
.LI r
Reply.  Reply to the author of the current message.  If
the autocopy flag is not specified, the program will 
prompt `Copy Message? (y/n)' to which the user can specify 
whether a copy of the source message is to be copied into the edit
buffer, or not.  If copied in, all lines from the message are 
prepended with the prefix character sequence, as specified in
the users \fI.elmrc\fR file.
.LI s
Save to file.  This command allows the current message or set of
tagged messages to be copied 
into an arbitrary file.  If there is anything in the file currently the
message or messages are appended to the end, otherwise the file is created
containing only the newly saved mail.  The prompt for this command
is `Save to file : '.  A response of <return> cancels the command
and returns the user to the system prompt.
After saving a file, each message is marked for deletion and,
if saving just one message,
the current message pointer is incremented.
The usual filename metacharacters are available, too.
.LI t
Tag.  Tag the current message for a later operation*.
.FS *
Currently only \fIpipe\fR, \fIprint\fR, and \fIsave\fR support this.
.FE
.LI "<control>-T"
Tag all messages containing the specified pattern.  Since \fItagging\fR
messages can occur on screens other than the one being viewed, the 
\fIElm\fR system will first check to see if any messages are currently
\fItagged\fR and ask you if you'd like to remove those tags.  After
that, it will, similar to the \fI<control>-D\fR function, prompt for
a pattern to match and then mark for deletion all messages that contain
the (case insensitive) pattern in either the \fIfrom\fR or \fIsubject\fR
lines. 
.LI x
Exit.  This is functionally the same as answering \fIN\fRo to the 
.I quit
command prompt, and simply leaves the program in the quickest
possible manner.  This command can also occur from typing
DELETE, or control-Q, both of which are also 
.I exit
commands.
.LE
.sp 2
.H 1 "The Mail Archive File"
.sp
.P
The format of the mail saved to the archive file is also
worth a quick discussion.  Unlike the usual exact copy
of the entire header section, the archived mail has the
following header;
.nf

	From To:<name> 15 Jan 1985 4:54:30 MST
	To: <address>
	Subject: <subject>
	Cc: <address>

	<message body>

.fi
The first line, the `From' line, is deliberately mangled
with the occurance of the `To:<name' to ensure that when
you are perusing your archive file with the mailer that
you see \fIwho the message was to\fR, since they're all going
to be from you!!  The <name> will either be the machine!login
of the person, or, if originally addressed with an alias, the
alias name.
.P
To read this file, you can use the mailer, choosing the 
the \fIchange mailbox\fR command, or start up specifying your
archive file as the mailbox to read.
.sp 2
.H 1 "Using ELM with the Notes System"
.sp
.P
Another feature in the 
.B Elm
program is the ability to read files saved by the notes
system and display them as individual messages.  Unfortunately,
the notes software does not currently save a note with
the subject line, however, so the mailer uses the next best
thing and displays each note in the form:
.nf

    1  Apr 5  hplabs!kundler    Note from group net.unix-wizards
    2  Apr 7  hplabs!richard    Note from group net.unix-wizards

.fi
and so on.  The individual notes can be replied to by using the
.I reply
command, as with normal mail, and the mailer will modify it's
behaviour to work with this particular brand of mail file.
.P
How does the mailer know if it's reading a file that contains
normal mail versus a saved set of notes?  By checking the
first line of the file - if it's the header line that notes
emits
.DS
/***** \fIhost\fR:\fIlogin\fR / \fInotesgroup\fR / \fIdate\fR **/
.DE
then the file is considered to be a notes file.  If not, the default
for unknown files is to assume they're mail files.
.sp 2
.H 1 "The Alias System"
.sp
.P
As mentioned previously, there exists in the
.B Elm
system a set of aliases that associate
an arbitrary word (such as a persons name) to a complex
address or group.  
The advantages are readily apparent; rather than
remembering an address of the form;
.nf

  machine1!machine2!machine3! ... !machineN!account

.fi
the user merely has to remember a single word.  
.P
Two alias tables are available for a each
user within 
.B Elm,
namely the system alias file and the users' alias file.  The
system alias file is created and maintained (by the system administrator)
by editing the file \fI/usr/mail/.alias_text\fR as described
in the documentation with the 
.I newalias
command, then running the 
.I newalias 
program.
.P
An individual user can also have an alias file which works
in conjunction with the system aliases.  To do this, they
need merely to peruse the documentation for the 
.I newalias
command and create a file as indicated therein.  After 
executing the program, the aliases will be available
for using from within 
.B Elm.
.sp
Please refer to the \fIElm Alias Users Guide\fR for more helpful
hints and so on.
.sp 2
Within
.B Elm,
however, the alias system acts as an entirely different program, with
it's own commands and own mini-menu.  The menu replaces the
standard mini-menu with;
.sp
.DS
.nf
.ce
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
.sp
.ce
Alias commands
.sp
.ce 
A)lias current message, Check a P)erson or S)ystem, M)ake new alias or R)eturn
.sp 2
Alias: @
.ce
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
.sp
.DE
.fi
.P 0
The commands are;
.VL 10 3
.LI a
Alias current message.  
This allows the user to create an alias that has the
return address of the current message as the address field of
the alias.  It prompts for a unique alias name.   Important
note: when you alias an address in this fashion, the mailer
will try to minimize the amount it needs to store by
iteratively comparing machine names in the path with the
machines in the pathalias database.  Once it finds an entry
the address will be saved at that point.   For further 
information, please see the \fIElm Alias Users Guide\fR.
.LI p
Check personal alias.  This is a simple way of checking what is in the alias
database - it prompts for an alias name, and returns the address
associated with that name or the error message `alias not found'
as appropriate.  
.LI s
Check system alias.  If you're not sure that your machine can talk
to another machine, you can use this command to either find the
appropriate route or find that you're correct in your suspicions 
and it is indeed unknown!
.LI m
Make user alias.  This will prompt for a unique alias name and
then for an address.  The information provided will be added
to your individual alias_text file (\fI$home/.alias_text\fR) and 
then added to the database.
.LI r
Return.  Return to the main level of the 
.B Elm
program.
.LE
.sp 2
.H 1 "While We're Talking Aliases..."
.P
Another feature worthy of discussion, since it's been getting
lots of veiled references throughout this document, is the 
host-path file.  This is implemented using the uucp pathalias 
database, with a file (whose location is specified in the hdrs/sysdefs.h
file - see the \fIConfiguration Guide\fR) in the format:
.nf

  \fIhostname\fR <tab> \fIaddress\fR!%s

.fi
The actual details of the file are, suprise, suprise, located in 
the \fIAlias System Users Guide\fR.
.P
Anyway, to use them is quite simple...when specifying the address
of someone, you can either have an alias for them already, resond
to their mail to you, or use the system alias feature!
.P
Enough hype, right?  Okay...to use this feature, you specify an
address by either "machine!person" ignoring if your specific
machine can talk directly to the machine specified, or, if you
prefer the Internet addressing scheme, "person at machine".  When
you enter the address as specified, the mailer will quickly
search through the pathalias database file and expand the
specified address to be a legitimate routing address.
.P
What's really nice about this is that the address that we're
going to send to can be either on ARPA, CSNET, BITNET, uucp,
or any other network.  The method of specifying the basic
address is the same regardless!
.P
For example, mail to me could be sent as either "hplabs!taylor"
or "taylor at hplabs".  \fBElm\fR will expand them
both in the same manner and include a ``route'' to the 
machine \fIhplabs\fR, if needed.
.P 0
As the song goes, check the alias guide...
.P
For those sites with the domains database installed, you can
also mail to users on domain based systems by simply specifying
their name, the machine they receive mail on and a full domain
specification.
.P
For example, say you have a friend Maurice who reads mail 
on \s9JOEVAX\s10 in the Mailnet world.  You could mail to him by using
the address "Maurice@\s9JOEVAX.MAILNET\s10" and your system will
expand the address correctly.
.P
Guess where to go for more information...!!
.sp 2
.H 1 "Expert Mail Users and Debugging the Mailer"
.P
There are some additional facilities available in the
.B Elm
mailer for those people who are knowledgable about 
mail protocols, or trying to debug/track down a 
problem.
.P
The `h' \fIheaders\fR command at the outermost level of the mailer
will display the current message ignoring the current
setting of the `weed' option.  This is most useful
for answering questions of the form "I wonder what
this guy put in his header?" and such.  This command
does not show up on the mini-menu because it is somewhat
esoteric, but it does appear on the `?' help screen (can
you find it there, though?).
.P
The `@' command at the outermost level of the mailer
will output a screen of debugging information,
including the number of lines and 
offsets of each of the message in the current mailbox.
.P
The `#' command at the outermost level of the mailer
will display the entire stored `record structure' for
the current message.
.P
The `%' command at the outermost level of the mailer
will display the full computed return address of the
current message.
.P
Starting up 
.B Elm
with the "-d" debug option will create a file called
.I Elm:debug.info
in your home directory and contain a wealth of useful
information (to me, at least!) to aid in tracking down
what errors are occuring and why.  
.sp
.P
If there are any problems with the mailer,  please try
to recreate the error with the debug option enabled
and set to the highest level (9)
before sending defect reports my way.
.sp 3
One final note: all error names reported by the program
are defined in the Bell System V Reference Manual in \fIerrno\fR(2).
END-OF-FILE

if [ "$filename" != "/dev/null" ]
then
  size=`wc -c < $filename`

  if [ $size != 39623 ]
  then
    echo $filename changed - should be 39623 bytes, not $size bytes
  fi

  chmod 644 $filename
fi

echo end of this archive file....
exit 0