-.TH PICK %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
+.TH PICK %manext1% "August 3, 2014" "%nmhversion%"
.\"
.\" %nmhwarning%
.\"
.HP 5
.na
.B pick
+.RB [ \-help ]
+.RB [ \-version ]
.RI [ +folder ]
.RI [ msgs ]
+.RB [ \-reverse
+\&...]
.RB [ \-and
\&...]
.RB [ \-or
.RB [ \-sequence
.I name
\&...]
+.RB [ \-nosequence ]
.RB [ \-public " | " \-nopublic ]
.RB [ \-zero " | " \-nozero ]
.RB [ \-list " | " \-nolist ]
-.RB [ \-version ]
-.RB [ \-help ]
+.RB [ \-debug ]
.PP
typical usage:
.PP
.RE
.ad
.SH DESCRIPTION
-.B Pick
+.B pick
searches within a folder for messages with the specified
contents, and then identifies those messages. Two types of search
primitives are available: pattern matching and date constraint
.B \-after
and
.B \-before
-switches take legal 822\-style date
+switches take legal RFC 822\-style date
specifications as arguments.
-.B Pick
+.B pick
will default certain missing
fields so that the entire date need not be specified. These fields
are (in order of defaulting): timezone, time and timezone, date, date
and timezone. All defaults are taken from the current date, time,
and timezone.
.PP
-In addition to 822\-style dates,
+In addition to RFC 822\-style dates,
.B pick
will also recognize any of
the days of the week (\*(lqsunday\*(rq, \*(lqmonday\*(rq, and so on),
also honor a specification of the form \*(lq\-dd\*(rq, which means
\*(lqdd days ago\*(rq.
.PP
-.B Pick
+Use the
+.BR \-reverse
+switch to make
+.B pick
+find matching messages in reverse order, working from the highest message
+number down to the lowest. This can be useful in for searching recent
+messages in large folders, for example,
+.PP
+.RS 5
+.nf
+pick\0\-reverse\0\-from\0frated\0|\0xargs\0\-n1\0scan
+.fi
+.RE
+.PP
+.B pick
supports complex boolean operations on the searching primitives
with the
.BR \-and ,
defines a new message sequence for the current folder called
\*(lqfred\*(rq which contains exactly those messages that were selected.
.PP
+The
+.B \-nosequence
+switch will disable all previously named sequences, allowing
+those established by a profile component to be overridden.
+.PP
By default,
.B pick
-will zero the sequence before adding it. This
+will zero a sequence before adding it. This
action can be disabled with the
.B \-nozero
switch, which means that the
same way
.B mark
uses them.
+.PP
+The
+.B \-debug
+switch causes pick to output a representation of the search
+pattern.
+.SS "Output when no messages are matched"
+If
+.B pick
+is used in a backquoted operation, such as
+.PP
+.RS 5
+scan\0`pick\0\-from\0jones`
+.RE
+.PP
+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.,
+.BR scan ).
+Since no messages were matched,
+.B pick
+produced
+no output, and the argument given to the outer command as a result of
+backquoting
+.B pick
+is empty. In the case of
+.B nmh
+programs,
+the outer command now acts as if the default `msg' or `msgs' should be
+used (e.g., \*(lqall\*(rq 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
+when it fails. This lets the outer command fail gracefully as well.
.SH FILES
.fc ^ ~
.nf
-.ta \w'%etcdir%/ExtraBigFileName 'u
+.ta \w'%nmhetcdir%/ExtraBigFileName 'u
^$HOME/\&.mh\(ruprofile~^The user profile
.fi
.SH "PROFILE COMPONENTS"
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 quotes.
-Furthermore, any occurrence of
+Any occurrence of
.B \-datefield
must occur prior to the
.B \-after
.B \-before
switch it applies to.
.PP
-If
-.B pick
-is used in a back\-quoted operation, such as
-.PP
-.RS 5
-scan\0`pick\0\-from\0jones`
-.RE
-.PP
-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.,
-.BR scan ).
-Since no messages were matched,
-.B pick
-produced
-no output, and the argument given to the outer command as a result of
-backquoting
-.B pick
-is empty. In the case of
-.B nmh
-programs,
-the outer command now acts as if the default `msg' or `msgs' should be
-used (e.g., \*(lqall\*(rq 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
-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
matched must be included within the square brackets.
projects / nmh / blobdiff