X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/d1cb667bddf8d1c5c0721fc7ab642c22946baf1f..bfc6b93af:/man/pick.man?ds=inline

diff --git a/man/pick.man b/man/pick.man
index aca09182..dbed194a 100644
--- a/man/pick.man
+++ b/man/pick.man
@@ -1,4 +1,4 @@
-.TH PICK %manext1% "March 6, 2012" "%nmhversion%"
+.TH PICK %manext1% "August 3, 2014" "%nmhversion%"
 .\"
 .\" %nmhwarning%
 .\"
@@ -8,8 +8,12 @@ pick \- search for messages by content
 .HP 5
 .na
 .B pick
+.RB [ \-help ]
+.RB [ \-version ]
 .RI [ +folder ]
 .RI [ msgs ]
+.RB [ \-reverse
+\&...]
 .RB [ \-and
 \&...]
 .RB [ \-or
@@ -42,11 +46,11 @@ pick \- search for messages by content
 .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
@@ -59,7 +63,7 @@ show\0`pick\0\-before\0friday`
 .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
@@ -150,16 +154,16 @@ Both the
 .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),
@@ -175,7 +179,21 @@ will
 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 ,
@@ -259,9 +277,14 @@ pick\0\-from\0frated\0\-seq\0fred
 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
@@ -281,10 +304,48 @@ in 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"
@@ -357,16 +418,7 @@ Use
 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
@@ -374,38 +426,5 @@ or
 .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.