X-Git-Url: http://git.marmaro.de/?p=mmh;a=blobdiff_plain;f=man%2Fpick.man1;h=2de3ce5659dbd6149e7d096b3c5047ae5992fc98;hp=e9d1941c5de9b7229d03431531410b3f95710127;hb=d0855b62a07b36c5c5e9c90adbdbac0489027ddd;hpb=18272eafd1dd4c2c594724da3d850e794f191566 diff --git a/man/pick.man1 b/man/pick.man1 index e9d1941..2de3ce5 100644 --- a/man/pick.man1 +++ b/man/pick.man1 @@ -3,7 +3,8 @@ .\" .TH PICK %manext1% "%nmhdate%" MH.6.8 [%nmhversion%] .SH NAME -pick \- search for messages by content +pick \- select messages by content +scan \- produce a one line per message scan listing .SH SYNOPSIS .HP 5 .na @@ -39,21 +40,34 @@ pick \- search for messages by content .IR date ] .RB [ \-datefield .IR field ] +.RB [ \-format +.IR formatfile ] +.RB [ \-width +.IR columns ] +.RB [ \-thread +.RI [ +folder ] messages "|" files ] +.RB [ \-file +.IR mboxfilename ] .RB [ \-sequence .I name \&...] .RB [ \-public " | " \-nopublic ] .RB [ \-zero " | " \-nozero ] .RB [ \-list " | " \-nolist ] -.RB [ \-version ] +.RB [ \-Version ] .RB [ \-help ] +.PP +.HP 5 +.B scan +is equivalent to +.B pick -format scan.default .ad .PP typical usage: .PP .RS 5 .nf -scan\0`pick\0\-from\0jones` +scan\0\-from\0jones` pick\0\-to\0holloway\0\-sequence\0select show\0`pick\0\-before\0friday` .fi @@ -66,56 +80,41 @@ contents, and then identifies those messages. Two types of search primitives are available: pattern matching and date constraint operations. .PP -A modified -.BR grep (1) +The default +.BR regex (7) is used to perform the matching, so the -full regular expression (see -.BR ed (1)) -facility is available +full regular expression facility is available within -.IR pattern . +.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 -.PP -.RS 5 -`\-\|\-component\ pattern' -.RE -.PP -is a shorthand for specifying -.PP -.RS 5 -`\-search \*(lqcomponent[ \\t]*:\&.*pattern\*(rq\ ' -.RE +is used directly, but only for the body of the Mail. +With the others, +.B pick +compares the header field name case insensitive +and the tries to match the field body with the +.IR pattern. .PP -It is used to pick a component which is not one of \*(lqTo:\*(rq, -\*(lqCc:\*(rq, \*(lqDate:\*(rq, \*(lqFrom:\*(rq, or \*(lqSubject:\*(rq. +With +.BR --componend +you can specify the exact header field name you are looking for. +It is used to pick a component which is not one of `To:', +`Cc:', `Date:', `From:', or `Subject:'. An example is -.RB \*(lq "pick\0\-\|\-reply\-to\0pooh" \*(rq. +.RB ` "pick\0\-\|\-reply\-to\0pooh" '. .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. +Pattern matching is performed on a per\-header-field basis. Within the header +of the message, each field is treated as one long line, but in the +body, each line is separate. The +.IR pattern +will match any case. .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. +string must match the text of the `Date:' field of the message. .PP Independent of any pattern matching operations requested, the switches .B \-after @@ -124,9 +123,9 @@ or .B \-before .I date may also be used to introduce date/time -constraints on all of the messages. By default, the \*(lqDate:\*(rq +constraints on all of the messages. By default, the `Date:' field is consulted, but if another date yielding field (such as -\*(lqBB\-Posted:\*(rq or \*(lqDelivery\-Date:\*(rq) should be used, the +`BB\-Posted:' or `Delivery\-Date:') should be used, the .B \-datefield .I field switch may be used. @@ -141,7 +140,7 @@ fields in each of the messages specified in `msgs' and compare them to the date/time specified. If .B \-after is given, then only those -messages whose \*(lqDate:\*(rq field value is chronologically after the +messages whose `Date:' field value is chronologically after the date specified will be considered. The .B \-before switch specifies the @@ -163,18 +162,28 @@ and timezone. 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 +the days of the week (`sunday', `monday', and so on), +and the special dates `today', `yesterday' (24 hours +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 -\*(lqsaturday\*(rq on a \*(lqtuesday\*(rq means \*(lqlast\ saturday\*(rq -not \*(lqthis\ saturday\*(rq). -.PP +`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 -also honor a specification of the form \*(lq\-dd\*(rq, which means -\*(lqdd days ago\*(rq. +also honor a date specification of the form `\-\fIddd\fR', which means +`\fIddd\fR days ago'. +For example, +.PP +.RS 5 +.nf +pick\0\-after\0\-30 +.fi +.RE +.PP +identifies the messages of the last thirty days. .PP .B Pick supports complex boolean operations on the searching primitives @@ -196,7 +205,7 @@ pick\0\-after\0yesterday\0\-and .fi .RE .PP -identifies messages recently sent by \*(lqfrieda\*(rq or \*(lqfear\*(rq. +identifies messages recently sent by `frieda' or `fear'. .PP The matching primitives take precedence over the .B \-not @@ -213,7 +222,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 \*(lqall\*(rq). +command line are selected (this defaults to `a'). .PP Once the search has been performed, if the .B \-list @@ -223,25 +232,25 @@ output separated by newlines. This is .B extremely useful for quickly generating arguments for other -.B nmh +.B mmh programs by using the -\*(lqbackquoting\*(rq syntax of the shell. For example, the command +`backquoting' syntax of the shell. For example, the command .PP .RS 5 -scan\0`pick\0+todo\0\-after\0\*(lq31 Mar 83 0123 PST\*(rq` +show\0`pick\0+todo\0\-after\0`31 Mar 83 0123 PST'` .RE .PP says to -.B scan +.B show 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 +.BR show 's invocation, you need not give the folder argument to -.B scan +.B show as well. .PP The @@ -258,7 +267,7 @@ 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. +`fred' which contains exactly those messages that were selected. .PP By default, .B pick @@ -283,6 +292,137 @@ same way .B mark uses them. +.B Scan +and +.B pick +produces a one\-line\-per\-message listing of the specified and selected +folder or messages. +The default format is for +.B pick +is to print the message number for each message. +The default +.B Scan +line contains the message number +(name), the date, the `From:' field and the `Subject' field. +The following example shows the default output of +.B scan +.PP +.RS 5 +.nf +.ta \w'15+- 'u +\w'07/\|05x 'u +\w'Dcrocker 'u +15+ 10/\|05 crocker nned +16\- 10/\|05 crocker message id format +18 10/\|06 brien Re: Exit status from mkdir +19 10/\|07*brien `scan' listing format in mmh +.fi +.RE +.PP +The `+' on message 15 indicates that it is the current message. +The `\-' on message 16 indicates that it has been replied to, as indicated +by a `Replied:' component (produced by the +.B \-annotate +switch +to the +.B repl +command). +The `*' on message 19 indicates that no `Date:' header was +present. The time of last modification of the message is given instead. +.B Scan +actually reads each of the specified messages and parses them to extract +the desired fields. During parsing, appropriate error messages will be +produced if there are format errors in any of the messages. +.PP +By default, +.B scan +will decode RFC-2047 (MIME) encoding in +these scan listings. +.B Scan +will only decode these fields if your +terminal can natively display the character set used in the encoding. +You should set the MM_CHARSET environment variable to your native +character set, if it is not US-ASCII. See the mh-profile(5) man +page for details about this environment variable. +.PP +The +.B \-file +.I filename +switch allows the user to obtain a +.B scan +listing of a maildrop file as produced by +.BR packf . +This listing +includes every message in the file (you can't scan individual messages). +.PP +The switch +.B \-width +.I columns +may be used to specify the width of +the scan line. The default is to use the width of the terminal. +.PP +The command: +.PP +.RS 5 +(scan | pr ; show a \-showproc pr) | lpr +.RE +.PP +produces a scan listing of the current folder, +followed by a formatted listing of all messages in the folder, one +per page. Omitting +.RB ` "\-showproc\ pr" ' +will cause the messages to be +concatenated, separated by a one\-line header and two blank lines. +.PP +To override the output format used by +.BR scan , +the +.B \-form +.I file +switch is used. This permits individual fields of +the scan listing to be extracted with ease. +.I file +is either the name of a format file or a format string directly, +if prepended with an equal sign `='. +See +.BR mh\-format (5) +for the details. +.PP +In addition to the standard +.BR mh\-format (5) +escapes, +.B scan +also recognizes the following additional +.I component +escapes: +.PP +.RS 5 +.nf +.ta \w'Dtimenow 'u +\w'Returns 'u +.I "Escape Returns Description +dtimenow date the current date +folder string the name of the current folder +.fi +.RE +.PP +If no date header is present in the message, the +.I function +escapes +which operate on +.RB { date } +will return values for the date of last +modification of the message file itself. This feature is handy for +scanning a draft folder, as message drafts usually aren't allowed +to have dates in them. +.PP +.B scan +will update the +.B mmh +context prior to starting the listing, +so interrupting a long +.B scan +listing preserves the new context. +.B nmh +purists hate this idea. + .SH FILES .fc ^ ~ .nf @@ -296,6 +436,7 @@ uses them. .ta 2.4i .ta \w'ExtraBigProfileName 'u ^Path:~^To determine the user's mail storage +^Alternate\-Mailboxes:~^To determine the user's mailboxes ^Current\-Folder:~^To find the default current folder .fi @@ -305,10 +446,11 @@ 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" +.RB ` "\-format pick\.default" "' if the program is called with scan `scan.default' is used .fi .SH CONTEXT @@ -325,7 +467,7 @@ command would or .B refile the selected messages. This was rather -\*(lqinverted logic\*(rq from the UNIX point of view, so +`inverted logic' from the UNIX point of view, so .B pick was changed to define sequences and output those sequences. Hence, .B pick @@ -344,24 +486,48 @@ 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 .PP -Finally, timezones used to be ignored when comparing dates: they aren't +Also, timezones used to be ignored when comparing dates: they aren't any more. - +.PP +In +.B MH +, +.B nmh +and old +.B mmh +versions scan and pick where two different tools. So instand of typing +.PP +.RS 5 +.nf +scan\0\-from\0philipp +.fi +.RE +.PP +you had typed +.PP +.RS 5 +.nf +scan\0`pick\0\-from\0philipp` +.fi +.RE +.PP +With the default config the old style usage is still supported, so +you can write scripts for both mmh and nmh. .SH "HELPFUL HINTS" Use -.RB \*(lq "pick sequence \-list" \*(rq +.RB ` "pick sequence \-list" ' to enumerate the messages in a sequence (such as for use by a shell script). @@ -385,7 +551,7 @@ scan\0`pick\0\-from\0jones` 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., +`jones'), then the shell will still run the outer command (e.g., .BR scan ). Since no messages were matched, .B pick @@ -394,18 +560,29 @@ 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., \*(lqall\*(rq in the case of +used (e.g., `all' 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 +outputs the illegal message number `0' 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 +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.