From: sources@anomaly.sbs.risc.net
Subject: v01i105 - ELM v2.3.11, Electronic Mail Reader - Part 05/20
Reply-To: sources@anomaly.sbs.risc.net
Organization: The Rhode Island Internet Systems Cooperative Network
Date: Sun, 13 Sep 1992 17:39:12 GMT
Followup-To: biz.sco.general


#!/bin/sh
# this is part.05 (part 5 of a multipart archive)
# do not concatenate these parts, unpack them in order with /bin/sh
# file doc/Ref.guide continued
#
if test ! -r shar3_seq_.tmp; then
	echo "Please unpack part 1 first!"
	exit 1
fi
(read Scheck
 if test "$Scheck" != 5; then
	echo "Please unpack part $Scheck next!"
	exit 1
 else
	exit 0
 fi
) < shar3_seq_.tmp || exit 1
echo "x - Continuing file doc/Ref.guide"
sed 's/^X//' << 'SHAR_EOF' >> doc/Ref.guide &&
Xif entered.  (See also \f2bounce\f1, above.)
X
XElm will ask you if you want to edit the message before sending it.  If you
Xanswer `yes', Elm will prepend your prefix string to each line of the
Xmessage, and let you edit the result.  If you do not want the prefix string
Xon each line, answer `no'; you will have another chance to edit the message
Xwhen you get to the `send' menu.  (See also the `elmrc' section, under
X\f2prefix\f1.)
X
X.lp \h'24p'g 66p
XGroup reply.  Identical to \f2reply\f1 below, except that the
Xresponse is mailed to \f2all recipients\f1 of the original
Xmessage (except yourself \(em see the \f2alternatives\f1
Xoption for your \f2.elm/elmrc\f1 file above).
X
X.lp \h'24p'h 66p
XDisplay the current message with all headers intact.
XWhen you display a message with other commands,
Xcertain header lines are formatted and others discarded (according
Xto the \f2weedlist\fP parameter in your \f2.elm/elmrc\f1 file).
X
X.lp \h'24p'i 66p
XReturn to the index screen,
Xwhen issued in the builtin pager or at the end of a message (with
Xeither the builtin pager or an external pager).
X
X.lp "\h'24p'j or <down>, k or <up>" 66p
XThese four keys work similarly to what they would do in \f2vi\f1 or
Xany of the other (precious few) screen oriented
Xprograms.  The `j' and <down> keys move
Xthe current message pointer down to the next message skipping
Xover any marked deleted (going to
Xthe next page if needed) and the `k' and <up> keys move the current
Xmessage pointer back to the previous message skipping
Xover any marked deleted (also changing pages if needed)
X
X.lp "\h'24p'J, K" 66p
XThese two keys work similarly to their lower case counterparts,
Xexcept that they don't skip over deleted messages.
X
X.lp \h'24p'l 66p
XLimit.  This feature allows you to specify a subset of the existing
Xmessages to be dealt with.  For example, let's say we had a folder with
Xfour hundred messages in it, about four or five different subjects.  We
Xcould then limit what we're dealing with by using the \f2limit\f1
Xcommand.  Pressing `l' would result in the prompt:
X.nf
X.ft CW
X.zf
X.ti +.5i
XCriteria: 
X.ft 1
X.fi
Xto which we could answer 
X.ft CW
X.zf
Xsubject \f2string\f1, 
X.ft CW
X.zf
Xfrom \f2string\f1 or
X.ft CW
X.zf
Xto \f2string\f1.  In our example, we could use 
X.ft CW
X.zf
Xsubject programming\f1
Xas a criteria for selection.  Once we've limited our selections down,
Xthe screen will be rewritten with just the selected messages
Xand the top line will change to have a message
Xlike:
X.nf
X.ft CW
X.zf
X.ps 9
X.tl ''     Folder is "=elm" with 92 shown out of 124 [Elm 2.2]'
X.ps 10
X.ft 1
X.fi
XWe can further limit selections by entering further criteria, each
Xtime using the \f2limit\f1 option again.
X
XTo clear all the criteria and get back to the `regular' display, simply
Xenter \f2all\f1 as the limiting criteria.  It should be noted that the
Xselection based on ``to'' isn't fully implemented for this version, so
Xit is recommended that users stay with ``subject'' and ``from'' as the
Xbasis for their criteria.
X
X.lp \h'24p'm 66p
XMail.  Send mail to a specified user.  The prompt that is associated
Xwith this command is `Send mail to :'.  Entering an alias name results
Xin the full address being rewritten in parenthesis immediately.  This
Xprompt is followed by `Subject:' which allows the user to title their
Xnote.  The final field is `Copies to: ', which allows other people
Xspecified to receive "carbon copies" of the message.  (See the \f2askcc\f1
Xoption of the \f2.elm/elmrc\f1 file above.)  Upon entering all three items the 
Xeditor is invoked and the message can be composed.
X
X.lp \h'24p'n 66p
XNext message that is not marked deleted:
Xuseful for displaying successive messages in a folder.
XWhen issued from the index screen, it displays the current message,
Xand then when issued while in the builtin pager or at the end of a message
X(with either the builtin pager or an external pager),
Xit will display the first screen of the next message not marked for deletion.
X
X.lp \h'24p'o 66p
XOptions.  This full-screen display allows you to alter the settings
Xof a number of parameters, including the current sorting method,
Xthe method of printing files, the calendar file, the save file, and
Xso on.  It's self-documenting (where have you heard \f2that\f1
Xbefore?) so isn't explained in too much detail here.
X
X.lp \h'24p'p 66p
XPrint.  This allows you to print out the current
Xmessage or the tagged messages to a previously defined printer.  (See
Xthe section on the \f2.elm/elmrc\f1 discussing the \f2print\f1 variable.)
X
X.lp \h'24p'q 66p
XQuit.  If you in the pager, you are returned to the index screen. If you are
Xon the index screen, \f2elm\f1 quits altogether.  However, if you have the
Xoption \f2ask\fP set, \f2elm\f1 first prompts you for the disposition of the
Xmessages in the current folder.  If any messages are marked for deletion, it
Xwill ask if you want them deleted.  If the current folder is your incoming
Xmailbox, you will also be asked if read messages should be stored in your
X\f2receivedmail\f1 folder,
Xand if unread messages should be kept in the incoming mailbox.
XThe default answers to these questions are set by the \f2.elm/elmrc\f1
Xoptions \f2alwaysdelete\fP, \f2alwaysstore\fP, and \f2alwayskeep\fP.
XHowever, if you elect to not store your read messages (i.e. keep them)
Xit is presumed you want to keep your unread messages, too.
X
X.lp \h'24p'Q 66p
XQuick quit.  This behaves similar to the `q' command except that
Xyou are never prompted for answers to the message disposition questions.
X\f2Elm\f1 will dispose of messages according to the values you
Xhave set for \f2alwaysdelete\f1, \f2alwaysstore\f1, and \f2alwayskeep\f1
Xin your \f2.elm/elmrc\f1 file.
X
X.lp \h'24p'r 66p
XReply.  Reply to the sender of the current message.  If
Xthe \f2autocopy\f1 flag is OFF in your \f2.elm/elmrc\f1 file, the program will 
Xprompt ``Copy message? (y/n)'' to which the user can specify 
Xwhether a copy of the source message is to be copied into the edit
Xbuffer, or not.  If copied in, all lines from the message are 
Xprepended with the \f2prefix\f1 character sequence specified in
Xyour \f2.elm/elmrc\f1 file.
X
X.lp \h'24p's 66p
XSave to folder.  This command is like the `copy' command, except
Xthat the saved messages are marked for deletion, and that if you are
Xsaving just the current message, the current message pointer is
Xincremented afterwards (see the \f2resolve\f1 option in the \f2.elm/elmrc\f1
Xfile above).  This command expands folder names
Xwith `~' being your home directory and `=' being your
X\f2maildir\f1 directory, if defined.  This command also allows you to
Xuse `>' for your \f2receivedmail\f1 folder and
X`<' for your \f2sentmail\f1 folder.
X
X.lp \h'24p't 66p
XTag.
X.fn
X4. Currently only \f2pipe\f1, \f2print\f1, and \f2save\f1 support this.
X.ef
XTag the current message for a later operation\s-2\u4\d\s0.
X
X.lp \h'24p'<control>-T 66p
XTag all messages containing the specified pattern.  Since \f2tagging\f1
Xmessages can occur on screens other than the one being viewed, the 
X\f2elm\f1 system will first check to see if any messages are currently
X\f2tagged\f1 and ask you if you'd like to remove those tags.  After
Xthat, it will, similar to the \f2<control>-D\f1 function, prompt for
Xa pattern to match and then mark for deletion all messages that contain
Xthe (case insensitive) pattern in either the \f2from\f1 or \f2subject\f1
Xlines. 
X
X.lp \h'24p'x 66p
XExit.  This leaves \f2elm\f1 discarding any changes to the mailbox.
XIf changes are pending (such as messages marked for deletion) a prompt
Xis made to confirm discarding the changes.  If confirmed, no
Xmessages are deleted and the statuses of messages are unchanged.  That is,
Xany messages that were new will remain new instead of being noted as old,
Xand any messages that were read for the first time
Xwill be again noted as unread.
X
X.lp \h'24p'X 66p
XExit immediately.  This leaves \f2elm\f1 in the quickest possible manner
Xwithout even prompting about discarding the changes to the mailbox.
XNo messages are deleted and the statuses of messages are unchanged.  That is,
Xany messages that were new will remain new instead of being noted as old,
Xand any messages that were read for the first time
Xwill be again noted as unread.
X
X.in 0
X.sp
XWhen you are about to send of a message under the \f2forward\f1, \f2mail\f1,
Xor \f2reply\f1 commands (see above), a small menu of the following
Xoptions appears:
X
X.lp \h'24p'c 66p
XSpecify folder for saving a copy to.  This allows you to override the
X\f2copy\f1, \f2forcename\f1 and \f2savename\f1 options
Xof your \f2.elm/elmrc\f1 file.  It prompts you for the name
Xof the folder where a copy of the outgoing message is to be saved.  The
Xdefault displayed is taken from those three \f2.elm/elmrc\f1
Xoptions and can be changed.  This command also allows you to
Xuse `>' for your \f2receivedmail\f1 folder
Xand `<' for your \f2sentmail\f1 folder,
Xand `=?' to mean ``conditionally save by name''
Xand `=' to mean ``unconditionally save by name''. (See the \f2savename\f1
Xoption above for details on saving by name.)  (Since you could next enter
Xthe \f2edit headers\f1 command and change the recipients
Xof your message, the name of the folder under the
Xtwo ``save by name'' options is not established until you enter the \f2send\f1
Xcommand.)  You can also enter `?' at the prompt
Xto list the names of your folders.
X
X.lp \h'24p'f 66p
XForget.  This gets you out of sending a message you started. If you are
Xin send-only mode, the message is saved to the file \f2Cancelled.mail\f1
Xin your home directory.  Otherwise 
Xit can be restored at the next \f2forward\f1, \f2mail\f1,
Xor \f2reply\f1 command during the current session of \f2elm\f1. After
Xissuing one of those commands you will be prompted with ``Recall last
Xkept message?''
X
X.lp \h'24p'e 66p
XEdit message (or form).  Entering this command will allow you to edit
Xthe text of your message or form.
X
X.lp \h'24p'h 66p
XEdit headers.  This puts you into the \f2header editing mode\f1, whereby
Xyou can edit to any of the various headers of your message.  Like
Xthe options screen, it's self-documenting, so it isn't explained in too much
Xdetail here.
X
X.lp \h'24p'm 66p
XMake form.  This converts the message you have edited into a form.  (See
X\f2The Elm Forms Mode Guide\f1 for more details.)
X
X.lp \h'24p's 66p
XSend.  This sends the message as is without any further ado.
X.in 0
X.br
X.ne 5
X.sp
X.hn 1 "Using Elm with ``editor = none''"
X.sp
XThe \f2Elm\f1 program also supports a builtin editor for simple message 
Xcomposition that is very (very) similar to the simple line
Xeditor available from the \f2Berkeley Mail\f1 system.
X
XTo access it, you need merely to specify ``\f2editor=none\f1'' in
Xyour \f2.elm/elmrc\f1 file.  
XWith that, any messages to be composed
Xthat don't already have text in the buffer (e.g. no reply with
Xthe text included, etc), will use this editor.
X.sp
XFrom the builtin editor, the following options are available for use.
XEach command here is prefixed with a `~'.
XYou can specify a different ``escape'' character in your \f2.elm/elmrc\f1 file,
Xif you desire (see above).
X.sp
X
X.lp \h'16p'~? .5i
XPrint a brief help menu.
X
X.lp \h'16p'~b .5i
XChange the Blind-Carbon-Copy list.
X
X.lp \h'16p'~c .5i
XChange the Carbon-Copy list.
X
X.lp \h'16p'~e .5i
XInvoke the Emacs editor on the message, if possible.
X
X.lp \h'16p'~f .5i
XAdd the specified message or current message.
X
X.lp \h'16p'~h .5i
XChange all the available headers (To, Cc, Bcc, and Subject).
X
X.lp \h'16p'~m .5i
XSame as `~f', but with the current `prefix'.
X
X.lp \h'16p'~o .5i
XInvoke a user specified editor on the message.
X
X.lp \h'16p'~p .5i
XPrint out the message as typed in so far.
X
X.lp \h'16p'~r .5i
XInclude (read in) the contents of the specified file.
X
X.lp \h'16p'~s .5i
XChange the Subject line.
X
X.lp \h'16p'~t .5i
XChange the To list.
X
X.lp \h'16p'~v .5i
XInvoke the Vi visual editor on the message.
X
X.lp \h'16p'~< .5i
XExecute the specified unix command, entering the output
Xof the command into the editor buffer upon completion.
X(For example ``~< who'' will include the output of
Xthe \f2who\f1 command in your message.)
X
X.lp \h'16p'~! .5i
XExecute a unix command if one is given (as in ``~!ls'') or
Xgive the user a shell (either from their shell setting in 
Xtheir \f2.elm/elmrc\f1 file or the default).
X
X.lp \h'16p'~~ .5i
XAdd a line prefixed by a single `~' character.
X.in 0
X.sp
XA useful note is that the `~f' and `~m' commands invoke the \f2readmsg\f1
Xcommand, so you can pass parameters along too.  For example, if we
Xwanted to include a message from Joe, without any headers, prefixed,
Xwe could use:
X.nf
X.ti .5i
X~m -n Joe
X.fi
Xto accomplish the task.
X
XTo learn more about how they work, try 'em!
X.br
X.ne 5
X.sp
X.hn 1 The Alias System
X.sp
XAs mentioned previously, there exists in the \f2elm\f1
Xsystem a set of aliases that associate
Xan arbitrary word (such as a persons name) to a complex address or group.  
XThe advantages are readily apparent; rather than
Xremembering an address of the form:
X.nf
X.ps 9
X.ft CW
X.zf
X.ti .5i
Xhost1!host2! ... !hostN!user
X.ft 1
X.ps 10
X.fi
Xthe user merely has to remember a single word.  
X
XTwo alias tables are available for a each
Xuser within \f2elm\f1,
Xnamely the system alias file and the user's alias file.  The
Xsystem alias file is created and maintained (by the system administrator)
Xby editing the 
Xfile \f2SYSTEM_ALIASES\f1 as defined in the `sysdefs.h' file
X(see \f2The Elm Configuration Guide\f1) and as described
Xin the documentation with the \f2newalias\f1 command,
Xthen running the \f2newalias\f1 program.
X
XAn individual user can also have an alias file which works
Xin conjunction with the system aliases.  To do this, they
Xneed merely to peruse the documentation for the \f2newalias\f1
Xcommand and create a file as indicated therein.  After 
Xexecuting the program, the aliases will be available
Xfor using from within \f2elm\f1.
X.sp
XPlease refer to \f2The Elm Alias Users Guide\f1 for more helpful
Xhints and so on.
X.sp 2
XWithin \f2elm\f1,
Xhowever, the alias system acts as an entirely different program, with
Xit's own commands and own mini-menu.  The menu replaces the
Xstandard mini-menu with:
X.sp
X.sd
X.nf
X.ps 9
X.ft CW
X.zf
X.ce
X--------------------------------------------------------------------------------
X.sp
X.ce
XAlias commands
X.sp
X.ce 2
Xa)lias current message, d)elete an alias, check a p)erson or s)ystem,
Xl)ist existing aliases, m)ake new alias or r)eturn
X.sp 2
XAlias: @
X.ce
X--------------------------------------------------------------------------------
X.sp
X.ps 10
X.ft 1
X.ed
X.fi
X
XThe commands are:
X
X.lp \h'16p'a .5i
XAlias current message.  
XThis allows the user to create an alias that has the
Xreturn address of the current message as the address field of
Xthe alias.  It prompts for a unique alias name.   Important
Xnote: when you alias an address in this fashion, the mailer
Xwill try to minimize the amount it needs to store by
Xiteratively comparing machine names in the path with the
Xmachines in the pathalias database.  Once it finds an entry
Xthe address will be saved at that point.   For further 
Xinformation, please see \f2The Elm Alias System Users Guide\f1.
X
X.lp \h'16p'd .5i
XDelete an existing alias.
XThis allows the user to delete an alias the user has previously made.
XIt prompts for the alias name, and displays the alias information, if
Xfound, and then prompts for confirmation to delete.
X
X.lp \h'16p'l .5i
XList all existing aliases.
XThis simply lists all the aliases you have previously made.
X
X.lp \h'16p'm .5i
XMake user alias.  This will prompt for a unique alias name and
Xthen for an address.  The information provided will be added
Xto your individual aliases.text file (\f2$HOME/.elm/aliases.text\f1) and 
Xthen added to the database.
X
X.lp \h'16p'p .5i
XCheck personal alias.  This is a simple way of checking what is in the alias
Xdatabase \(em it prompts for an alias name, and returns the address
Xassociated with that name or the error message `alias not found'
Xas appropriate.  
X
X.lp \h'16p'r .5i
XReturn.  Return to the main level of the \f2elm\f1 program.
X
X.lp \h'16p's .5i
XCheck system alias.  If you're not sure that your machine can talk
Xto another machine, you can use this command to either find the
Xappropriate route or find that you're correct in your suspicions 
Xand it is indeed unknown!
X.in 0
X.br
X.ne 5
X.sp
X.hn 1 While We're Talking Aliases...
X
XAnother feature worthy of discussion, since it's been getting
Xlots of veiled references throughout this document, is the 
Xhost-path file.  This is implemented using the uucp pathalias 
Xdatabase, with a file containing lines with the format:
X.nf
X.ti .5i
X\f2hostname\f1        \f2address\f(CW!%s\f1
X  or
X.ti .5i
X\f2hostname\f1        \f(CW%s@\f2hostname\f1
X.fi
XThe actual details of the file are located in 
X\f2The Alias System Users Guide\f1.
X
XAnyway, to use them is quite simple...when specifying the address
Xof someone, you can either have an alias for them already, reply
Xto their message, or use the system alias feature!
X
XEnough hype, right?  Okay...to use this feature, you specify an
Xaddress by either "machine!person" ignoring if your specific
Xmachine can talk directly to the machine specified, or, if you
Xprefer the Internet addressing scheme, "person@machine".  When
Xyou enter the address as specified, the mailer will quickly
Xsearch through the pathalias database file and expand the
Xspecified address to be a legitimate routing address.
X
XWhat's really nice about this is that the address that we're
Xgoing to send to can be either on ARPA, CSNET, BITNET, uucp,
Xor any other network.  The method of specifying the basic
Xaddress is the same regardless!
X
XFor example, mail to me could be sent as either "hplabs!taylor"
Xor "taylor@hplabs".  \f2elm\f1 will expand them
Xboth in the same manner and include a ``route'' to the 
Xmachine \f2hplabs\f1, if needed.
X
XFor those sites with the domains database installed, you can
Xalso mail to users on domain based systems by simply specifying
Xtheir name, the machine they receive mail on and a full domain
Xspecification.
X
XFor example, say you have a friend Maurice who reads mail 
Xon \s9JOEVAX\s10 in the Mailnet world.  You could mail to him by using
Xthe address "Maurice@\s9JOEVAX.MAILNET\s10" and your system will
Xexpand the address correctly.
X.br
X.ne 5
X.sp
X.hn 1 Expert Mail Users and Debugging the Mailer
X
XThere are some additional facilities available in the \f2elm\f1
Xmailer for those people who are knowledgeable about 
Xmail protocols, or trying to debug/track down a problem.
X
XThe `h' \f2headers\f1 command at the outermost level of the mailer
Xwill display the current message ignoring the current
Xsetting of the `weed' option.  This is most useful
Xfor answering questions of the form "I wonder what
Xthis guy put in his header?" and such.  This command
Xdoes not show up on the mini-menu because it is somewhat
Xesoteric, but it does appear on the `?' help screen (can
Xyou find it there, though?).
X
XThe `@' command at the outermost level of the mailer
Xwill output a screen of debugging information,
Xincluding the number of lines and 
Xoffsets of each of the messages in the current mailbox.
X
XThe `#' command at the outermost level of the mailer
Xwill display the entire stored `record structure' for
Xthe current message.
X
XThe `%' command 
Xwill display the full computed return address of the
Xcurrent message.
X
XStarting up \f2elm\f1 with the "-d" debug option will create a file called
X\f2ELM:debug.info\f1 in your home directory and contain a wealth of useful
Xinformation (to me, at least!) to aid in tracking down
Xwhat errors are occurring and why.  
X.sp
X
XIf there are any problems with the mailer,  please try
Xto recreate the error with the debug option enabled
Xand set to the highest level (11) before sending defect reports my way.
X.sp 3
XOne final note: all error names reported by the program
Xare documented in the AT&T System V Interface Definition Reference 
XManual in \f2errno\f1(2).
SHAR_EOF
echo "File doc/Ref.guide is complete" &&
# ============= doc/Users.guide ==============
echo "x - extracting doc/Users.guide (Text)"
sed 's/^X//' << 'SHAR_EOF' > doc/Users.guide &&
X.\" @(#)$Id: Users.guide,v 4.1.1.1 90/06/09 22:49:54 syd Exp $
X.\"
X.\"  Users guide to the ELM mail system.
X.\"  format with:
X.\"	'tbl Users.guide | troff tmac.n - > Users.fmtd'
X.\"
X.\"  Elm is now in the public trust. Bug reports, comments, suggestions, flames
X.\"  etc. should go to:
X.\"	Syd Weinstein		elm@DSI.COM (dsinc!elm)
X.\"
X.\"  (C) Copyright 1986, 1987 Dave Taylor
X.\"  (C) Copyright 1988, 1989, 1990 Usenet Community Trust
X.\"
X.\"  $Log:	Users.guide,v $
X.\" Revision 4.1.1.1  90/06/09  22:49:54  syd
X.\" Droped obsolete control Q command from list
X.\" From: Joe Wasik
X.\" 
X.\" Revision 4.1  90/04/28  22:41:16  syd
X.\" checkin of Elm 2.3 as of Release PL0
X.\" 
X.\"  
X.tm I trust we've run this through "tbl" first...
X.\"  Define the big box macro for troff
X.de eb
X.sp -1	
X.nf
X.ie t \{\
X\h'-.5n'\L'|\\nau-1'\l'\\n(.lu+1n\(ul'\L'-|\\nau+1'\l'|0u-.5n\(ul'
X.\}
X.el \{\
X\h'-.5n'\l'\\n(.lu+1n'
X.\}
X.fi
X..
X.po 1i
X.ds h0
X.ds h1
X.ds h2
X.ds f0
X.ds f1
X.ds f2
X.nr Hy 1
X.nr Pt 1
X.nr Pi 0
X.lg 0
X.nf
X.na
X.rs
X.za
X.\" This will keep the nroff version of the title page on one sheet.
X.if t .sv |2.0i
X.ce 99
X.ps 20
X.ss 18
X.vs 12
X\f3The Elm Users Guide\f1
X.sp 3
X.ps 12
X.ss 14
X.vs 14
X\f2A painless introduction to electronic mail 
Xusing the \f3Elm\fP mail system\f1
X.sp 2
XDave Taylor
X.sp 
XHewlett-Packard Laboratories
X1501 Page Mill Road
XPalo Alto CA
X94304
X.sp 3
Xemail: taylor\s10@\s12hplabs.HP.COM or hplabs!taylor
X.sp 3
X>>> Elm is now in the public trust. Bug reports, comments, etc. to: <<<
X.sp
XSyd Weinstein
XDatacomp Systems, Inc.
X3837 Byron Road
XHuntingdon Valley, PA 19006-2320
X.sp
Xemail: elm\s-1@\s+1DSI.COM  or  dsinc\s-1!\s+1elm
X.fi
X.ad
X.ps 8
X.if t .vs 9
X.sp 4
X\f3ABSTRACT\f1
X.ce 0
X.sp
X.in +1i
X.ll -1i
XWhile various Unix utilities have been designed to
Xtake advantage of the CRT screen
X(rather than line-oriented systems)
Xelectronic mail systems haven't ``caught the wave''.
XThis document 
Xpresents \f2Elm\f1, a sophisticated
Xfull-screen mail system for interactive use.
X\f2Elm\f1 offers all the features of
X\f2/bin/mail\f1, \f2Berkeley Mail\f1, \f2uumail\f1, \f2NMail\f1 and
Xthe AT&T Mail family of Unix mailers (namely \f2PMX/TERM\f1) in a
Xunified and intuitive fashion.
X.ll +1i
X.in -1i
X.if t .sp 3
X.if n .sp 2
X.ce 2
X.ps 18
X.if t .vs 14
X\f3\(co\f1\s12 Copyright 1986, 1987 by Dave Taylor
X.ps 18
X\f3\(co\f1\s12 Copyright 1988, 1989, 1990 by The USENET Community Trust
X.ps 10
X.ss 12
X.vs 12
X.bp 1
X.sv 5v
X.ce 99
X.ps 14
X\f3Elm Users Guide\f1
X.ds h0 "Elm Users Guide
X.ds h1
X.ds h2 "Version 2.3
X.ds f0 "May 1, 1990
X.ds f1 "Page %
X.ps 10
X.sp
X(Version 2.3)
X.sp 2
XDave Taylor
XHewlett-Packard Laboratories
X1501 Page Mill Road
XPalo Alto CA
X94304
X.sp
Xemail:  taylor\s-1@\s+1hplabs.HP.COM  or  hplabs\s-1!\s+1taylor
X.sp 2
X>>> Elm is now in the public trust. Bug reports, comments, etc. to: <<<
X.sp
XSyd Weinstein
XDatacomp Systems, Inc.
X3837 Byron Road
XHuntingdon Valley, PA 19006-2320
X.sp
Xemail: elm\s-1@\s+1DSI.COM  or  dsinc\s-1!\s+1elm
X.sp 2
XMay 1, 1990
X.ce 0
X.sp 3
X.hn 1 Introduction
X
XThe
X.ux
Xoperating system was originally written on a small PDP machine,
Xto work with teletypewriters.  Consequently, all the original software for
Xthe operating system was written with a `tty' in mind; 
Xwith line oriented interfaces, rather than screen oriented.
X
XGradually this began to change, and, with the addition of the Berkeley \f2vi\f1
Xvisual shell to the \f2ed\f1
Xline editor, the trend began to be brought to the attention of 
XUnix systems designers.  
XAnd yet, this transition has seemed
Xtoo subtle for many software engineers,
Xand so precious few Unix programs are available 
Xdesigned to exploit the entire CRT screen.
X
XConsequently, after becoming more and more disenchanted
Xwith the existing electronic mail facilities (\f2binmail\f1
Xand \f2Berkeley Mail\f1)
XI decided to undertake creating my own system.  
XOnce the ball was rolling it became quite
Xdifficult not to keep enhancing it, especially as I
Xbecame more and more familiar with various different mail
Xsystems, but the result, I hope, is a solid, unified interface
Xto electronic mail suitable for almost any environment.
X
XOne thing that sets \f3The Elm Mail System\f1 off from
Xother packages is that it
Xcomes with an extensive documentation set, including;
X\f2The Elm Users Guide\f1, which you're holding,
X\f2The Elm Reference Guide\f1, 
X\f2The Elm Alias Users Guide\f1,
X\f2The Elm Filter System Users Guide\f1,
X\f2The Elm Forms Mode Guide\f1, 
Xand \f2The Elm Configuration Guide\f1.  
XThe names of each indicate
Xwhat they discuss (not unreasonably).
X
XThis particular document contains;
Xthis introduction, a tutorial session with the mailer, a
Xdiscussion of non-interactive uses of \f3Elm\f1,
Xa brief foray into the \f3Elm\f1 utilities,
Xand finally, credits and references.
X
X\f2The Elm Reference Guide\f1 contains a
Xmuch more indepth discussion of all the possible options
Xavailable within the \f3Elm\f1 environment, including
Xthe \f2``.elm/elmrc''\f1 file,
Xthe available outbound mail processing features,
Xa section for expert users, suggestions
Xon debugging strange installations, and
Xmany other useful topics.
X
X\f2The Elm Alias Users Guide\f1 is the place
Xto go to learn about the format of the 
X``.elm/aliases.text''
Xfile and the associated data files, to learn how
Xto create and use path route aliases and domain
Xbased alias routing, system aliases, and other
Xrelated topics.
X
XOne of the more innovative features of \f3Elm\f1 is
Xthe ability to transmit and receive ``forms'' (as
Xdefined by the AT&T Mail system).  To learn about
Xhow to create and reply to forms you should refer
Xto \f2The Elm Forms Mode Guide\f1.
X
XIf you find yourself getting too much mail delivered in
Xyour mailbox, you might be a good candidate for the
X\f2filter\f1 program.  To learn more about what
Xthis program is and how to use it please
Xconsult \f2The Elm Filter System Users Guide\f1.
X
XFinally, if you're working with the actual source code
Xand are interested in what all the locally configured
Xoptions are and mean, please see
X\f2The Elm Configuration Guide\f1.  It is
Xstrongly suggested that all system administrators
Xand people installing the system print out the
Xlocal ``sysdefs.h'' file and have it handy while
Xreading the configuration guide.
X
XThe recommended order of learning the \f3Elm\f1
Xsystem is to skim this guide until you feel
Xconfident enough to start up the program.  Once
Xthat's reached, \f2use it!\f1  Soon you'll find
Xareas that you need to expand into, and you can
Xachieve that by going into the \f2o)ptions\f1
Xscreen within \f2elm\f1 and changing your
Xuser level accordingly.
XAfter a while, sit down again and read through this
Xguide.  You should have a couple of ``aha!'' intuitive
Xflashes.  After another period of time, you're
Xready to delve into the real power of the system
Xand read the reference guide.  The other manuals
Xshould be read as the need arises.
X
XIn any case, the system should be useable without reading
X\f2any\f1 of the documentation!
X
XAny comments or problems with any of the documentation or the program
Xitself are welcome; if you can't get electronic mail to me, please
Xfeel free instead to drop me a note via the overland mail address
Xin the title page.  
X.br
X.ne 20
X.sp 
X.hn 1 The Main System
X
XUpon entry to the program, the main screen will be 
Xdisplayed as below;
X
X.\" display start, constant width, remember loc for BOX
X.ft CW
X.zf
X.ps 9
X.mk a
X.mk a
X.sp
X.ce
XMailbox is '/usr/mail/mymail' with 15 messages  [Elm 2.2]
X.TS
Xr l n l l l l.
X ->	N	1	Apr 24	Larry Fenske	(49)	Hello there
X	N	2	Apr 24	jad@hpcnoe	(84)	Chico?  Why go there?
X	E	3	Apr 23	Carl Smith	(53)	Dinner tonight?
X	NU	4	Apr 18	Don Knuth	(354)	Your version of TeX...
X	N	5	Apr 18	games	(26)	Bug in cribbage game
X	 A	6	Apr 15	kevin	(27)	More software requests
X		7	Apr 13	John Jacobs	(194)	How can you hate RUSH?
X	 U	8	Apr 8	decvax!mouse	(68)	Re: your Usenet article
X		9	Apr 6	root	(7)
X	O	10	Apr 5	root	(13)
X.TE
X.sp
X.ce 3
XYou can use any of the following commands by pressing the first character;
Xd)elete or u)ndelete mail, m)ail a message, r)eply or f)orward mail, q)uit
XTo read a message, press <return>.  j = move down, k = move up, ? = help
X Command : @
X.sp 
X.\" draw box, proportional Roman font back, display end
X.eb
X.ps 10
X.ft 1
X
XThere are a number of things to notice about this, the main screen;
X
X.lp \h'12p'\(bu 20p
XMost likely, on your computer the message currently ``active'' will be
Xdisplayed in an inverse bar rather than being delimited by the two
Xcharacter arrow as here.  It's nothing to worry about; displaying
Xinverse video is just quite difficult on printable guides!
X
X.lp \h'12p'\(bu 20p
XThe first line on the screen always displays the name of the current folder,
Xthe number of messages in the folder, and the current \f3Elm\f1 version number.
X
X.lp \h'12p'\(bu 20p
XThe arrow (``->'') or inverse video bar will always
Xindicate which is the current message.  
X
X.lp \h'12p'\(bu 20p
XThe first field that appears associated with each message is
Xthe status field.  This can be blank (as with most of the
Xones above, or can have any combination of the following:
X
XThe first character signifies temporary status:
X
X.ta .75iC 102p
X.nf
X	E	for an \f2expired\f1 message
X	N	for a \f2new\f1 message
X	O	for an \f2old\f1 (i.e. not new but not read) message
X	D	for a \f2deleted\f1 message
X
XThe second character which signifies permanent status:
X
X	U	for \f2urgent\f1 mail
X	A	for messages that have an \f2action\f1 associated with them
X	F	for a \f2form\f1 letter
X.fi
X
XThe third character of the status field can be a ``+'' to
Xindicate that the message is \f2tagged\f1 too.
X
X.lp \h'12p'\(bu 20p
XContinuing from left to right, the next field is the message
Xnumber.  For the most part you can ignore these unless you want
Xto quickly move to a specific message (as we'll see later).
X
X.lp \h'12p'\(bu 20p
XThe date associated with each message is typically
Xthe date the person actually \f2sent\f1 the message.  
X
X.lp \h'12p'\(bu 20p
XThe next field displayed indicates whom the message is from.  
X\f3Elm\f1 will try to display the \f2full name\f1 of the person who 
Xsent the message, rather than the their return address or computer login.  
XSome systems don't generate the correct headers, though, hence 
Xmessages like numbers 2 and 8, where it's their return address.
X
X.lp \h'12p'\(bu 20p
XThe number in parentheses is the total number of lines in the message.
X
X.lp \h'12p'\(bu 20p
XThe final field is the subject of the message.  Notice
Xthat messages might not have any subject, as in messages #9 and #10.
X
X.lp \h'12p'\(bu 20p
XA maximum of ten messages are displayed at one time\s-2\u1\d\s0.
X.fn
X1. On screens with greater than 25 lines, more messages will be 
Xdisplayed automatically.  Further, if you choose to turn off
Xthe Menu display, you can have an even greater number 
Xdisplayed.
X.ef
XFurther into the document we'll learn how to change ``pages'' in the folder. 
X
X.lp \h'12p'\(bu 20p
XThe three line Menu display will always 
Xindicate the relevant commands.  There are actually two possible 
Xmenus that can be displayed, based
Xon the \f2user level\f1 as set from either the o)ptions screen or
Xthe \f2.elm/elmrc\f1 
Xfile.  The alternate menu, for more advanced users, 
Xlists more options;
X.sp
X.ft CW
X.zf
X.ps 9
X.ce 3
X|=pipe, !=shell, ?=help, <n>=set current to n, /=search pattern
Xa)lias, C)copy, c)hange folder, d)elete, e)dit, f)orward, g)roup reply, m)ail, 
Xn)ext, o)ptions, p)rint, r)eply, s)ave, t)ag, q)uit, u)ndelete, or e(x)it
X.ps 10
X.ft 1
X
X.lp \h'12p'\(bu 20p
XFinally, the '@' character indicates where the cursor would be, awaiting
Xyour input.
X
X.sp
X.in 0
XThe typical action at this point is to use the \f2<return>\f1
Xkey to read the current message, which will clear the 
Xscreen and display the current message:
X
X.ne 10
X.ft CW
X.zf
X.ps 9
X.mk a
X.tl ' Message 1/15 from Larry Fenske''Apr 24 \'87 at 8:45 pm'
X.tl ''Hello there''
X.nf
X Dave, 
X      Just wanted to drop you a brief note to see what was going on with 
X you this afternoon.  Life here has been the usual fun and games...
X	     Ah well, off to the great wilds beyond the desk!
X				Larry
X Command ('i' to return to index): @
X.fi
X.eb
X.ft 1
X.ps 10
X
XBefore we go further with our example, however, let's very
Xquickly look at all the functions available from the main
Xscreen:
X.\" ensure we get a reasonable chunk of this table on the page...
X.br
X.ne 10
X.lp \h'18p'\f3Command 90p
XAction\f1
X
X.lp "\h'18p'<return> or <space>" 90p
XRead current message.
X.lp \h'18p'| 90p
XPipe current message or tagged messages to specified system command.
X.lp \h'18p'! 90p
XShell escape.
X.lp \h'18p'$ 90p
XResynchronize folder.
X.lp \h'18p'? 90p
XHelp mode \(em any key pressed will be explained.
X.lp "\h'18p'+ or <right>" 90p
XDisplay next page of headers.
X.lp "\h'18p'- or <left>" 90p
XDisplay previous page of headers.
X.lp \h'18p'= 90p
XSet current message to 1.
X.lp \h'18p'* 90p
XSet current to last message.
X.lp \h'18p'<number><return> 90p
XSet current message to number \f2number\f1.
X.lp \h'18p'/ 90p
XSearch for pattern in subject/from lines.
X.lp \h'18p'// 90p
XSearch for pattern in entire folder.
X.lp \h'18p'< 90p
XScan message for calendar entries.\s-2\u2\d\s0
X.fn
X2. Some sites might opt not to have the calendar feature available.
X.ef
X.lp \h'18p'> 90p
XA synonym for `s' \(em \f2save\f1 message or messages.
X.sp
X.lp \h'18p'a 90p
XAlias, change to ``alias'' mode.
X.lp \h'18p'b 90p
XBounce \(em remail message [see \f2f \(em forward\f1 too].
X.lp \h'18p'C 90p
XCopy current message or tagged messages to folder.
X.lp \h'18p'c 90p
XChange to another folder.
X.lp \h'18p'd 90p
XDelete current message.
X.lp \h'18p'<control>-D 90p
XDelete all messages matching specified pattern.
X.lp \h'18p'e 90p
XEdit current folder, resyncing upon reentry.\s-2\u3\d\s0
X.fn
X3. Some sites might opt not to have the edit folder feature available.
X.ef
X.lp \h'18p'f 90p
XForward message to specified user.\s-2\u4\d\s0
X.fn
X4. The difference between \f2Forward\f1 and \f2Bounce\f1 is rather 
Xsubtle \(em a forwarded message is ``from'' you, with the
Xoriginal message included, whereas a bounced message
Xis still from the original sender.  
X.ef
X.lp \h'18p'g 90p 
XGroup reply \(em reply to everyone who received the current message.
X.lp \h'18p'h 90p
XDisplay message with headers.
X.lp \h'18p'J 90p
XSet current to next message.
X.lp "\h'18p'j or <down>" 90p
XSet current to next message not marked deleted.
X.lp \h'18p'K 90p
XSet current to previous message.
X.lp "\h'18p'k or <up>" 90p
XSet current to previous message not marked deleted.
X.lp \h'18p'l 90p
XLimit displayed messages based on the specified criteria.  
X.lp \h'18p'<control>-L 90p
XRewrite screen.
X.lp \h'18p'm 90p
XMail to arbitrary user(s).
X.lp \h'18p'n 90p
XRead current message, then increment to next message not marked deleted.
X.lp \h'18p'o 90p
XAlter current system options.
X.lp \h'18p'p 90p
XPrint current message or tagged messages.
X.lp \h'18p'q 90p
XQuit \(em maybe prompting for messages to delete, store, or keep.
X.lp \h'18p'Q 90p
XQuick quit \(em like quit but without prompting.
X.lp \h'18p'r 90p
XReply to the author of current message.
X.lp \h'18p's 90p
XSave current message or tagged messages to folder.
X.lp \h'18p't 90p
XTag current message.
X.lp \h'18p'<control>-T 90p
XTag all messages matching specified pattern.
X.lp \h'18p'u 90p
XUndelete current message.
X.lp \h'18p'<control>-U 90p
XUndelete all messages matching specified pattern.
X.lp \h'18p'x 90p
XExit \(em prompt if mailbox changed, don't record as read, don't save...
X.lp \h'18p'X 90p
XExit immediately \(em don't record as read, don't save...
X.in 0
X.\" again, make sure we start on a new page please
X.br
X.ne 10
XBut let's go back to our example and see some of this at
Xwork, shall we?
X.sp
XWe were reading the message from Larry and the screen looked
Xlike:
X
X.ne 10
X.ft CW
X.zf
X.ps 9
X.mk a
X.tl ' Message 1/15 from Larry Fenske''Apr 24 \'87 at 8:45 pm'
X.tl ''Hello there''
X.nf
X Dave, 
X      Just wanted to drop you a brief note to see what was going on with 
X you this afternoon.  Life here has been the usual fun and games...
X	      Ah well, off to the great wilds beyond the desk!
X				Larry
X Command ('i' to return to index): @
X.fi
X.eb
X.ft 1
X.ps 10
X
XFrom this point let's go ahead and reply to the message.  To
Xdo this, we can use the \f2reply\f1 command...
XTo do this, we type ``r'' and the last few lines change to
Xsomething like:
X.ft CW
X.zf
X.ps 9
X.sp 
X.tl '-------------------------------------------------------------------------------''
X.tl 'Command: Reply to message''Copy message (y/n) ? @ '
X.sp 2
X.ft 1
X.ps 10
XTo which we decide that we don't need the text of this message in 
Xour new one, so we reply \f2no\f1 by pressing the ``n'' key.  The
Xbottom part of the window then changes to:
X.ft CW
X.zf
X.ps 9
X.sp
X.tl '-------------------------------------------------------------------------------''
X.tl 'Command: Reply to message''To: Larry Fenske '
X.tl 'Subject: Re: Hello there@''
X.ft 1
X.ps 10
X.sp 2
Xat this point we can either decide to enter a new subject (you could
Xuse either \f2backup word\f1 (<control>-W) or \f2backup line\f1 (this
Xis the same as your `line kill' character, <control>-X or <control>-U
Xusually)) or go with this one by pressing \f2<return>\f1.  We'll
Xjust leave it as it is and press \f2<return>\f1, changing the
Xscreen to:
X.ps 9
X.ft CW
X.zf
X.sp
X.tl '-------------------------------------------------------------------------------''
X.tl 'Command: reply to message''To: Larry Fenske '
X.tl 'Subject: Re: Hello there''
X.tl 'Copies to: @'''
X.ps 10
X.ft 1
X.sp 
XThere's no one we want to have receive copies of this message, so we'll
Xjust press \f2<return>\f1 again to indicate this.  
X
XOnce you've answered these questions the program will put you into
Xyour favorite editor and let you compose a response.  When you're
Xdone it then asks:
X.ps 9
X.ft CW
X.zf
X.sp
X.tl ''-------------------------------------------------------------------------------''
X.tl 'Please choose one of the following options by parenthesized letter: @'''
X.tl ''e)dit message, edit h)eaders, s)end it, or f)orget it.''
X.ft 1
X.ps 10
X.sp
XSince we're just interested in sending the message out, we'll
Xchoose the \f2send\f1 option and press ``s''.  The program
Xthen sends the message, indicating that by the line below
Xsaying:
X.sp
X.ps 9
X.ft CW
X.zf
X    Sending mail...
X.ft 1
X.ps 10
X.sp
Xthen putting at the bottom of the screen ``Mail sent!'' and giving us
Xthe prompt:
X.ps 9
X.ft CW
X.zf
X.sp
X.tl ''-------------------------------------------------------------------------------''
X.tl 'Command:''(Use \'i\' to return to index.)''
X.sp
X.ps 10
X.ft 1
XPretty easy, isn't it?  Let's continue by going back to the main
Xscreen by requesting \f2index\f1: pressing the ``i'' key.  The
Xscreen is then:
X
X.ne 20
X.ft CW
X.zf
X.ps 9
X.mk a
X.mk a
X.sp
X.ce
XMailbox is '/usr/mail/mymail' with 15 messages  [Elm 2.2]
X.TS
Xr l r l l l l.
X ->		1	Apr 24	Larry Fenske	(49)	Hello there
X	N	2	Apr 24	jad@hpcnoe	(84)	Chico?  Why go there?
X	E	3	Apr 23	Carl Smith	(53)	Dinner tonight?
X	NU	4	Apr 18	Don Knuth	(354)	Your version of TeX...
X	N	5	Apr 18	games	(26)	Bug in cribbage game
X	 A	6	Apr 15	kevin	(27)	More software requests
X		7	Apr 13	John Jacobs	(194)	How can you hate RUSH?
X	 U	8	Apr 8	decvax!mouse	(68)	Re: your Usenet article
X		9	Apr 6	root	(7)
X	O	10	Apr 5	root	(13)
X.TE
X.sp
X.ce 3
XYou can use any of the following commands by pressing the first character;
Xd)elete or u)ndelete mail, m)ail a message, r)eply or f)orward mail, q)uit
XTo read a message, press <return>.  j = move down, k = move up, ? = help
X Command : @
X.sp 
X.\" draw box, proportional Roman font back, display end
X.eb
X.ft 1
X.ps 10
X
X.ft 1
XNotice that the first message is no longer marked as \f2new\f1
Xsince we've now read it.
X.sp
XLet's go ahead and read the message from kevin (message #6) since
Xit has some sort of \f2action\f1 associated with it anyway.  To
Xdo this, we simply press the ``6'' key, which will change the
Xbottom of the screen to:
X.sp
X.ps 9
X.ft CW
X.zf
X.tl 'Command: New Current Message''Set current message to : 6@'
X.ft 1
X.ps 10
X.sp
XWe'll just press \f2<return>\f1 to move the active message
Xpointer (the arrow).
X.sp
XNow we're pointing at the new message, so let's go ahead and read
Xit by pressing \f2<return>\f1 again, giving us:
X
X.ne 10
X.ft CW
X.zf
X.ps 9
X.mk a
X.tl ' Message 6/15 from kevin''Apr 15 \'87 at 11:36 am'
X.tl ''More software requests''
X Action: please acknowledge receipt
X I don't suppose you have a nifty netnews reader around too, do you??
X --
X kevin
X Command ('i' to return to index): @
X.eb
X.sp
X.ps 10
X.ft 1
X
X.br
X.ne 5
XWell, it turns out that we don't, but a friend of ours does, so
Xlet's \f2forward\f1 the message to them by pressing ``f'':
X.ps 9
X.ft CW
X.zf
X.sp
X.tl '-------------------------------------------------------------------------------''
X.tl 'Command: Forward message''Edit outgoing message (y/n) ? @ '
X.ft 1
X.ps 10
X.sp 2
XNo need to edit it, so let's answer \f2no\f1 with ``n'':
X.sp
X.ps 9
X.ft CW
X.zf
X.tl '-------------------------------------------------------------------------------''
X.tl 'Command: Forward message''Edit outgoing message (y/n) ? No '
X.tl 'To: @'''
X.ps 10
X.ft 1
X.sp 
XWe type in the address of the person we're forwarding to (in
Xthis case 
X.ft CW
X.zf
Xusenet\f1) and press
X\f2<return>\f1:
X.ft CW
X.zf
X.ps 9
X.sp
X.tl '-------------------------------------------------------------------------------''
X.tl 'Command: Forward message''To: usenet '
X.tl 'Subject: More software requests (fwd)@'
X.ft 1
X.ps 10
X.sp
XTo which we again press \f2<return>\f1 to take the default subject.
X\f3Elm\f1 asks for any possible copy recipients, asks us if we're
Xsure we want to send it, and shoots it off.
X.sp
XEnough mail for now, however, so we just \f2exit\f1 by pressing
Xthe ``x'' key and the program drops us back into our shell.
X.sp 2
XAs you can see, it's quite easy to use the \f3Elm\f1 system, so
Xrather than continue with our example, let's
Xlook at some other aspects of the program.
X.br 
X.ne 5
X.sp
X.hn 1 Non-Interactive Uses of Elm
X
XBefore we go ahead and discuss the \f3Elm\f1 utilities, it's worth 
Xnoting that 
Xthere are a couple of other ways to use the main mail
Xsystem, namely to `send only' and to send files (batchmail).
X
XTo send a message to someone without any of the associated 
Xoverhead of reading in a mail folder, you can invoke the
Xmailer with the name(s) of the people to send to.  For example:
X.nf
X  $ \f3elm dave_taylor\f1
X.fi
XThe 
Xmailer will then prompt for Subject, Copies, and then drop
Xyou in your editor (defined in the \f2.elm/elmrc\f1 file) to compose
Xthe message.   When composition is complete, the program 
Xverifies transmission then terminates.
X
X.ne 3
XThe mailer also supports batch type mailing, of files and so on,
Xby using the following command:
X.nf
X  $ \f3elm dave_taylor < help.c\f1
X.fi
Xwhich will read in the file and transmit it to the specified user.
X
X.ne 3
XA subject may be specified with ``-s \f2subject\f1'' as an option
Xto the program in either `send only' or `batch' modes, as in:
X.nf
X  $ \f3elm -s "File help.c, as promised" dave_taylor < help.c\f1
X.fi
X.br
X.ne 5
X.sp 
X.hn 1 The Elm Utilities
X
XThe \f3Elm\f1 mail system is really much more than a single
Xprogram for reading and writing mail.  It's a unified 
Xenvironment for intelligently dealing with electronic
Xcorrespondence.  As a consequence, it contains a number of other
Xprograms to aid in the easy processing of `email', 
Xincluding the following;
X
X.lp \h'10p'answer 1.0i
XAn answering-machine transcription program.  Please see the
Xmanual entry for more information on how to use this program.
X
X.lp \h'10p'autoreply 1.0i
XThis program, in conjunction with the ``arepdaemon'', enables users
Xto automatically reply to incoming mail when they're not directly
Xavailable.
X
X.lp \h'10p'checkalias 1.0i
XA script for checking aliases simply.
X
X.lp \h'10p'messages 1.0i
XA script that lists the number of messages in the specified 
Xfolder.  Suitable for login scripts and such.
X
X.lp \h'10p'newmail 1.0i
XThis program monitors a mailbox or set of mailboxes and can
Xoutput notification of new mail in one of two possible
Xformats; either:
X
X.ne 6
X.ft CW
X.zf
X.ps 9
X>> New mail from Jimmy Carter - Urgent matters of state
X>> New mail from joe@ucbvax.arpa - Did I hear someone say PARTY??
X.ft 1
X.ps 10
X
Xif running as \f2newmail\f1 or:
X
X.ft CW
X.zf
X.ps 9
XJimmy Carter -- Urgent matters of state
Xjoe@ucbvax.arpa -- Did I hear someone say PARTY??
X.ft 1
X.ps 10
X
Xif running as \f2wnewmail\f1.  BSD Users will find this is
Xa far superior \f2biff\f1 program.
X
X.lp \h'10p'wnewmail 1.0i
XThis is the same program as newmail, but has different
Xdefaults if invoked this way.
X
X.lp \h'10p'readmsg 1.0i
XThis handy little program can be used in two ways.  First off,
Xit can be used to easily read a specific message in the
Xincoming mailbox, specified by ordinal number, by a string that
Xthe message contains, by the metacharacter `$' which 
Xrepresents the last message in the folder, or `*' which matches 
Xall the messages in the folder.
X
XFor example;
X
X$ \f3readmsg 4 5 9 | lpr\f1
X
Xwould generate a printout, \f2sans\f1 superfluous headers, of the fourth,
Xfifth and ninth messages in your mailbox.
X
X$ \f3readmsg Carter | page\f1
X
Xwould be a fast way to read what `ole Jimmy has to say...
Xand
X
X$ \f3readmsg -h hear someone say\f1
X
Xwould list, including all the message headers, the message
Xcontaining the string ``hear someone say''.
X
X.lp \h'10p'frm 1.0i
XSimilar to the Berkeley \f2from\f1 command, this will
Xgive you a ``table of contents'' of either the current
Xmailbox or a mailbox of your choice.   It's useful to
Xsee what mail is pending, or what's in a mailbox.
XIf used with the `-n' option, it will number each message
Xin a way compatible with the arguments \f2readmsg\f1
Xexpects to get, too!
X
X.lp \h'10p'newalias 1.0i
XThis is used to install new user/group aliases.  Please see
X\f2The Elm Alias Users Guide\f1 for further information on this!
X
X.lp \h'10p'fastmail 1.0i
XSometimes you want to have a batchmailing system that works as
Xquickly as possible, not bothering with aliases or any of the
Xother ``deluxe'' features of \f3Elm\f1.  An example of this would
Xbe if you have a large mailing list for a newsletter, say.
XThis command, \f2fastmail\f1, is designed just for that purpose.
XIt avoids the lengthy startup time of \f3Elm\f1 while still
Xgenerating valid \f2RFC-822\f1\s-2\u5\d\s0 mail.
X.fn
X5. If you don't know what RFC-822 is, don't worry about it!
X.ef
XPlease see the manual entry for more information on this
Xcommand.
X.in 0
X.br
X.ne 5
X.sp
X.hn 1 Credits and So on
X
XThis mailer has been evolving over the past few years with
Xinvaluable comments on the interface and general mail 
Xissues from the following people;
XJim Davis, Steve Wolf (or should that say Steve!! Wolf!!!! perhaps?),
XLarry Fenske, Rob Sartin,
XJohn Dilley and Carl Dierschow.
X.sp
XFor the Berkeley implementation, lots of help came from
Xboth John Lebovitz and Ken Stone.
X.sp
XFor the Amdahl/UTS implementation, thanks to Scott McGregor and
XStan Isaacs.
X.sp
XFor the Sun problems, Dave England in Lancaster (UK) turned out to be
X``bloody useful'', as he would no doubt say.
X.sp
XThe Pyramid version is due to the work of Steve Malone
Xof the University of Washington.
X.sp
XA number of other people have been amazingly disciplined at reporting 
Xproblems and (usually, much to my relief) indicating the fixes needed,
Xespecially Guy Hillyer, Bruce Townsend and Eric Negaard.
X.sp
XThere have been many, many others, too numerous to mention, that
Xhave inspired me with questions like "Why can't Elm..." or 
X"Why does it ..." or "Can we make it..." too.  A loud round of
Xapplause and an enthusiastic THANK YOU to you all!!
X.sp
XAlso helpful was the ability to have my `own' machine to 
Xclose up the many many iterative loops that this software
Xhas gone through \(em since being on a big multi-user machine
Xtends to slow it down to a standstill...
XFor that, I thank Hewlett-Packard Colorado Networks Division for their 
Xinitial support, and now HP Laboratories for the wonderful working 
Xenvironment that I have here (more than any one person is safe having, 
XI suspect).
X.sp
XMailers that have influenced the design and implementation of \f3Elm\f1, 
Xfor better or worse, include the following;
X
X.lp \h'4p'\f2/bin/mail\f1 1.0i
XThe most basic of mailers, this one was simply the example of how \f2not\f1
Xto force the user to interact with a program.
X
X.lp "\h'4p'\f2Berkeley Mail\f1" 1.0i
XA surprisingly sophisticated mailer, especially the version with 4.3 BSD,
X\f2Berkeley Mail\f1 still suffers from the tendency to force the user to
Xknow too much about the system, and also lacks a friendly, non-cryptic
Xinterface for the large subset of the population that use Unix but aren't
Xinterested in becoming a ``hacker''.
X
X.lp \h'4p'\f2MH\f1 1.0i
XThis is another nifty mailer.  The main difference between this and the
Xother mailers about is that it is a discrete set of programs rather than
Xa single unified interface.  This is quite useful for those people that
Xreceive \f2lots\f1 of mail and are willing to spend some time learning
Xthe intricacies of the program.  It's quite powerful, but again, misses some
Xof the basic friendly features the majority of users are interested in.
X
X.lp \h'4p'\f2dmail\f1 1.0i
XA sort of mutated cross between \f2MH\f1 and \f2Berkeley Mail\f1, it was
Xthis program that convinced me to implement the \f2Limit\f1 functions.
X
X.lp \h'4p'\f2NMail\f1 1.0i
X(a part of the HP AI Workstation Software Environment).  This program hints
Xat the power that mailers could be given to help deal with mail in a quick
Xand intelligent fashion.  Most of what it can do, and a lot more, are 
Xtherefore part of \f3Elm\f1.  Indubitably.  And quite faster too!
X
X.lp \h'4p'\f2PMX/TERM\f1 1.0i
XPart of the AT&T Mail package, a single glance at this interface convinced
Xme that a PC interface, with almost half of the screen taken up by a silly
Xfunction key mapping, is most certainly \f2not\f1 the way to do things!!
XOn the other hand, it also shows that the \f2Forms\f1 mode can be quite
Xnicely integrated into a more sophisticated mailer.
X
X.lp \h'4p'\f2fmail\f1 1.0i
XA nickel addition to the \f2/bin/mail\f1 program to add some rudimentary
Xscreen interface stuff, this nonetheless interesting mailer is part of 
Xthe AT&T Toolchest.
X
X.lp \h'4p'\f2Laurel\f1 1.0i
XA program only available within Xerox PARC, this was an interesting
Xearly attempt at a graphics based full-screen mail program.  The one,
Xperhaps trivial, part of the interface I really like was the fact that
Xit would \f2cross out\f1 a message that was marked for deletion.  One
Xday when we get real graphics and the ability to use them indicated in
Xa facility (not too) like \f2termcap\f1, perhaps \f3Elm\f1 will do 
Xthis too! 
X
X.lp \h'4p'\f2Mailtool\f1 1.0i
XPart of the Sun distribution package, this program is a really nice
Xexample of what can be done by putting a smart shell on top of a dumb
Xprogram \(em it uses \f2/bin/mail\f1 for all the `dirty work'.  Other than
Xthat, it's not a particularly interesting interface or mailer, and it
Xcertainly doesn't add much functionality!
X
X.lp \h'4p'\f2Metamail\f1 1.0i
XWhat can I say?  This isn't even a real mailer, but is just what I dream
Xof as an interface to mail in the future.  A program that works sort of
Xlike \f3HAL\f1 did in \f22001: A Space Odyssey\f1 \(em where it interrupts
Xme as appropriate for important mail, and can answer inane and other
Xqueries itself according to what I teach it.  Maybe \f3Elm\f1, by some sort
Xof groupmind metamorphosis, will change into that someday.  Maybe not.  Maybe
Xno-one bothers to read this far into the document!!
X
X.in 0
XFinally, it's also been a very useful experience overall,
Xconfirming my beliefs that iterative software design and
Xkeeping a close watch on users (not to mention an open
Xmind and mailbox!) improves a product manyfold.  Comments,
Xfeedback and bug reports (and fixes!) are, of course, always welcome!
X.br
X.ne 5
X.sp
X.hn 1 "Credits and So on Part II - The Usenet Elm Development Group"
X
XAs coordinator of the Elm Development Group, I must add to the credits.
XThis group of volunteers has taken the Elm code from Dave Taylor and
Xadded features, made it more robust, and more portable.
X.sp
XFor getting the Usenet Elm group going, for without which I wouldn't be
Xwriting this, thanks to Greg Hackney at Southwestern Bell Telephone Co.
X.sp
XFor the Configuration system and its newer Dist 2.0 version, thanks are
Xdue to Larry Wall of JPL-NASA.
X.sp
XFor his over two hundred sets of changes to version 2.2, Elm owes a lot
Xto Rob Bernardo at Pacbell.
X.sp
XThe ability to run Elm at all on Intel 286 machines owes a lot to the
Xinsistent nudging of the coordinator by Chip Salzenberg,
XChip Rosenthal, and Tim Evans.
X.sp
XFor getting us the rights to use the news macros and converting all
Xthe documentation over to those macros, thanks to Mike Brown.
X
XNow, before I get accused of leaving someone out, here are the
Xmembers of the Elm Development and the Elm Testing Group:
X.sp
XJonathan Bayer,
XRob Bernardo,
XDoug Blair,
XKevin Bond,
XMike Brown,
XEd Clarke,
XSteven Donegan,
XPaul Ebersman,
XAvi Feldblum,
XSteven Goodman,
XGreg Hackney,
XMark Hahn,
XMitch Hamilton,
XEd Hann,
XDavid Hawkins,
XNate Hess,
XPhil Hochstetler,
XBud Hovell,
XKenneth Ingham,
XChad Larson,
XWarren Lavallee,
XHoward Leadman,
XJohn A. Limpert,
XAndy Linton,
XDarrell McIntosh,
XDatta Miruke,
XPaul M. Moriarty,
XAndrew Mossberg,
XRobert B. Nelson,
XLeo C. Noordhuizen,
XBrian O'Neill,
XFairfax O'Riley,
XPete Phillips,
XDave Rasmussen,
XLen Rose,
XChip Rosenthal,
XChip Salzenberg,
XRay Smith,
XGary Trujillo,
XEd Wells,
XMike Whitman,
XDave Yearke,
XJon Zeeff,
Xand
XSyd Weinstein, Elm Coordinator.
SHAR_EOF
# ============= doc/answer.1 ==============
echo "x - extracting doc/answer.1 (Text)"
sed 's/^X//' << 'SHAR_EOF' > doc/answer.1 &&
X.TH ANSWER 1L "Elm Version 2.3" "USENET Community Trust"
X.SH NAME
Xanswer - phone message transcription system
X.SH SYNOPSIS
X.B answer
X.PP
X.SH DESCRIPTION
X.I Answer\^
Xis a part of the 
X.B Elm
Xmail system and is designed for secretaries and the like
Xto allow them to answer phones and|or listen to phone message
Xmachines and quickly and easily transcribe the messages into
Xelectronic mail.
X.P
XThe program uses its own alias set (usually a subset of the
Xsystem aliases, with more fields per user (ie unique first
Xnames, unique last names, first-initial lastname, and so on)).
XNote this means that you must create and then install, using
X.I newalias,
Xa separate alias table for the account this program is to 
Xbe run from.
X.P
XInterface-wise, the program is a breeze to use - type 'answer'
Xto start it up and then merely type a user name at the
X.nf
X	
X	Message to:
X
X.fi
Xprompt, and then enter the message, ending with a blank line.
XNames can be entered as 'Firstname Lastname' and the system
Xwill try to find a mail alias based on the first letter of the
Xfirst name plus the last name.  For example, 'Dave Taylor'
Xwill cause the program to search for an alias 'd_taylor' in
Xthe file (note the transliteration into lower case).   The 
Xprogram will loop until killed or quit.
X.P
X.I Answer
Xcan be easily exited by typing any of 'quit', 'exit' 'done', 
Xor 'bye' at the 'Message to:' prompt.
X.SH AUTHOR
XDave Taylor, Hewlett-Packard Laboratories
X.SH SEE ALSO
X.I "The Elm Alias System Users Guide", 
Xby Dave Taylor
X.sp
X.br
Xnewalias(1L), checkalias(1L), mail(1), mailx(1), from(1L), printmail(1L)
X.SH FILES
X$HOME/.elm/aliases.text       individual alias source
X.br
X$HOME/.elm/aliases.hash       individual alias hash table
X.br
X$HOME/.elm/aliases.data       individual alias data table
X.br
X/tmp/snd.$$                   edit buffer for outgoing mail
X.SH BUG REPORTS TO
XSyd Weinstein	elm@DSI.COM	(dsinc!elm)
X.SH COPYRIGHTS
X.ps 18
X\fB\(co\fR\s12 Copyright 1986, 1987 by Dave Taylor
X.br
X.ps 18
X\fB\(co\fR\s12 Copyright 1988, 1989, 1990 by The USENET Community Trust
SHAR_EOF
# ============= doc/autoreply.1 ==============
echo "x - extracting doc/autoreply.1 (Text)"
sed 's/^X//' << 'SHAR_EOF' > doc/autoreply.1 &&
X.TH AUTOREPLY 1L "Elm Version 2.3" "USENET Community Trust"
X.SH NAME
Xautoreply - Automatic mail reply system
X.SH SYNOPSIS
X.B autoreply
X.br
X.B "autoreply off"
X.br
X.B autoreply
X.I filename
X.PP
X.SH DESCRIPTION
X.I Autoreply\^
Xis a part of \fBThe Elm Mail System\fR
Xand is designed to enable users to easily set up
Xan automatic response to all mail they receive.  This is
Xtypically during a vacation or some other period of time that
Xthe user is not available to reply to mail (although some
Xpeople get enough mail that they have it permanently running
Xto simply send an "ack" to each message)
X.PP
XThe system is quite easy to use...
XYou can type "autoreply" and be informed of your current
Xstatus in the system (on or off), or "autoreply off" will
Xturn your autoreplying off.
X.PP
XTo add yourself to the system, you need merely to compose a
Xform response in a file somewhere, then type "autoreply \fIfile\fR"
Xwhere \fIfile\fR is the name of the file.
X.SH "SPECIAL NOTE"
XFor this to function correctly, the program "arepdaemon" must
Xbe running as a daemon in background.  This program automatically
Xchecks all the currently enrolled users for new mail in their
Xmailboxes...
X.SH AUTHOR
XDave Taylor, Hewlett-Packard Laboratories.
X.SH SEE ALSO
X.I "The Elm Users Guide", 
Xby Dave Taylor
X.sp
X.br
Xelm(1L), mail(1), mailx(1)
X.SH "BUGS"
XUnfortunately, this program isn't too brilliant about identifying
Xmail that shouldn't be responded to (like mail from other
Xdaemons, or your mother) but that's a more general problem anyway.
X.sp
XAlso, occasionally a user will remove themselves from the
Xautoreply system and the system won't turn their autoreply
Xoff.  This is a problem that hasn't been solved yet (obviously
Xsince it's in the "bugs" section!!) and any further information
Xwould be appreciated!
X.SH BUG REPORTS TO
XSyd Weinstein	elm@DSI.COM	(dsinc!elm)
X.SH COPYRIGHTS
X.ps 18
X\fB\(co\fR\s12 Copyright 1986, 1987 by Dave Taylor
X.br
X.ps 18
X\fB\(co\fR\s12 Copyright 1988, 1989, 1990 by The USENET Community Trust
SHAR_EOF
# ============= doc/chkalias.1 ==============
echo "x - extracting doc/chkalias.1 (Text)"
sed 's/^X//' << 'SHAR_EOF' > doc/chkalias.1 &&
X.TH CHECKALIAS 1L "Elm Version 2.3" "USENET Community Trust"
X.SH NAME
Xcheckalias - check to see if an alias is defined.
X.SH SYNOPSIS
X.B checkalias
Xalias, alias, ...
X.SH DESCRIPTION
X.I Checkalias
Xchecks the user file first, and then the system alias file
Xto try to find the specified alias or aliases.  If found, 
Xthe value of the alias is printed out, otherwise an error
Xis generated.
X.P
XNote: this is in fact a one-line shell script;
X.nf
X
X	elm -c $*
X.fi
X.SH AUTHOR
XDave Taylor, Hewlett-Packard Laboratories
X.SH SEE\ ALSO
Xnewalias(1L), elm(1L), mail(1), mailx(1)
X.SH BUGS
XNote that the precedence of aliases is user file then system
Xfile.  This means that a user can 'overload' an alias by having
Xone defined in the system file also defined in theirs.  This
Xshouldn't turn out to be a problem, but is something for
Xthe system administrator to keep in mind when creating the
Xsystem alias file.
X.SH BUG REPORTS TO
XSyd Weinstein	elm@DSI.COM	(dsinc!elm)
X.SH COPYRIGHTS
X.ps 18
X\fB\(co\fR\s12 Copyright 1986, 1987 by Dave Taylor
X.br
X.ps 18
X\fB\(co\fR\s12 Copyright 1988, 1989, 1990 by The USENET Community Trust
SHAR_EOF
# ============= doc/elm-help.0 ==============
echo "x - extracting doc/elm-help.0 (Text)"
sed 's/^X//' << 'SHAR_EOF' > doc/elm-help.0 &&
X
X        Command                      Elm 2.3 Action
X
X          <RETURN>,<SPACE>      Display current message
X           |                    Pipe current message or tagged messages to
X                                        a system command.
X           !                    Shell escape
X           $                    Resynchronize folder
X           ?                    This screen of information
X           +, <RIGHT>           Display next index page
X           -, <LEFT>            Display previous index page
X           =                    Set current message to first message
X           *                    Set current message to last message
X           <NUMBER><RETURN>     Set current message to <NUMBER>
X           /                    Search from/subjects for pattern
X           //                   Search entire message texts for pattern
X           >                    Save current message or tagged messages
X                                        to a folder
X           <                    Scan current message for calendar entries
X           a                    Alias, change to 'alias' mode
X           b                    Bounce (remail) current message
X           C                    Copy current message or tagged messages
X                                        to a folder
X           c                    Change to another folder
X           d                    Delete current message
X          ^D                    Delete messages with a specified pattern
X           e                    Edit current folder
X           f                    Forward current message
X           g                    Group (all recipients) reply to current message
X           h                    Headers displayed with message
X           J                    Increment current message by one
X           j, <DOWN>            Advance to next undeleted message
X           K                    Decrement current message by one
X           k, <UP>              Advance to previous undeleted message
X           l                    Limit messages by specified criteria
X          ^L                    Redraw screen
X           m                    Mail a message
X           n                    Next message, displaying current,
X                                        then increment
X           o                    Change ELM options
X           p                    Print current message or tagged messages
X           q                    Quit, maybe prompting for deleting, storing,
X                                        and keeping messages
X           Q                    Quick quit - no prompting
X           r                    Reply to current message
X           s                    Save current message or tagged messages
X                                        to a folder
X           t                    Tag current message for further operations
X          ^T                    Tag messages with a specified pattern
X           u                    Undelete current message
X          ^U                    Undelete messages with a specified pattern
X           x, ^Q                Exit leaving folder untouched, ask permission
X                                        if folder changed
X           X                    Exit leaving folder untouched, unconditionally
SHAR_EOF
echo "End of  part 5"
echo "File doc/elm-help.0 is continued in part 6"
echo "6" > shar3_seq_.tmp
exit 0