Mercurial > hg > Applications > mh
comparison doc/pick.me @ 0:bce86c4163a3
Initial revision
author | kono |
---|---|
date | Mon, 18 Apr 2005 23:46:02 +0900 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:bce86c4163a3 |
---|---|
1 .\" This file is automatically generated. Do not edit! | |
2 .\" @(#)$Id$ | |
3 .SC PICK 1 | |
4 .NA | |
5 pick \- select messages by content | |
6 .SY | |
7 .ie t \{\ | |
8 .ta .4i 1.8i | |
9 .nf | |
10 .in .5i | |
11 ^pick~^^\0\-cc~^ \%[+folder] \%[msgs] \%[\-help] | |
12 ^^^\0\-date~^ \%[\-before\ date] \%[\-after\ date] \%[\-datefield\ field] | |
13 ^^^\0\-from~^ | |
14 ^^^\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] | |
15 ^^^\0\-subject~^ | |
16 ^^^\0\-to~^ \%[\-sequence\ name\ ...] \%[\-public] \%[\-nopublic] \%[\-zero] \%[\-nozero] | |
17 ^^^\0\-\|\-component~^ \%[\-list] \%[\-nolist] | |
18 .fi | |
19 .re | |
20 .in 1i | |
21 .\} | |
22 .el \{\ | |
23 .ti .5i | |
24 pick | |
25 \%[+folder] \%[msgs] | |
26 \%[\-and\ ...] \%[\-or\ ...] \%[\-not\ ...] \%[\-lbrace\ ...\ \-rbrace] | |
27 \%[\-\|\-component\ pattern] | |
28 \%[\-cc\ pattern] | |
29 \%[\-date\ pattern] | |
30 \%[\-from\ pattern] | |
31 \%[\-search\ pattern] | |
32 \%[\-subject\ pattern] | |
33 \%[\-to\ pattern] | |
34 \%[\-after\ date] \%[\-before\ date] \%[\-datefield\ field] | |
35 \%[\-sequence\ name\ ...] | |
36 \%[\-public] \%[\-nopublic] | |
37 \%[\-zero] \%[\-nozero] | |
38 \%[\-list] \%[\-nolist] | |
39 \%[\-help] | |
40 .\} | |
41 | |
42 .ti .5i | |
43 typically: | |
44 .br | |
45 scan\0`pick\0\-from\0jones` | |
46 .br | |
47 pick\0\-to\0holloway\0\-sequence\0select | |
48 .br | |
49 show\0`pick\0\-before\0friday` | |
50 .DE | |
51 \fIPick\fR searches messages within a folder for the specified | |
52 contents, and then identifies those messages. | |
53 Two types of search primitives are available: | |
54 pattern matching and date constraint operations. | |
55 | |
56 A modified \fIgrep\fR(1) is used to perform the matching, so the | |
57 full regular expression (see \fIed\fR(1)) facility is available | |
58 within `pattern'. | |
59 With `\-search', `pattern' is used directly, | |
60 and with the others, the grep pattern constructed is: | |
61 | |
62 .ti +.5i | |
63 \*(lqcomponent[ \\t]*:\&.*pattern\*(rq | |
64 | |
65 This means that the pattern specified for a `\-search' will be | |
66 found everywhere in the message, including the header and the body, | |
67 while the other pattern matching requests are limited to the single | |
68 specified component. | |
69 The expression | |
70 | |
71 .ti +.5i | |
72 `\-\|\-component\ pattern' | |
73 | |
74 is a shorthand for specifying | |
75 | |
76 .ti +.5i | |
77 `\-search \*(lqcomponent[ \\t]*:\&.*pattern\*(rq\ ' | |
78 | |
79 It is used to pick a component which is not one of | |
80 \*(lqTo:\*(rq, \*(lqcc:\*(rq, \*(lqDate:\*(rq, \*(lqFrom:\*(rq, | |
81 or \*(lqSubject:\*(rq. | |
82 An example is `pick\0\-\|\-reply\-to\0pooh'. | |
83 | |
84 Pattern matching is performed on a per\-line basis. | |
85 Within the header of | |
86 the message, each component is treated as one long line, but in | |
87 the body, each line is separate. | |
88 Lower\-case letters in the | |
89 search pattern will match either lower or upper case in the | |
90 message, while upper case will match only upper case. | |
91 | |
92 Note that since the `\-date' switch is a pattern matching operation (as | |
93 described above), | |
94 to find messages sent on a certain date | |
95 the pattern string must match the text of the | |
96 \*(lqDate:\*(rq field of the message. | |
97 | |
98 Independent of any pattern matching operations requested, | |
99 the switches `\-after date' or `\-before date' may also be used | |
100 to introduce date/time contraints on all of the messages. | |
101 By default, the \*(lqDate:\*(rq field is consulted, | |
102 but if another date yielding field | |
103 (such as \*(lqBB\-Posted:\*(rq or \*(lqDelivery\-Date:\*(rq) should be used, | |
104 the `\-datefield\ field' switch may be used. | |
105 | |
106 With `\-before' and `\-after', | |
107 \fIpick\fR will actually parse the date fields in each of the messages | |
108 specified in `msgs' | |
109 and compare them to the date/time specified. | |
110 If `\-after' is given, | |
111 then only those messages whose \*(lqDate:\*(rq field value | |
112 is chronologically after | |
113 the date specified will be considered. | |
114 The `\-before' switch specifies the complimentary action. | |
115 | |
116 Both the `\-after' and `\-before' switches take legal 822\-style date | |
117 specifications as arguments. | |
118 \fIPick\fR will default certain missing fields so that the entire date | |
119 need not be specified. | |
120 These fields are (in order of defaulting): | |
121 timezone, time and timezone, date, date and timezone. | |
122 All defaults are taken from the current date, time, and timezone. | |
123 | |
124 In addition to 822\-style dates, | |
125 \fIpick\fR will also recognize any of the days of the week | |
126 (\*(lqsunday\*(rq, \*(lqmonday\*(rq, and so on), | |
127 and the special dates | |
128 \*(lqtoday\*(rq, \*(lqyesterday\*(rq (24 hours ago), | |
129 and \*(lqtomorrow\*(rq (24 hours from now). | |
130 All days of the week are judged to refer to a day in the past | |
131 (e.g., telling \fIpick\fR \*(lqsaturday\*(rq on | |
132 a \*(lqtuesday\*(rq means \*(lqlast\ saturday\*(rq | |
133 not \*(lqthis\ saturday\*(rq). | |
134 | |
135 Finally, in addition to these special specifications, | |
136 \fIpick\fR will also honor a specification of the form \*(lq\-dd\*(rq, | |
137 which means \*(lqdd days ago\*(rq. | |
138 | |
139 \fIPick\fR supports complex boolean operations on the searching primitives | |
140 with the `\-and', `\-or', `\-not', and `\-lbrace\ ...\ \-rbrace' switches. | |
141 For example, | |
142 | |
143 .ti +.5i | |
144 .ie t \{\ | |
145 pick\0\-after\0yesterday\0\-and\0\-lbrace\0\-from\0freida\0\-or\0\-from\0fear\0\-rbrace | |
146 .\} | |
147 .el \{\ | |
148 pick\0\-after\0yesterday\0\-and | |
149 .br | |
150 .ti +1i | |
151 \-lbrace\0\-from\0freida\0\-or\0\-from\0fear\0\-rbrace | |
152 .\} | |
153 | |
154 identifies messages recently sent by \*(lqfrieda\*(rq or \*(lqfear\*(rq. | |
155 | |
156 The matching primitives take precedence over the `\-not' switch, | |
157 which in turn takes precedence over `\-and' | |
158 which in turn takes precedence over `\-or'. | |
159 To override the default precedence, | |
160 the `\-lbrace' and `\-rbrace' switches are provided, | |
161 which act just like opening and closing parentheses in logical expressions. | |
162 | |
163 If no search criteria are given, all the messages | |
164 specified on the command | |
165 line are selected (this defaults to \*(lqall\*(rq). | |
166 | |
167 Once the search has been performed, | |
168 if the `\-list' switch is given, | |
169 the message numbers of the selected messages are written to the standard | |
170 output separated by newlines. | |
171 This is \fIextremely\fR useful for quickly generating arguments for other | |
172 \fIMH\fR programs by using the \*(lqbackquoting\*(rq syntax of the shell. | |
173 For example, | |
174 the command | |
175 | |
176 .ti +.5i | |
177 scan\0`pick\0+todo\0\-after\0\*(lq31 Mar 83 0123 PST\*(rq` | |
178 | |
179 says to \fIscan\fR those messages in the indicated folder which meet the | |
180 appropriate criterion. | |
181 Note that since \fIpick\fR\0's context changes are written out prior to | |
182 \fIscan\fR\0's invocation, | |
183 you need not give the folder argument to \fIscan\fR as well. | |
184 | |
185 Regardless of the operation of the `\-list' switch, | |
186 the `\-sequence name' switch may be given once for each sequence the user | |
187 wishes to define. | |
188 For each sequence named, | |
189 that sequence will be defined to mean exactly those messages selected by | |
190 \fIpick\fR. | |
191 For example, | |
192 | |
193 .ti +.5i | |
194 pick\0\-from\0frated\0\-seq\0fred | |
195 | |
196 defines a new message sequence for the current folder called \*(lqfred\*(rq | |
197 which contains exactly those messages that were selected. | |
198 | |
199 Note that whenever \fIpick\fR processes a `\-sequence\ name' switch, | |
200 it sets `\-nolist'. | |
201 | |
202 By default, \fIpick\fR will zero the sequence before adding it. | |
203 This action can be disabled with the `\-nozero' switch, | |
204 which means that the messages selected by \fIpick\fR will be added to the | |
205 sequence, if it already exists, and any messages already a part of that | |
206 sequence will remain so. | |
207 | |
208 The `\-public' and `\-nopublic' switches are used by \fIpick\fR in the same | |
209 way \fImark\fR uses them. | |
210 .Fi | |
211 ^$HOME/\&.mh\(ruprofile~^The user profile | |
212 .Pr | |
213 ^Path:~^To determine the user's MH directory | |
214 .Ps | |
215 ^Current\-Folder:~^To find the default current folder | |
216 .Sa | |
217 mark(1) | |
218 .De | |
219 `+folder' defaults to the current folder | |
220 .Ds | |
221 `msgs' defaults to all | |
222 .Ds | |
223 `\-datefield date' | |
224 .Ds | |
225 `\-nopublic' if the folder is read\-only, `\-public' otherwise | |
226 .Ds | |
227 `\-zero' | |
228 .Ds | |
229 `\-list' is the default if no `\-sequence', `\-nolist' otherwise | |
230 .Co | |
231 If a folder is given, it will become the current folder. | |
232 .Hi | |
233 In previous versions of \fIMH\fR, | |
234 the \fIpick\fR command would \fIshow\fR, \fIscan\fR, or \fIrefile\fR the | |
235 selected messages. | |
236 This was rather \*(lqinverted logic\*(rq from the UNIX point of view, | |
237 so \fIpick\fR was changed to define sequences and output those sequences. | |
238 Hence, \fIpick\fR can be used to generate the arguments for all other | |
239 \fIMH\fR commands, | |
240 instead of giving \fIpick\fR endless switches for invoking those commands | |
241 itself. | |
242 | |
243 Also, previous versions of \fIpick\fR balked if you didn't specify a search | |
244 string or a date/time constraint. | |
245 The current version does not, and merely matches the messages you specify. | |
246 This lets you type something like: | |
247 | |
248 .ti +.5i | |
249 show\0`pick\0last:20\0\-seq\0fear` | |
250 | |
251 instead of typing | |
252 | |
253 .in +.5i | |
254 .nf | |
255 mark\0\-add\0\-nozero\0\-seq\0fear\0last:20 | |
256 show\0fear | |
257 .fi | |
258 .in -.5i | |
259 | |
260 Finally, | |
261 timezones used to be ignored when comparing dates: | |
262 they aren't any more. | |
263 .Hh | |
264 Use \*(lqpick sequence \-list\*(rq | |
265 to enumerate the messages in a sequence (such as for use | |
266 by a shell script). | |
267 .Bu | |
268 The argument to the `\-after' and `\-before' switches must be interpreted | |
269 as a single token by the shell that invokes \fIpick\fR. | |
270 Therefore, | |
271 one must usually place the argument to this switch inside double\-quotes. | |
272 Furthermore, | |
273 any occurance of `\-datefield' must occur prior to the `\-after' | |
274 or `\-before' switch it applies to. | |
275 | |
276 If \fIpick\fR is used in a back\-quoted operation, | |
277 such as | |
278 | |
279 .ti +.5i | |
280 scan\0`pick\0\-from\0jones` | |
281 | |
282 and \fIpick\fR selects no messages | |
283 (e.g., no messages are from \*(lqjones\*(rq), | |
284 then the shell will still run the outer command (e.g., \*(lqscan\*(rq). | |
285 Since no messages were matched, | |
286 \fIpick\fR produced no output, | |
287 and the argument given to the outer command as a result of backquoting | |
288 \fIpick\fR is empty. | |
289 In the case of \fIMH\fR programs, | |
290 the outer command now acts as if the default `msg' or `msgs' should be used | |
291 (e.g., \*(lqall\*(rq in the case of \fIscan\fR\0). | |
292 To prevent this unexpected behavior, | |
293 if `\-list' was given, | |
294 and if its standard output is not a tty, | |
295 then \fIpick\fR outputs the illegal message number \*(lq0\*(rq when it fails. | |
296 This lets the outer command fail gracefully as well. | |
297 .sp | |
298 The pattern syntax \*(lq[l-r]\*(rq is not supported; each letter | |
299 to be matched must be included within the square brackets. | |
300 .En |