.\" %nmhwarning%
.\" $Id$
.\"
-.\" include the -mh macro file
-.so %etcdir%/tmac.h
-.\"
-.TH PICK %manext1% MH.6.8 [%nmhversion%]
+.TH PICK %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
.SH NAME
pick \- search for messages by content
.SH SYNOPSIS
-.in +.5i
-.ti -.5i
-pick
-\%[+folder] \%[msgs]
-\%[\-and\ ...] \%[\-or\ ...] \%[\-not\ ...]
-.br
-\%[\-lbrace\ ...\ \-rbrace]
-\%[\-\|\-component\ pattern]
-.br
-\%[\-cc\ pattern]
-\%[\-date\ pattern]
-\%[\-from\ pattern]
-.br
-\%[\-search\ pattern]
-\%[\-subject\ pattern]
-\%[\-to\ pattern]
-.br
-\%[\-after\ date]
-\%[\-before\ date]
-\%[\-datefield\ field]
-.br
-\%[\-sequence\ name\ ...]
-\%[\-public] \%[\-nopublic]
-\%[\-zero]
-.br
-\%[\-nozero]
-\%[\-list] \%[\-nolist]
-\%[\-version]
-\%[\-help]
-.ti .5i
-
+.HP 5
+.na
+.B pick
+.RI [ +folder ]
+.RI [ msgs ]
+.RB [ \-and
+\&...]
+.RB [ \-or
+\&...]
+.RB [ \-not
+\&...]
+.RB [ \-lbrace
+\&...
+.BR \-rbrace ]
+.RB [ \-\|\-component
+.IR pattern ]
+.RB [ \-cc
+.IR pattern ]
+.RB [ \-date
+.IR pattern ]
+.RB [ \-from
+.IR pattern ]
+.RB [ \-search
+.IR pattern ]
+.RB [ \-subject
+.IR pattern ]
+.RB [ \-to
+.IR pattern ]
+.RB [ \-after
+.IR date ]
+.RB [ \-before
+.IR date ]
+.RB [ \-datefield
+.IR field ]
+.RB [ \-sequence
+.I name
+\&...]
+.RB [ \-public " | " \-nopublic ]
+.RB [ \-zero " | " \-nozero ]
+.RB [ \-list " | " \-nolist ]
+.RB [ \-version ]
+.RB [ \-help ]
+.PP
typical usage:
-.br
+.PP
+.RS 5
+.nf
scan\0`pick\0\-from\0jones`
-.br
pick\0\-to\0holloway\0\-sequence\0select
-.br
show\0`pick\0\-before\0friday`
-.in -.5i
+.fi
+.RE
+.ad
.SH DESCRIPTION
-\fIPick\fR searches within a folder for messages with the specified
+.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
operations.
-
-A modified \fIgrep\fR(1) is used to perform the matching, so the
-full regular expression (see \fIed\fR(1)) facility is available
-within `pattern'. With `\-search', `pattern' is used directly,
-and with the others, the grep pattern constructed is:
-
-.ti +.5i
-\*(lqcomponent[ \\t]*:\&.*pattern\*(rq
-
-This means that the pattern specified for a `\-search' will be found
+.PP
+A modified
+.BR grep (1)
+is used to perform the matching, so the
+full regular expression (see
+.BR ed (1))
+facility is available
+within
+.IR pattern .
+With
+.BR \-search ,
+.I pattern
+is used directly, and with the others, the grep pattern constructed is:
+.PP
+.RS 5
+`component[ \\t]*:\&.*pattern'
+.RE
+.PP
+This means that the pattern specified for a
+.B \-search
+will be found
everywhere in the message, including the header and the body, while
the other pattern matching requests are limited to the single specified
component. The expression
-
-.ti +.5i
+.PP
+.RS 5
`\-\|\-component\ pattern'
-
+.RE
+.PP
is a shorthand for specifying
-
-.ti +.5i
+.PP
+.RS 5
`\-search \*(lqcomponent[ \\t]*:\&.*pattern\*(rq\ '
-
+.RE
+.PP
It is used to pick a component which is not one of \*(lqTo:\*(rq,
\*(lqcc:\*(rq, \*(lqDate:\*(rq, \*(lqFrom:\*(rq, or \*(lqSubject:\*(rq.
-An example is `pick\0\-\|\-reply\-to\0pooh'.
-
+An example is
+.RB \*(lq "pick\0\-\|\-reply\-to\0pooh" \*(rq.
+.PP
Pattern matching is performed on a per\-line basis. Within the header
of the message, each component is treated as one long line, but in the
body, each line is separate. Lower\-case letters in the search pattern
will match either lower or upper case in the message, while upper case
will match only upper case.
-
-Note that since the `\-date' switch is a pattern matching operation (as
+.PP
+Note that since the
+.B \-date
+switch is a pattern matching operation (as
described above), to find messages sent on a certain date the pattern
string must match the text of the \*(lqDate:\*(rq field of the message.
-
+.PP
Independent of any pattern matching operations requested, the switches
-`\-after date' or `\-before date' may also be used to introduce date/time
+.B \-after
+.I date
+or
+.B \-before
+.I date
+may also be used to introduce date/time
constraints on all of the messages. By default, the \*(lqDate:\*(rq
field is consulted, but if another date yielding field (such as
\*(lqBB\-Posted:\*(rq or \*(lqDelivery\-Date:\*(rq) should be used, the
-`\-datefield\ field' switch may be used.
-
-With `\-before' and `\-after', \fIpick\fR will actually parse the date
+.B \-datefield
+.I field
+switch may be used.
+.PP
+With
+.B \-before
+and
+.BR \-after ,
+.B pick
+will actually parse the date
fields in each of the messages specified in `msgs' and compare them
-to the date/time specified. If `\-after' is given, then only those
+to the date/time specified. If
+.B \-after
+is given, then only those
messages whose \*(lqDate:\*(rq field value is chronologically after the
-date specified will be considered. The `\-before' switch specifies the
+date specified will be considered. The
+.B \-before
+switch specifies the
complimentary action.
-
-Both the `\-after' and `\-before' switches take legal 822\-style date
-specifications as arguments. \fIPick\fR will default certain missing
+.PP
+Both the
+.B \-after
+and
+.B \-before
+switches take legal 822\-style date
+specifications as arguments.
+.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.
-
-In addition to 822\-style dates, \fIpick\fR will also recognize any of
+.PP
+In addition to 822\-style dates,
+.B pick
+will also recognize any of
the days of the week (\*(lqsunday\*(rq, \*(lqmonday\*(rq, and so on),
and the special dates \*(lqtoday\*(rq, \*(lqyesterday\*(rq (24 hours
ago), and \*(lqtomorrow\*(rq (24 hours from now). All days of the
week are judged to refer to a day in the past (e.g., telling \fIpick\fR
\*(lqsaturday\*(rq on a \*(lqtuesday\*(rq means \*(lqlast\ saturday\*(rq
not \*(lqthis\ saturday\*(rq).
-
-Finally, in addition to these special specifications, \fIpick\fR will
+.PP
+Finally, in addition to these special specifications,
+.B pick
+will
also honor a specification of the form \*(lq\-dd\*(rq, which means
\*(lqdd days ago\*(rq.
-
-\fIPick\fR supports complex boolean operations on the searching primitives
-with the `\-and', `\-or', `\-not', and `\-lbrace\ ...\ \-rbrace' switches.
+.PP
+.B Pick
+supports complex boolean operations on the searching primitives
+with the
+.BR \-and ,
+.BR \-or ,
+.BR \-not ,
+and
+.B \-lbrace
+.B \&...
+.B \-rbrace
+switches.
For example,
-
-.ti +.5i
-.ie t \{\
-pick\0\-after\0yesterday\0\-and\0\-lbrace\0\-from\0freida\0\-or\0\-from\0fear\0\-rbrace
-.\}
-.el \{\
+.PP
+.RS 5
+.nf
pick\0\-after\0yesterday\0\-and
-.br
-.ti +1i
-\-lbrace\0\-from\0freida\0\-or\0\-from\0fear\0\-rbrace
-.\}
-
+ \-lbrace\0\-from\0freida\0\-or\0\-from\0fear\0\-rbrace
+.fi
+.RE
+.PP
identifies messages recently sent by \*(lqfrieda\*(rq or \*(lqfear\*(rq.
-
-The matching primitives take precedence over the `\-not' switch, which
-in turn takes precedence over `\-and' which in turn takes precedence
-over `\-or'. To override the default precedence, the `\-lbrace' and
-`\-rbrace' switches are provided, which act just like opening and closing
+.PP
+The matching primitives take precedence over the
+.B \-not
+switch, which in turn takes precedence over
+.B \-and
+which in turn takes precedence
+over
+.BR \-or .
+To override the default precedence, the
+.B \-lbrace
+and
+.B \-rbrace
+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 \*(lqall\*(rq).
-
-Once the search has been performed, if the `\-list' switch is given, the
+.PP
+Once the search has been performed, if the
+.B \-list
+switch is given, the
message numbers of the selected messages are written to the standard
-output separated by newlines. This is \fIextremely\fR useful for
-quickly generating arguments for other \fInmh\fR programs by using the
+output separated by newlines. This is
+.B extremely
+useful for
+quickly generating arguments for other
+.B nmh
+programs by using the
\*(lqbackquoting\*(rq syntax of the shell. For example, the command
-
-.ti +.5i
+.PP
+.RS 5
scan\0`pick\0+todo\0\-after\0\*(lq31 Mar 83 0123 PST\*(rq`
-
-says to \fIscan\fR those messages in the indicated folder which meet the
-appropriate criterion. Note that since \fIpick\fR\0's context changes
-are written out prior to \fIscan\fR\0's invocation, you need not give
-the folder argument to \fIscan\fR as well.
-
-Regardless of the operation of the `\-list' switch, the `\-sequence name'
+.RE
+.PP
+says to
+.B scan
+those messages in the indicated folder which meet the
+appropriate criterion. Note that since
+.BR pick 's
+context changes
+are written out prior to
+.BR scan 's
+invocation, you need not give
+the folder argument to
+.B scan
+as well.
+.PP
+Regardless of the operation of the
+.B \-list
+switch, the
+.B \-sequence
+.I name
switch may be given once for each sequence the user wishes to define.
For each sequence named, that sequence will be defined to mean exactly
-those messages selected by \fIpick\fR. For example,
-
-.ti +.5i
+those messages selected by
+.BR pick .
+For example,
+.PP
+.RS 5
pick\0\-from\0frated\0\-seq\0fred
-
+.RE
+.PP
defines a new message sequence for the current folder called
\*(lqfred\*(rq which contains exactly those messages that were selected.
-
-Note that whenever \fIpick\fR processes a `\-sequence\ name' switch, it
-sets `\-nolist'.
-
-By default, \fIpick\fR will zero the sequence before adding it. This
-action can be disabled with the `\-nozero' switch, which means that the
-messages selected by \fIpick\fR will be added to the sequence, if it
+.PP
+Note that whenever
+.B pick
+processes a
+.B \-sequence
+.I name
+switch, it
+sets
+.BR \-nolist .
+.PP
+By default,
+.B pick
+will zero the sequence before adding it. This
+action can be disabled with the
+.B \-nozero
+switch, which means that the
+messages selected by
+.B pick
+will be added to the sequence, if it
already exists, and any messages already a part of that sequence will
remain so.
-
-The `\-public' and `\-nopublic' switches are used by \fIpick\fR in the
-same way \fImark\fR uses them.
-.Fi
+.PP
+The
+.B \-public
+and
+.B \-nopublic
+switches are used by
+.B pick
+in the
+same way
+.B mark
+uses them.
+
+.SH FILES
+.fc ^ ~
+.nf
+.ta \w'/usr/local/nmh/etc/ExtraBigFileName 'u
^$HOME/\&.mh\(ruprofile~^The user profile
-.Pr
+.fi
+
+.SH "PROFILE COMPONENTS"
+.fc ^ ~
+.nf
+.ta 2.4i
+.ta \w'ExtraBigProfileName 'u
^Path:~^To determine the user's nmh directory
-.Ps
^Current\-Folder:~^To find the default current folder
-.Sa
+.fi
+
+.SH "SEE ALSO"
mark(1)
-.De
-`+folder' defaults to the current folder
-.Ds
-`msgs' defaults to all
-.Ds
-`\-datefield date'
-.Ds
-`\-zero'
-.Ds
-`\-list' is the default if no `\-sequence', `\-nolist' otherwise
-.Co
+
+.SH DEFAULTS
+.nf
+.RB ` +folder "' defaults to the current folder"
+.RB ` msgs "' defaults to all"
+.RB ` "\-datefield date" '
+.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.
-.Hi
-In previous versions of \fIMH\fR, the \fIpick\fR command would \fIshow\fR,
-\fIscan\fR, or \fIrefile\fR the selected messages. This was rather
-\*(lqinverted logic\*(rq from the UNIX point of view, so \fIpick\fR was
-changed to define sequences and output those sequences. Hence, \fIpick\fR
-can be used to generate the arguments for all other \fIMH\fR commands,
-instead of giving \fIpick\fR endless switches for invoking those commands
-itself.
-Also, previous versions of \fIpick\fR balked if you didn't specify
+.SH HISTORY
+In previous versions of
+.BR MH ,
+the
+.B pick
+command would
+.BR show ,
+.BR scan ,
+or
+.B refile
+the selected messages. This was rather
+\*(lqinverted logic\*(rq from the UNIX point of view, so
+.B pick
+was changed to define sequences and output those sequences. Hence,
+.B pick
+can be used to generate the arguments for all other
+.B MH
+commands, instead of giving
+.B pick
+endless switches for invoking those commands
+itself.
+.PP
+Also, previous versions of
+.B pick
+balked if you didn't specify
a search string or a date/time constraint. The current version does
not, and merely matches the messages you specify. This lets you type
something like:
-
-.ti +.5i
+.PP
+.RS 5
show\0`pick\0last:20\0\-seq\0fear`
-
+.RE
+.PP
instead of typing
-
-.in +.5i
+.PP
+.RS 5
.nf
mark\0\-add\0\-nozero\0\-seq\0fear\0last:20
show\0fear
.fi
-.in -.5i
-
+.RE
+.PP
Finally, timezones used to be ignored when comparing dates: they aren't
any more.
-.Hh
-Use \*(lqpick sequence \-list\*(rq to enumerate the messages in a sequence
-(such as for use by a shell script).
-.Bu
-The argument to the `\-after' and `\-before' switches must be interpreted
-as a single token by the shell that invokes \fIpick\fR. Therefore, one
-must usually place the argument to this switch inside double\-quotes.
-Furthermore, any occurrence of `\-datefield' must occur prior to the
-`\-after' or `\-before' switch it applies to.
-If \fIpick\fR is used in a back\-quoted operation, such as
+.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).
-.ti +.5i
+.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
+.B \-datefield
+must occur prior to the
+.B \-after
+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`
-
-and \fIpick\fR selects no messages (e.g., no messages are from
+.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.,
-\*(lqscan\*(rq). Since no messages were matched, \fIpick\fR produced
+.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 \fIpick\fR is empty. In the case of \fInmh\fR programs,
+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 \fIscan\fR\0). To prevent this
-unexpected behavior, if `\-list' was given, and if its standard output is
-not a tty, then \fIpick\fR outputs the illegal message number \*(lq0\*(rq
+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.
-
-.sp
+.PP
The pattern syntax \*(lq[l-r]\*(rq is not supported; each letter to be
matched must be included within the square brackets.
-.En
projects / mmh / blobdiff