NAME

       scan - produce a one line per message scan listing

SYNOPSIS

       scan [+folder] [msgs] [-clear | -noclear] [-form formatfile] [-format string] [-header |
            -noheader] [-width columns] [-reverse | -noreverse] [-file filename] [-version]
            [-help]

DESCRIPTION

       Scan  produces  a  one-line-per-message listing of the specified folder or messages.  Each
       scan line contains the message number (name), the date, the “From:” field,  the  “Subject”
       field, and, if room allows, some of the body of the message.  For example:

            15+  10/05 crocker    nned  <<Last week I asked some of
            16-  10/05 crocker    message id format  <<I recommend
            18   10/06 brien      Re: Exit status from mkdir
            19   10/07*brien      “scan” listing format in nmh

       The `+' on message 15 indicates that it is the current message.

       The  `-' on message 16 indicates that it has been replied to, as indicated by a “Replied:”
       component (produced by the -annotate switch to the repl command).

       The `*' on message 19 indicates that no “Date:” header was  present.   The  time  of  last
       modification of the message is given instead.

       If  there  is  sufficient  room  left on the scan line after the subject, the line will be
       filled with text from the body, preceded by “<<”, and terminated by “>>” if  the  body  is
       sufficiently short.  Scan actually reads each of the specified messages and parses them to
       extract the desired fields.  During parsing, appropriate error messages will  be  produced
       if there are format errors in any of the messages.

       By  default,  scan will decode RFC-2047 (MIME) encoding in these scan listings.  Scan will
       only decode these fields if your terminal can natively display the character set  used  in
       the encoding.  You should set the MM_CHARSET environment variable to your native character
       set, if it is not US-ASCII.  See  the  mh-profile(5)  man  page  for  details  about  this
       environment variable.

       The switch -reverse, makes scan list the messages in reverse order.

       The  -file  filename switch allows the user to obtain a scan listing of a maildrop file as
       produced by packf.  This listing includes every  message  in  the  file  (you  can't  scan
       individual messages).  The switch -reverse is ignored with this option.

       The  switch -width columns may be used to specify the width of the scan line.  The default
       is to use the width of the terminal.

       The -header switch produces a header line prior to the scan listing.  Currently, the  name
       of  the  folder and the current date and time are output (see the HISTORY section for more
       information).

       If the -clear switch is used and scan's output is directed to a terminal, then  scan  will
       consult  the  environment  variables $TERM and $TERMCAP to determine your terminal type in
       order to find out how to clear the screen prior to exiting.  If the -clear switch is  used
       and  scan's  output is not directed to a terminal (e.g., a pipe or a file), then scan will
       send a formfeed prior to exiting.

       For example, the command:

            (scan -clear -header; show all -show pr -f) | lpr

       produces a scan listing of the current folder, followed  by  a  formfeed,  followed  by  a
       formatted  listing  of  all  messages in the folder, one per page.  Omitting “-show pr -f”
       will cause the messages to be concatenated, separated by a one-line header and  two  blank
       lines.

       To  override the output format used by scan, the -format string or -form file switches are
       used.  This permits individual fields of the scan listing to be extracted with ease.   The
       string  is  simply a format string and the file is simply a format file.  See mh-format(5)
       for the details.

       In addition to the standard mh-format(5)  escapes,  scan  also  recognizes  the  following
       additional component escapes:

            Escape    Returns  Description
            body      string   the (compressed) first part of the body
            dtimenow  date     the current date
            folder    string   the name of the current folder

       If  no date header is present in the message, the function escapes which operate on {date}
       will return values for the date of last modification of the  message  file  itself.   This
       feature  is handy for scanning a draft folder, as message drafts usually aren't allowed to
       have dates in them.

       scan will update the nmh context prior to starting the listing,  so  interrupting  a  long
       scan listing preserves the new context.  nmh purists hate this idea.

FILES

       $HOME/.mh_profile          The user profile

PROFILE COMPONENTS

       Path:                To determine the user's nmh directory
       Alternate-Mailboxes: To determine the user's mailboxes
       Current-Folder:      To find the default current folder

SEE ALSO

       inc(1), pick(1), show(1), mh-format(5)

DEFAULTS

       `+folder' defaults to the current folder
       `msgs' defaults to all
       `-format' defaulted as described above
       `-noheader'
       `-width' defaulted to the width of the terminal

CONTEXT

       If a folder is given, it will become the current folder.

HISTORY

       Prior to using the format string mechanism, -header used to generate a heading saying what
       each column in the listing was.  Format strings prevent this from happening.

BUGS

       The argument to the -format switch must be interpreted as a single token by the shell that
       invokes  scan.   Therefore,  one  must  usually  place  the argument to this switch inside
       quotes.

       The value of each component escape is set by scan to the contents  of  the  first  message
       header  scan  encounters with the corresponding component name; any following headers with
       the same component name are ignored.