Added context_find_prefix().

[nmh] / man / pick.man

diff --git a/man/pick.man b/man/pick.man
index 2db25277b4d0b445317a4fd88806e54a289d1563..9d7cdcf554315393af1ee1f611c30c0b3158152c 100644 (file)
--- a/man/pick.man
+++ b/man/pick.man
@@ -1,4 +1,4 @@
-.TH PICK %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
+.TH PICK %manext1% "August 3, 2014" "%nmhversion%"

 .\"
 .\" %nmhwarning%
 .\"
 .\"
 .\" %nmhwarning%
 .\"


@@ -10,6 +10,8 @@ pick \- search for messages by content
 .B pick
 .RI [ +folder ]
 .RI [ msgs ]
 .B pick
 .RI [ +folder ]
 .RI [ msgs ]

+.RB [ \-reverse
+\&...]

 .RB [ \-and
 \&...]
 .RB [ \-or
 .RB [ \-and
 \&...]
 .RB [ \-or


@@ -42,9 +44,11 @@ pick \- search for messages by content
 .RB [ \-sequence
 .I name
 \&...]
 .RB [ \-sequence
 .I name
 \&...]

+.RB [ \-nosequence ]

 .RB [ \-public " | " \-nopublic ]
 .RB [ \-zero " | " \-nozero ]
 .RB [ \-list " | " \-nolist ] 
 .RB [ \-public " | " \-nopublic ]
 .RB [ \-zero " | " \-nozero ]
 .RB [ \-list " | " \-nolist ] 

+.RB [ \-debug ]

 .RB [ \-version ]
 .RB [ \-help ]
 .PP
 .RB [ \-version ]
 .RB [ \-help ]
 .PP


@@ -150,7 +154,7 @@ Both the
 .B \-after
 and
 .B \-before
 .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
 specifications as arguments.
 .B Pick
 will default certain missing


@@ -159,7 +163,7 @@ 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
 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),
 .B pick
 will also recognize any of
 the days of the week (\*(lqsunday\*(rq, \*(lqmonday\*(rq, and so on),


@@ -175,6 +179,20 @@ will
 also honor a specification of the form \*(lq\-dd\*(rq, which means
 \*(lqdd days ago\*(rq.
 .PP
 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 Pick
 supports complex boolean operations on the searching primitives
 with the


@@ -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
 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
 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
 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.
 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
 .SH FILES
 .fc ^ ~
 .nf

-.ta \w'%etcdir%/ExtraBigFileName  'u
+.ta \w'%nmhetcdir%/ExtraBigFileName  'u

 ^$HOME/\&.mh\(ruprofile~^The user profile
 .fi
 .SH "PROFILE COMPONENTS"
 ^$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
 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 \-datefield
 must occur prior to the
 .B \-after


@@ -374,38 +426,5 @@ or
 .B \-before
 switch it applies to.
 .PP
 .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.
 The pattern syntax \*(lq[l-r]\*(rq is not supported; each letter to be
 matched must be included within the square brackets.