.\"
.TH PICK %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
.SH NAME
-pick \- search for messages by content
+pick \- select messages by content
+scan \- produce a one line per message scan listing
.SH SYNOPSIS
.HP 5
.na
.IR date ]
.RB [ \-datefield
.IR field ]
+.RB [ \-format
+.IR formatfile ]
+.RB [ \-width
+.IR columns ]
+.RB [ \-thread
+.RI [ +folder ] messages "|" files ]
+.RB [ \-file
+.IR mboxfilename ]
.RB [ \-sequence
.I name
\&...]
.RB [ \-public " | " \-nopublic ]
.RB [ \-zero " | " \-nozero ]
.RB [ \-list " | " \-nolist ]
-.RB [ \-version ]
+.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 \*(lqcomponent[ \\t]*:\&.*pattern\*(rq\ '
-.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 patern.
.PP
-It is used to pick a component which is not one of \*(lqTo:\*(rq,
-\*(lqCc:\*(rq, \*(lqDate:\*(rq, \*(lqFrom:\*(rq, or \*(lqSubject:\*(rq.
+With
+.BR --componend
+you can sepcify 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 \*(lq "pick\0\-\|\-reply\-to\0pooh" \*(rq.
+.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 patern
+will match any case.
.PP
Note that since the
.B \-date
switch is a pattern matching operation (as
described above), to find messages sent on a certain date the pattern
-string must match the text of the \*(lqDate:\*(rq field of the message.
+string must match the text of the `Date:' field of the message.
.PP
Independent of any pattern matching operations requested, the switches
.B \-after
.B \-before
.I date
may also be used to introduce date/time
-constraints on all of the messages. By default, the \*(lqDate:\*(rq
+constraints on all of the messages. By default, the `Date:'
field is consulted, but if another date yielding field (such as
-\*(lqBB\-Posted:\*(rq or \*(lqDelivery\-Date:\*(rq) should be used, the
+`BB\-Posted:' or `Delivery\-Date:') should be used, the
.B \-datefield
.I field
switch may be used.
to the date/time specified. If
.B \-after
is given, then only those
-messages whose \*(lqDate:\*(rq field value is chronologically after the
+messages whose `Date:' field value is chronologically after the
date specified will be considered. The
.B \-before
switch specifies the
In addition to 822\-style dates,
.B pick
will also recognize any of
-the days of the week (\*(lqsunday\*(rq, \*(lqmonday\*(rq, and so on),
-and the special dates \*(lqtoday\*(rq, \*(lqyesterday\*(rq (24 hours
-ago), and \*(lqtomorrow\*(rq (24 hours from now). All days of the
+the days of the week (`sunday', `monday', and so on),
+and the special dates `today', `yesterday' (24 hours
+ago), and `tomorrow' (24 hours from now). All days of the
week are judged to refer to a day in the past (e.g., telling \fIpick\fR
-\*(lqsaturday\*(rq on a \*(lqtuesday\*(rq means \*(lqlast\ saturday\*(rq
-not \*(lqthis\ saturday\*(rq).
-.PP
+`saturday' on a `tuesday' means `last\ saturday'
+not `this\ saturday').
+Further more, dates in a simplified ISO 8601/RFC 3339 style (e.g.
+`YYYY-MM-DD' or `YYYY-MM-DD hh:mm:ss') are accepted.
Finally, in addition to these special specifications,
.B pick
will
-also honor a specification of the form \*(lq\-dd\*(rq, which means
-\*(lqdd days ago\*(rq.
+also honor a date specification of the form `\-\fIddd\fR', which means
+`\fIddd\fR days ago'.
+For example,
+.PP
+.RS 5
+.nf
+pick\0\-after\0\-30
+.fi
+.RE
+.PP
+identifies the messages of the last thirty days.
.PP
.B Pick
supports complex boolean operations on the searching primitives
.fi
.RE
.PP
-identifies messages recently sent by \*(lqfrieda\*(rq or \*(lqfear\*(rq.
+identifies messages recently sent by `frieda' or `fear'.
.PP
The matching primitives take precedence over the
.B \-not
parentheses in logical expressions.
.PP
If no search criteria are given, all the messages specified on the
-command line are selected (this defaults to \*(lqall\*(rq).
+command line are selected (this defaults to `a').
.PP
Once the search has been performed, if the
.B \-list
.B extremely
useful for
quickly generating arguments for other
-.B nmh
+.B mmh
programs by using the
-\*(lqbackquoting\*(rq syntax of the shell. For example, the command
+`backquoting' syntax of the shell. For example, the command
.PP
.RS 5
-scan\0`pick\0+todo\0\-after\0\*(lq31 Mar 83 0123 PST\*(rq`
+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
.RE
.PP
defines a new message sequence for the current folder called
-\*(lqfred\*(rq which contains exactly those messages that were selected.
+`fred' which contains exactly those messages that were selected.
.PP
By default,
.B pick
.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 folowing 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 programm is called with scan `scan.default' is used
.fi
.SH CONTEXT
or
.B refile
the selected messages. This was rather
-\*(lqinverted logic\*(rq from the UNIX point of view, so
+`inverted logic' from the UNIX point of view, so
.B pick
was changed to define sequences and output those sequences. Hence,
.B pick
something like:
.PP
.RS 5
-show\0`pick\0last:20\0\-seq\0fear`
+show\0`pick\0l:20\0\-seq\0fear`
.RE
.PP
instead of typing
.PP
.RS 5
.nf
-mark\0\-add\0\-nozero\0\-seq\0fear\0last:20
+mark\0\-add\0\-nozero\0\-seq\0fear\0l:20
show\0fear
.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 diffrent 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 \*(lq "pick sequence \-list" \*(rq
+.RB ` "pick sequence \-list" '
to enumerate the messages in a sequence
(such as for use by a shell script).
.SH BUGS
-The argument to the
-.B \-after
-and
-.B \-before
-switches must be interpreted
-as a single token by the shell that invokes
-.BR pick .
-Therefore, one
-must usually place the argument to this switch inside double\-quotes.
-Furthermore, any occurrence of
+Any occurrence of
.B \-datefield
must occur prior to the
.B \-after
and
.B pick
selects no messages (e.g., no messages are from
-\*(lqjones\*(rq), then the shell will still run the outer command (e.g.,
+`jones'), then the shell will still run the outer command (e.g.,
.BR scan ).
Since no messages were matched,
.B pick
backquoting
.B pick
is empty. In the case of
-.B nmh
+.B mmh
programs,
the outer command now acts as if the default `msg' or `msgs' should be
-used (e.g., \*(lqall\*(rq in the case of
+used (e.g., `all' in the case of
.BR scan ).
To prevent this
unexpected behavior, if
.B \-list
was given, and if its standard output is not a tty, then
.B pick
-outputs the illegal message number \*(lq0\*(rq
+outputs the illegal message number `0'
when it fails. This lets the outer command fail gracefully as well.
.PP
-The pattern syntax \*(lq[l-r]\*(rq is not supported; each letter to be
+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.
projects / mmh / blobdiff