+.TH PICK %manext1% "August 3, 2014" "%nmhversion%"
.\"
.\" %nmhwarning%
-.\" $Id$
.\"
-.TH PICK %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
.SH NAME
pick \- search for messages by content
.SH SYNOPSIS
.B pick
.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 [ \-debug ]
.RB [ \-version ]
.RB [ \-help ]
.PP
operations.
.PP
A modified
-.BR grep (1)
+.IR grep (1)
is used to perform the matching, so the
full regular expression (see
-.BR ed (1))
+.IR ed (1))
facility is available
within
.IR pattern .
.B \-after
and
.B \-before
-switches take legal 822\-style date
+switches take legal RFC 822\-style date
specifications as arguments.
.B Pick
will default certain missing
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
+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
.B scan
as well.
.PP
-Regardless of the operation of the
-.B \-list
-switch, the
+The
.B \-sequence
.I name
switch may be given once for each sequence the user wishes to define.
defines a new message sequence for the current folder called
\*(lqfred\*(rq which contains exactly those messages that were selected.
.PP
-Note that whenever
-.B pick
-processes a
-.B \-sequence
-.I name
-switch, it
-sets
-.BR \-nolist .
+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'/usr/local/nmh/etc/ExtraBigFileName 'u
+.ta \w'%nmhetcdir%/ExtraBigFileName 'u
^$HOME/\&.mh\(ruprofile~^The user profile
.fi
-
.SH "PROFILE COMPONENTS"
.fc ^ ~
.nf
^Path:~^To determine the user's nmh directory
^Current\-Folder:~^To find the default current folder
.fi
-
.SH "SEE ALSO"
-mark(1)
-
+.IR mark (1)
.SH DEFAULTS
.nf
.RB ` +folder "' defaults to the current folder"
.RB ` \-zero '
.RB ` \-list "' is the default if no `\-sequence', `\-nolist' otherwise"
.fi
-
.SH CONTEXT
If a folder is given, it will become the current folder.
-
.SH HISTORY
In previous versions of
.BR MH ,
.PP
Finally, timezones used to be ignored when comparing dates: they aren't
any more.
-
.SH "HELPFUL HINTS"
Use
.RB \*(lq "pick sequence \-list" \*(rq
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
.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