READMSG(1L)                                           READMSG(1L)

NAME
       readmsg - extract messages from a mail folder

SYNOPSIS
       readmsg  [-anhp] [-f folder] [-w weedlist] [selection ...]

DESCRIPTION
       Readmsg  extracts  selected  mail  messages  from  a  mail
       folder.   One  helpful  use of the program is when you are
       composing a response to a mail message in an external edi-
       tor.   In this case, you can run readmsg to pull a copy of
       the original message into the editing buffer.

       When you run readmsg from within elm (e.g. from a subshell
       escape  or  in  an  external editor while composing a mail
       reply) it behaves a bit differently from when you  run  it
       directly  (e.g. from a shell command line).  We will first
       describe its normal behavior, and then describe how it  is
       different when you run it under elm.

       You tell readmsg which messages to extract with the selec-
       tion argument.  There are a couple of  possible  different
       ways to specify the selection.

       1.     A lone ``*'' means select all messages in the mail-
              box.

       2.     A list of message numbers may be specified.  Values
              of  ``0''  and ``$'' in the list both mean the last
              message in the mailbox.  For example:

                   readmsg 1 3 0

              extracts  three  messages  from  the  folder:   the
              first, the third, and the last.

       3.     Finally,  the  selection may be some text to match.
              This will  select  a  mail  message  which  exactly
              matches the specified text.  For example,

                   readmsg staff meeting

              extracts  the  message  which  contains  the  words
              ``staff meeting.''  Note that it will not  match  a
              message containing ``Staff Meeting'' - the matching
              is case sensitive.  Normally only the first message
              which  matches the pattern will be printed.  The -a
              option discussed in a moment changes this.

       The -f flag indicates that you'd  rather  use  the  folder
       specified  rather  than the default incoming mailbox.  The
       specified folder can be a filename or a specification such
       as ``=sentmail''.

       The  -w  flag  tailors  the  list of mail headers that are
       weeded and displayed.  Header weeding is discussed  below.

       The  -h  flag  instructs  the program to ignore the header
       weeding list, and include the entire header of the matched
       message or messages when displaying their text.

       The  -n  flag  instructs  the program to ignore the header
       weeding list, and  exclude  all  headers.   This  is  used
       mostly for extracting files mailed and such.

       The  -p  flag  indicates that the program should put form-
       feeds (control-L) between message headers.

       The -a flag indicates that all messages  which  match  the
       pattern  specified  on the command line should be printed,
       not just the first.  If a pattern was not specified on the
       command line then this flag has no effect.

       When  you  run readmsg under elm (say in the context of an
       external editor) the behavior will be different from  that
       described above as follows.

       1.     The  default mail folder will be the folder you are
              currently examining in elm and not necessarily your
              incoming mail folder.

       2.     You  do not need to specify a selection on the com-
              mand line.  If you omit the selection then  readmsg
              will  extract  the  message(s) you have selected in
              Elm.  If you have tagged  any  messages  then  this
              would  be  all of the tagged messages, otherwise it
              would be the message you are currently examining.

       3.     Normally the message numbers readmsg  uses  are  in
              mailbox order.  When you call readmsg under elm and
              do not override the folder selection  with  the  -f
              option, then message numbers will be sorted as they
              are displayed on the elm message index screen.

       Normally, readmsg selects  and  displays  certain  headers
       from  the message.  By default, the list of selected head-
       ers includes:

              o The ``Subject:'' header.
              o The ``From:'' header.
              o The ``To:'' header.
              o The ``Cc:'' header.
              o The ``Date:'' header.
              o Any header starting with ``Apparently-''.

       The header weeding may be changed with the -w option.  The
       argument  to  this option is a list of header names, sepa-
       rated by whitespace  or  commas.   readmsg  compares  each
       header  to  the ones in this list, and if a match is found
       the header is displayed.  The  list  entries  can  contain
       partial  header names.  For instance, an entry of ``From''
       would match both the ``From<SPACE>'' line at  the  top  of
       the message, as well as any ``From:'' header.  Matching is
       case insensitive.  An underscore (``_'') may  be  used  to
       represent a space, so specifying ``From_'' will select the
       ``From<SPACE>'' line but not the ``From:'' header.  A list
       entry  may be preceded by an exclamation point to suppress
       the header.   Thus,  a  specification  of  ``!From_ From''
       means  about  the same thing as ``From:''.  When no header
       weeding options are specified, the default  action  corre-
       sponds to:

            readmsg -w "Subject: From: To: Cc: Apparently- Date:"

EXAMPLES
       First off, to use this from within vi to include the  text
       of the current message, you could use the command:

            :r !readmsg

       (as  you hit the ':' the editor will put you at the bottom
       of the screen with the ':' prompt).  The  space  following
       ':r' is required.

       Let's look at something more interesting, however;

       Suppose you have the mail file;

          From joe Jun 3 1986 4:45:30 MST
          Subject: hello

          Hey Guy!  Wanta go out and have a milk this evening?

          Joe

          From john Jun 3 1986 4:48:20 MST
          Subject: Dinner at Eight
          From: John Dinley <xyz!john>

          Remember you should show up about eight, okay?

                    - John D -

          From xxzyz!cron Jun 3 1986 5:02:43 MST

          Cannot connect to server: blob
          Job 43243 deleted from queue.

       The following commands will result in;

         $ readmsg 2
         [ display the second message, from John ]

         $ readmsg
         [ an error, unless we're calling from elm ]

         $ readmsg BLOB
         [ no match - case sensitive! ]

         $ readmsg -h connect to server
         [ displays third message, including headers ]

FILES
       /usr/mail/<username>          The incoming mail
       $ELMSTATE           Status information from elm

AUTHOR
       Elm Development Group

SEE ALSO
       newmail(1L), elm(1L)

BUGS
       The '*' metacharacter doesn't always work as expected!
       Perhaps the pattern matching should be case insensitive?
       It  might  be confusing that messages are sorted when run-
       ning under elm with the current  folder,  and  in  mailbox
       order  for  all  other  cases.   When readmsg is run stan-
       dalone, messages may be truncated at lines beginning  with
       "From".   This  is  not  a problem when readmsg is spawned
       under elm because the status information file  created  by
       elm says exactly how long each message is.

BUG REPORTS TO
       Bill Pemberton  flash@virginia.edu

COPYRIGHTS
       Copyright 1988-1995 by The USENET Community Trust
       Derived from Elm 2.0,  Copyright 1986, 1987 by Dave Taylor

USENET Community Trust   Elm Version 2.5                        1