Add example to pick.1 for handling empty result set in the shell

[mmh] / man / pick.man1

diff --git a/man/pick.man1 b/man/pick.man1
index 7b1263f..2390984 100644 (file)
--- a/man/pick.man1
+++ b/man/pick.man1
@@ -3,7 +3,7 @@
 .\"
 .TH PICK %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
 .SH NAME
-pick \- search for messages by content
+pick \- select messages by content
 .SH SYNOPSIS
 .HP 5
 .na
@@ -169,6 +169,8 @@ 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
 `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
@@ -221,7 +223,7 @@ switches are provided, which act just like opening and closing
 parentheses in logical expressions.
 .PP
 If no search criteria are given, all the messages specified on the
-command line are selected (this defaults to `all').
+command line are selected (this defaults to `a').
 .PP
 Once the search has been performed, if the
 .B \-list
@@ -231,7 +233,7 @@ output separated by newlines.  This is
 .B extremely
 useful for
 quickly generating arguments for other
-.B nmh
+.B mmh
 programs by using the
 `backquoting' syntax of the shell.  For example, the command
 .PP
@@ -313,7 +315,7 @@ mark(1)
 .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"
@@ -352,14 +354,14 @@ not, and merely matches the messages you specify.  This lets you type
 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
@@ -402,7 +404,7 @@ 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
+.B mmh
 programs,
 the outer command now acts as if the default `msg' or `msgs' should be
 used (e.g., `all' in the case of
@@ -415,5 +417,16 @@ was given, and if its standard output is not a tty, then
 outputs the illegal message number `0'
 when it fails.  This lets the outer command fail gracefully as well.
 .PP
+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.