--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/pick.me	Mon Apr 18 23:46:02 2005 +0900
@@ -0,0 +1,300 @@
+.\"	This file is automatically generated.  Do not edit!
+.\" @(#)$Id$
+.SC PICK 1
+.NA
+pick \- select messages by content
+.SY
+.ie t \{\
+.ta .4i 1.8i
+.nf
+.in .5i
+^pick~^^\0\-cc~^ \%[+folder] \%[msgs] \%[\-help]
+^^^\0\-date~^ \%[\-before\ date] \%[\-after\ date] \%[\-datefield\ field]
+^^^\0\-from~^
+^^^\s+2\b'\(lt\(bv\(bv\(lk\(bv\(bv\(lb'\s0\-search~\s+2\b'\(rt\(bv\(bv\(rk\(bv\(bv\(rb'\s0^ pattern \%[\-and\ ...] \%[\-or\ ...] \%[\-not\ ...] \%[\-lbrace\ ...\ \-rbrace]
+^^^\0\-subject~^
+^^^\0\-to~^ \%[\-sequence\ name\ ...] \%[\-public] \%[\-nopublic] \%[\-zero] \%[\-nozero]
+^^^\0\-\|\-component~^ \%[\-list] \%[\-nolist]
+.fi
+.re
+.in 1i
+.\}
+.el \{\
+.ti .5i
+pick
+\%[+folder] \%[msgs]
+\%[\-and\ ...] \%[\-or\ ...] \%[\-not\ ...] \%[\-lbrace\ ...\ \-rbrace]
+\%[\-\|\-component\ pattern]
+\%[\-cc\ pattern]
+\%[\-date\ pattern]
+\%[\-from\ pattern]
+\%[\-search\ pattern]
+\%[\-subject\ pattern]
+\%[\-to\ pattern]
+\%[\-after\ date] \%[\-before\ date] \%[\-datefield\ field]
+\%[\-sequence\ name\ ...]
+\%[\-public] \%[\-nopublic]
+\%[\-zero] \%[\-nozero]
+\%[\-list] \%[\-nolist]
+\%[\-help]
+.\}
+
+.ti .5i
+typically:
+.br
+scan\0`pick\0\-from\0jones`
+.br
+pick\0\-to\0holloway\0\-sequence\0select
+.br
+show\0`pick\0\-before\0friday`
+.DE
+\fIPick\fR searches messages within a folder for 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 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
+`\-\|\-component\ pattern'
+
+is a shorthand for specifying
+
+.ti +.5i
+`\-search \*(lqcomponent[ \\t]*:\&.*pattern\*(rq\ '
+
+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'.
+
+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 
+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.
+
+Independent of any pattern matching operations requested,
+the switches `\-after date' or `\-before date' may also be used
+to introduce date/time contraints 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 fields in each of the messages
+specified in `msgs'
+and compare them to the date/time specified.
+If `\-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 complimentary action.
+
+Both the `\-after' and `\-before' switches take legal 822\-style date
+specifications as arguments.
+\fIPick\fR 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 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 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.
+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 \{\
+pick\0\-after\0yesterday\0\-and
+.br
+.ti +1i
+\-lbrace\0\-from\0freida\0\-or\0\-from\0fear\0\-rbrace
+.\}
+
+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 parentheses in logical expressions.
+
+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 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
+\fIMH\fR programs by using the \*(lqbackquoting\*(rq syntax of the shell.
+For example,
+the command
+
+.ti +.5i
+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' 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
+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.
+
+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 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
+^$HOME/\&.mh\(ruprofile~^The user profile
+.Pr
+^Path:~^To determine the user's MH directory
+.Ps
+^Current\-Folder:~^To find the default current folder
+.Sa
+mark(1)
+.De
+`+folder' defaults to the current folder
+.Ds
+`msgs' defaults to all
+.Ds
+`\-datefield date'
+.Ds
+`\-nopublic' if the folder is read\-only, `\-public' otherwise
+.Ds
+`\-zero'
+.Ds
+`\-list' is the default if no `\-sequence', `\-nolist' otherwise
+.Co
+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 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
+show\0`pick\0last:20\0\-seq\0fear`
+
+instead of typing
+
+.in +.5i
+.nf
+mark\0\-add\0\-nozero\0\-seq\0fear\0last:20
+show\0fear
+.fi
+.in -.5i
+
+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 occurance 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
+
+.ti +.5i
+scan\0`pick\0\-from\0jones`
+
+and \fIpick\fR 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 no output,
+and the argument given to the outer command as a result of backquoting
+\fIpick\fR is empty.
+In the case of \fIMH\fR 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 when it fails.
+This lets the outer command fail gracefully as well.
+.sp
+The pattern syntax \*(lq[l-r]\*(rq is not supported; each letter
+to be matched must be included within the square brackets.
+.En