.TH PICK %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
.SH NAME
pick \- select messages by content
+scan \- produce a one line per message scan listing
.SH SYNOPSIS
.HP 5
.na
.IR columns ]
.RB [ \-thread
.RI [ +folder ] messages "|" files ]
+.RB [ \-file
+.IR mboxfilename ]
.RB [ \-sequence
.I name
\&...]
.RB [ \-list " | " \-nolist ]
.RB [ \-Version ]
.RB [ \-help ]
+.PP
+.HP 5
+.B scan
+is equivalent to
+.B pick -format scan.default
.ad
.PP
typical usage:
.PP
.RS 5
.nf
-scan\0`pick\0\-from\0jones`
+scan\0\-from\0jones`
pick\0\-to\0holloway\0\-sequence\0select
show\0`pick\0\-before\0friday`
.fi
primitives are available: pattern matching and date constraint
operations.
.PP
-A modified
-.BR grep (1)
+The default
+.BR regex (7)
is used to perform the matching, so the
-full regular expression (see
-.BR ed (1))
-facility is available
+full regular expression facility is available
within
-.IR pattern .
+.IR pattern.
With
.BR \-search ,
.I pattern
-is used directly, and with the others, the grep pattern constructed is:
-.PP
-.RS 5
-`component[ \\t]*:\&.*pattern'
-.RE
-.PP
-This means that the pattern specified for a
-.B \-search
-will be found
-everywhere in the message, including the header and the body, while
-the other pattern matching requests are limited to the single specified
-component. The expression
-.PP
-.RS 5
-`\-\|\-component\ pattern'
-.RE
-.PP
-is a shorthand for specifying
-.PP
-.RS 5
-`\-search `component[ \\t]*:\&.*pattern'\ '
-.RE
+is used directly, but only for the body of the Mail.
+With the others,
+.B pick
+compares the header field name case insensitive
+and the tries to match the field body with the
+.IR pattern.
.PP
+With
+.BR --componend
+you can specify the exact header field name you are looking for.
It is used to pick a component which is not one of `To:',
`Cc:', `Date:', `From:', or `Subject:'.
An example is
.RB ` "pick\0\-\|\-reply\-to\0pooh" '.
.PP
-Pattern matching is performed on a per\-line basis. Within the header
-of the message, each component is treated as one long line, but in the
-body, each line is separate. Lower\-case letters in the search pattern
-will match either lower or upper case in the message, while upper case
-will match only upper case.
+Pattern matching is performed on a per\-header-field basis. Within the header
+of the message, each field is treated as one long line, but in the
+body, each line is separate. The
+.IR pattern
+will match any case.
.PP
Note that since the
.B \-date
parentheses in logical expressions.
.PP
If no search criteria are given, all the messages specified on the
-command line are selected (this defaults to `all').
+command line are selected (this defaults to `a').
.PP
Once the search has been performed, if the
.B \-list
`backquoting' syntax of the shell. For example, the command
.PP
.RS 5
-scan\0`pick\0+todo\0\-after\0`31 Mar 83 0123 PST'`
+show\0`pick\0+todo\0\-after\0`31 Mar 83 0123 PST'`
.RE
.PP
says to
-.B scan
+.B show
those messages in the indicated folder which meet the
appropriate criterion. Note that since
.BR pick 's
context changes
are written out prior to
-.BR scan 's
+.BR show 's
invocation, you need not give
the folder argument to
-.B scan
+.B show
as well.
.PP
The
.B mark
uses them.
+.B Scan
+and
+.B pick
+produces a one\-line\-per\-message listing of the specified and selected
+folder or messages.
+The default format is for
+.B pick
+is to print the message number for each message.
+The default
+.B Scan
+line contains the message number
+(name), the date, the `From:' field and the `Subject' field.
+The following example shows the default output of
+.B scan
+.PP
+.RS 5
+.nf
+.ta \w'15+- 'u +\w'07/\|05x 'u +\w'Dcrocker 'u
+15+ 10/\|05 crocker nned
+16\- 10/\|05 crocker message id format
+18 10/\|06 brien Re: Exit status from mkdir
+19 10/\|07*brien `scan' listing format in mmh
+.fi
+.RE
+.PP
+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
+.B \-annotate
+switch
+to the
+.B repl
+command).
+The `*' on message 19 indicates that no `Date:' header was
+present. The time of last modification of the message is given instead.
+.B 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.
+.PP
+By default,
+.B scan
+will decode RFC-2047 (MIME) encoding in
+these scan listings.
+.B 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.
+.PP
+The
+.B \-file
+.I filename
+switch allows the user to obtain a
+.B scan
+listing of a maildrop file as produced by
+.BR packf .
+This listing
+includes every message in the file (you can't scan individual messages).
+.PP
+The switch
+.B \-width
+.I columns
+may be used to specify the width of
+the scan line. The default is to use the width of the terminal.
+.PP
+The command:
+.PP
+.RS 5
+(scan | pr ; show a \-showproc pr) | lpr
+.RE
+.PP
+produces a scan listing of the current folder,
+followed by a formatted listing of all messages in the folder, one
+per page. Omitting
+.RB ` "\-showproc\ pr" '
+will cause the messages to be
+concatenated, separated by a one\-line header and two blank lines.
+.PP
+To override the output format used by
+.BR scan ,
+the
+.B \-form
+.I file
+switch is used. This permits individual fields of
+the scan listing to be extracted with ease.
+.I file
+is either the name of a format file or a format string directly,
+if prepended with an equal sign `='.
+See
+.BR mh\-format (5)
+for the details.
+.PP
+In addition to the standard
+.BR mh\-format (5)
+escapes,
+.B scan
+also recognizes the following additional
+.I component
+escapes:
+.PP
+.RS 5
+.nf
+.ta \w'Dtimenow 'u +\w'Returns 'u
+.I "Escape Returns Description
+dtimenow date the current date
+folder string the name of the current folder
+.fi
+.RE
+.PP
+If no date header is present in the message, the
+.I function
+escapes
+which operate on
+.RB { 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.
+.PP
+.B scan
+will update the
+.B mmh
+context prior to starting the listing,
+so interrupting a long
+.B scan
+listing preserves the new context.
+.B nmh
+purists hate this idea.
+
.SH FILES
.fc ^ ~
.nf
.ta 2.4i
.ta \w'ExtraBigProfileName 'u
^Path:~^To determine the user's mail storage
+^Alternate\-Mailboxes:~^To determine the user's mailboxes
^Current\-Folder:~^To find the default current folder
.fi
.SH DEFAULTS
.nf
.RB ` +folder "' defaults to the current folder"
-.RB ` msgs "' defaults to all"
+.RB ` msgs "' defaults to all messages"
.RB ` "\-datefield date" '
.RB ` \-zero '
.RB ` \-list "' is the default if no `\-sequence', `\-nolist' otherwise"
+.RB ` "\-format pick\.default" "' if the program is called with scan `scan.default' is used
.fi
.SH CONTEXT
.fi
.RE
.PP
-Finally, timezones used to be ignored when comparing dates: they aren't
+Also, timezones used to be ignored when comparing dates: they aren't
any more.
-
+.PP
+In
+.B MH
+,
+.B nmh
+and old
+.B mmh
+versions scan and pick where two different tools. So instand of typing
+.PP
+.RS 5
+.nf
+scan\0\-from\0philipp
+.fi
+.RE
+.PP
+you had typed
+.PP
+.RS 5
+.nf
+scan\0`pick\0\-from\0philipp`
+.fi
+.RE
+.PP
+With the default config the old style usage is still supported, so
+you can write scripts for both mmh and nmh.
.SH "HELPFUL HINTS"
Use
.RB ` "pick sequence \-list" '
outputs the illegal message number `0'
when it fails. This lets the outer command fail gracefully as well.
.PP
+To account for this case when combining
+.B pick
+with regular shell tools, filter out the message number `0'.
+For example, do
+.PP
+.RS 5
+pick\0...\0|\0fgrep\0-vx\0\&0\0|\0wc\0-l
+.RE
+.PP
+to count the number of messages picked.
+.PP
The pattern syntax `[l-r]' is not supported; each letter to be
matched must be included within the square brackets.