X-Git-Url: http://git.marmaro.de/?p=mmh;a=blobdiff_plain;f=man%2Fpick.man;h=e523dd40f94265e3b19ca4d9e95156381761870f;hp=6195cf94826c1f7b33101971cd5ae23362f8da40;hb=3d7993e40a34f52e2b6394c2f64ef0111ab886f7;hpb=b36e2ab7892cdf30a8b33d02e00af70398013b5d diff --git a/man/pick.man b/man/pick.man index 6195cf9..e523dd4 100644 --- a/man/pick.man +++ b/man/pick.man @@ -2,263 +2,430 @@ .\" %nmhwarning% .\" $Id$ .\" -.\" include the -mh macro file -.so %etcdir%/tmac.h -.\" .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