SCAN(1)                                                   SCAN(1)

NAME
       scan - produce a one line per message scan listing

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

DESCRIPTION
       Scan produces a one-line-per-message listing of the speci-
       fied folder or messages.  Each scan line contains the mes-
       sage number (name), the date, the "From:" field, the "Sub-
       ject"  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 spec-
       ified  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 mes-
       sages.

       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 envi-
       ronment 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 envi-
       ronment 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  exit-
       ing.

       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  mes-
       sages 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 mes-
       sage 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.  ^$HOME/.mh_pro-
       file~^The user profile ^Path:~^To determine the user's nmh
       directory  ^Alternate-Mailboxes:~^To  determine the user's
       mailboxes ^Current-Folder:~^To find  the  default  current
       folder  inc(1),  pick(1),  show(1), mh-format(5) `+folder'
       defaults to the folder  current  `msgs'  defaults  to  all
       `-format'   defaulted   as   described  above  `-noheader'
       `-width' defaulted to the  width  of  the  terminal  If  a
       folder is given, it will become the current folder.  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.   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
       double-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.

[nmh-0.27]                    MH.6.8                            1