Added all of the MH sources, including RCS files, in
[mmh] / docs / historical / mh-6.8.5 / conf / doc / RCS / mh-sequence.rf,v
1 head    1.11;
2 access;
3 symbols;
4 locks; strict;
5
6
7 1.11
8 date    92.05.12.22.23.34;      author jromine; state Exp;
9 branches;
10 next    1.10;
11
12 1.10
13 date    92.02.06.22.46.37;      author jromine; state Exp;
14 branches;
15 next    1.9;
16
17 1.9
18 date    91.01.09.11.34.34;      author mh;      state Exp;
19 branches;
20 next    1.8;
21
22 1.8
23 date    91.01.07.16.45.12;      author mh;      state Exp;
24 branches;
25 next    1.7;
26
27 1.7
28 date    91.01.07.16.41.26;      author mh;      state Exp;
29 branches;
30 next    1.6;
31
32 1.6
33 date    91.01.07.16.34.25;      author mh;      state Exp;
34 branches;
35 next    1.5;
36
37 1.5
38 date    91.01.07.16.26.52;      author mh;      state Exp;
39 branches;
40 next    1.4;
41
42 1.4
43 date    91.01.07.16.14.39;      author mh;      state Exp;
44 branches;
45 next    1.3;
46
47 1.3
48 date    90.12.27.14.59.21;      author mh;      state Exp;
49 branches;
50 next    1.2;
51
52 1.2
53 date    90.12.27.14.55.16;      author mh;      state Exp;
54 branches;
55 next    1.1;
56
57 1.1
58 date    90.12.27.12.25.16;      author mh;      state Exp;
59 branches;
60 next    ;
61
62
63 desc
64 @jlr
65 @
66
67
68 1.11
69 log
70 @fixup for nroff problems
71 @
72 text
73 @.\"    @@(MHWARNING)
74 .\" @@(#)$Id: mh-sequence.rf,v 1.10 1992/02/06 22:46:37 jromine Exp jromine $
75 .SC MH-SEQUENCE 5
76 .NA
77 mh-sequence \- sequence specification for MH message system
78 .SY
79 most \fIMH\fR commands
80 .DE
81 Most \fIMH\fP commands accept a `msg' or `msgs' specification, where
82 `msg' indicates one message and `msgs' indicates one or more
83 messages.
84 To designate a message, you may use either its number (e.g., 1, 10, 234)
85 or one of these \*(lqreserved\*(rq message names: 
86 .in +.5i
87 .sp 1
88 .nf
89 .ta +\w'\fIName\fP      'u
90 \fIName\fP      \fIDescription\fR
91 first   the first message in the folder
92 last    the last message in the folder
93 cur     the most recently accessed message
94 prev    the message numerically preceding \*(lqcur\*(rq
95 next    the message numerically following \*(lqcur\*(rq
96 .re
97 .fi
98 .in -.5i
99
100 In commands that take a `msg' argument, the default is \*(lqcur\*(rq.
101 As a shorthand, \*(lq\&.\*(rq is equivalent to \*(lqcur\*(rq.
102
103 For example: In a folder containing five messages numbered 5, 10, 94,
104 177 and 325, \*(lqfirst\*(rq is 5 and \*(lqlast\*(rq is 325.
105 If \*(lqcur\*(rq is 94, then \*(lqprev\*(rq is 10 and \*(lqnext\*(rq
106 is 177.
107
108 The word `msgs' indicates that one or more messages may be specified.
109 Such a specification consists of one message designation or of several message
110 designations separated by spaces.
111 A message designation consists either 
112 of a message name as defined above, or a message range.
113
114 A message range is specified as \*(lqname1\-name2\*(rq
115 or \*(lqname:n\*(rq,
116 where `name', `name1' and `name2' are message names, and `n' is an integer.
117
118 The specification \*(lqname1\-name2\*(rq 
119 designates all currently-existing messages from `name1' to `name2' inclusive.
120 The message name \*(lqall\*(rq is a shorthand for the message
121 range \*(lqfirst\-last\*(rq.
122
123 The specification \*(lqname:n\*(rq designates up to `n' messages.
124 These messages start with `name' if `name' is a message number
125 or one of the reserved names \*(lqfirst\*(rq \*(lqcur\*(rq, or \*(lqnext\*(rq,
126 The messages end with `name' if `name' is \*(lqprev\*(rq or \*(lqlast\*(rq.
127 The interpretation of `n' may be overridden by preceding `n' with 
128 a plus or minus sign; `+n' always means up to `n' messages starting
129 with `name', and `\-n' always means up to `n' messages ending
130 with `name'.
131
132 In commands which accept a `msgs' argument, the default is either
133 \*(lqcur\*(rq or \*(lqall\*(rq, depending on which makes more sense
134 for each command (see the individual man pages for details).
135 Repeated specifications of the same message have the same effect as
136 a single specification of the message.
137
138 .Uh "User\-Defined Message Sequences"
139 In addition to the \*(lqreserved\*(rq (pre-defined) message names given above,
140 \fIMH\fP supports user-defined sequence names.
141 User-defined sequences allow the \fIMH\fR user a tremendous amount of power
142 in dealing with groups of messages in the same folder
143 by allowing the user to bind a group of messages to a meaningful symbolic
144 name.
145
146 The name used to denote a message sequence must consist of
147 an alphabetic character followed by zero or more
148 alphanumeric characters, and can not be one of the \*(lqreserved\*(rq
149 message names above.
150 After defining a sequence,
151 it can be used wherever an \fIMH\fR command expects a `msg' or `msgs'
152 argument.
153
154 Some forms of message ranges are allowed with user-defined
155 sequences.  The 
156 specification \*(lqname:n\*(rq may be used, and it
157 designates up to the first `n' messages (or last `n' messages for `\-n')
158 which are elements of the user-defined sequence `name'.
159
160 The specifications \*(lqname:next\*(rq and \*(lqname:prev\*(rq
161 may also be used, and they designate the
162 next or previous message (relative to the current message)
163 which is an element of the user-defined sequence `name'.
164 The specificaitions 
165 \*(lqname:first\*(rq and \*(lqname:last\*(rq are equivalent
166 to \*(lqname:1\*(rq and \*(lqname:\-1\*(rq, respectively.
167 The specification \*(lqname:cur\*(rq is not allowed
168 (use just \*(lqcur\*(rq instead).
169 The syntax of these message range
170 specifcations is subject to change
171 in the future.
172
173 User-defined sequence names 
174 are specific to each folder.
175 They are defined using the \fIpick\fP and \fImark\fP commands.
176
177 .Uh "Public and Private User-Defined Sequences"
178 There are two varieties of sequences: \fIpublic\fR sequences
179 and \fIprivate\fR sequences.
180 \fIPublic\fR sequences of a folder are accessible to any \fIMH\fR user that
181 can read that folder and are kept in the \&.mh\(rusequences file in the folder.
182 \fIPrivate\fR sequences are accessible only to the \fIMH\fR user that defined
183 those sequences and are kept in the user's \fIMH\fR context file.
184 By default,
185 \fIpick\fR and \fImark\fR create \fIpublic\fR sequences
186 if the folder for which the sequences are being defined is writable by the
187 \fIMH\fR user.
188 Otherwise, \fIprivate\fR sequences are created.
189 This can be overridden with the `\-public' and `\-private' switches
190 to \fImark\fP.
191
192 .Uh "Sequence Negation"
193 \fIMH\fP provides the ability to select all messages
194 not elements of a user-defined sequence.  To do this,
195 the user should define the entry
196 \*(lqSequence\-Negation\*(rq in the \fIMH\fR profile file;
197 its value may be any string.
198 This string is then used to preface an existing user-defined
199 sequence name.  This specification then refers to those messages
200 not elements of the specified sequence name.
201 For example, if the profile entry is:
202
203 .ti +.5i
204 Sequence\-Negation:\^ not
205
206 then anytime an \fIMH\fR command is given \*(lqnotfoo\*(rq as a `msg' or
207 `msgs' argument,
208 it would substitute all messages that are not elements of the sequence
209 \*(lqfoo\*(rq.
210
211 Obviously,
212 the user should beware of defining sequences with names that
213 begin with the value of the
214 \*(lqSequence\-Negation\*(rq profile entry.
215
216 .Uh "The Previous Sequence"
217 \fIMH\fR provides the ability
218 to remember the `msgs' or
219 `msg' argument last given to an \fIMH\fR command.
220 The entry \*(lqPrevious\-Sequence\*(rq should be defined in the
221 \fIMH\fR profile; its value should be a sequence name or multiple
222 sequence names separated by spaces.
223 If this entry is defined, when
224 when an \fIMH\fP command finishes,
225 it will define the sequence(s) named in the value of this entry to be
226 those messages that were specified to the command.
227 Hence, a profile entry of
228
229 .ti +.5i
230 Previous\-Sequence:\^ pseq
231
232 directs any \fIMH\fR command that accepts a `msg' or `msgs' argument to
233 define the sequence \*(lqpseq\*(rq as those messages when it finishes.
234
235 \fBNote:\fP there can be a performance penalty in using the  
236 \*(lqPrevious\-Sequence\*(rq facility.
237 If it is used,
238 \fBall\fP \fIMH\fR programs have to write the sequence information 
239 to the \&.mh\(rusequences file for
240 the folder each time they run.
241 If the \*(lqPrevious\-Sequence\*(rq profile entry is not included,
242 only \fIpick\fR and \fImark\fR will write to the \&.mh\(rusequences file.
243
244 .Uh "The Unseen Sequence"
245 Finally, some users like to indicate messages which have not been
246 previously seen by them.
247 Both \fIinc\fR and \fIshow\fR honor the profile entry
248 \*(lqUnseen\-Sequence\*(rq to support this activity.
249 This entry in the \&.mh\(ruprofile should be defined
250 as one or more sequence names separated by spaces.
251 If there is a value for \*(lqUnseen\-Sequence\*(rq in the profile,
252 then whenever \fIinc\fR places new messages in a folder,
253 the new messages will also be added to the sequence(s) named
254 in the value of this entry.
255 Hence, a profile entry of
256
257 .ti +.5i
258 Unseen\-Sequence:\^ unseen
259
260 directs \fIinc\fR to add new messages to the sequence \*(lqunseen\*(rq.
261 Unlike the behavior of the \*(lqPrevious\-Sequence\*(rq entry in the profile,
262 however, the sequence(s) will \fBnot\fR be zeroed by \fIinc\fP.
263
264 Similarly,
265 whenever \fIshow\fR (or \fInext\fR or \fIprev\fR\^) displays a message,
266 that message will be removed
267 from any sequences named by the
268 \*(lqUnseen\-Sequence\*(rq entry in the profile.
269
270 .Fi
271 ^$HOME/\&.mh\(ruprofile~^The user profile
272 ^<mh\-dir>/context~^The user context
273 ^<folder>/\&.mh\(rusequences~^Public sequences for <folder>
274 .Pr
275 ^Sequence\-Negation:~^To designate messages not in a sequence
276 .Ps
277 ^Previous\-Sequence:~^The last message specification given
278 .Ps
279 ^Unseen\-Sequence:~^Those messages not yet seen by the user
280 .Sa
281 mh(1), mark(1), pick(1), mh-profile(5)
282 .De
283 None
284 .Co
285 All
286 .Bu
287 User-defined sequences are stored in the \&.mh\(rusequences file 
288 as a series of message specifications separated by spaces.
289 If a user-defined sequence contains too many individual
290 message specifications,
291 that line in the file may become too long for \fIMH\fP to handle.
292 This will generate the error message \*(lq\&.mh\(rusequences is
293 poorly formatted\*(rq.  You'll have to edit the file by hand to
294 remove the offending line. 
295
296 This can happen to users who define the \*(lqPrevious\-Sequence\*(rq entry in
297 the \fIMH\fP profile
298 and have a folder containing many messages with gaps in the numbering.
299 A workaround for large folders is to minimize numbering gaps by using
300 \*(lqfolder\ \-pack\*(rq often.
301 .En
302 @
303
304
305 1.10
306 log
307 @minor note
308 @
309 text
310 @d2 2
311 a3 2
312 .\" @@(#)$Id: mh-sequence.rf,v 1.9 1991/01/09 11:34:34 mh Exp jromine $
313 .SC MH\-SEQUENCE 5
314 d5 1
315 a5 1
316 mh\-sequence \- sequence specification for MH message system
317 @
318
319
320 1.9
321 log
322 @document name:{first,last,next,prev}
323 jlr
324 @
325 text
326 @d2 1
327 a2 1
328 .\" @@(#)$Id: mh-sequence.rf,v 1.8 91/01/07 16:45:12 mh Exp Locker: mh $
329 d61 2
330 a62 1
331 \*(lqcur\*(rq or \*(lqall\*(rq, depending on which makes more sense.
332 @
333
334
335 1.8
336 log
337 @jlr
338 @
339 text
340 @d2 1
341 a2 1
342 .\" @@(#)$Id: mh-sequence.rf,v 1.7 91/01/07 16:41:26 mh Exp Locker: mh $
343 d81 2
344 a82 2
345 A restricted form of message ranges are allowed with user\-defined
346 sequences.  Only the 
347 d87 14
348 a100 1
349 These user-defined sequence names 
350 @
351
352
353 1.7
354 log
355 @fix
356 jlr
357 @
358 text
359 @d2 1
360 a2 1
361 .\" @@(#)$Id: mh-sequence.rf,v 1.6 91/01/07 16:34:25 mh Exp Locker: mh $
362 d66 1
363 a66 1
364 In addition to the \(*lqreserved\(*rq (pre-defined) message names given above,
365 @
366
367
368 1.6
369 log
370 @fixup
371 jlr
372 @
373 text
374 @d2 1
375 a2 1
376 .\" @@(#)$Id: mh-sequence.rf,v 1.5 91/01/07 16:26:52 mh Exp Locker: mh $
377 a183 15
378 .Bu
379 User-defined sequences are stored in the \&.mh\(rusequences file 
380 as a series of message specifications separated by spaces.
381 If a user-defined sequence contains too many individual
382 message specifications,
383 that line in the file may become too long for \fIMH\fP to handle.
384 This will generate the error message \*(lq\&.mh\(rusequences is
385 poorly formatted\*(rq.  You'll have to edit the file by hand to
386 remove the offending line. 
387
388 This can happen to users who define the \*(lqPrevious\-Sequence\*(rq entry in
389 the \fIMH\fP profile
390 and have a folder containing many messages with gaps in the numbering.
391 A workaround for large folders is to minimize numbering gaps by using
392 \*(lqfolder\ \-pack\*(rq often.
393 d200 15
394 @
395
396
397 1.5
398 log
399 @change from Jerry Peek
400 @
401 text
402 @d1 4
403 a4 7
404 .\"     This file is automatically generated.  Do not edit!
405 .\" include the -mh macro file
406 .so /usr/local/lib/mh/tmac.h
407 .\"     This file is automatically generated.  Do not edit!
408 .\" @@(#)$Id: mh-sequence.rf,v 1.3 90/12/27 14:59:21 mh Exp $
409 .TH MH\-SEQUENCE 5 MH.6.7 [mh.6]
410 .SH NAME
411 d6 1
412 a6 3
413 .SH SYNOPSIS
414 .in +.5i
415 .ti -.5i
416 d8 1
417 a8 2
418 .in -.5i
419 .SH DESCRIPTION
420 @
421
422
423 1.4
424 log
425 @use Uh macro
426 @
427 text
428 @d1 7
429 a7 4
430 .\"     @@(MHWARNING)
431 .\" @@(#)$Id: mh-sequence.rf,v 1.3 90/12/27 14:59:21 mh Exp Locker: mh $
432 .SC MH\-SEQUENCE 5
433 .NA
434 d9 3
435 a11 1
436 .SY
437 d13 2
438 a14 1
439 .DE
440 d16 1
441 a16 1
442 `msg' indicates one message, and `msgs' indicates one or more
443 d18 1
444 a18 1
445 To designate a message, you may use either its number (e.g., 1, 10, 234),
446 d28 1
447 a28 1
448 prev    the message numerically preceding \*(lqcur\*(rq
449 d37 5
450 d43 2
451 a44 2
452 Such a specification consists of several message designations separated
453 by spaces.
454 d49 2
455 a50 2
456 or \*(lqname1:n\*(rq,
457 where `name1' and `name2' are message names, and `n' is an integer.
458 d53 1
459 a53 1
460 designates all the messages from `name1' to `name2' inclusive.
461 d57 2
462 a58 2
463 The specification \*(lqname1:n\*(rq designates up to `n' messages,
464 starting with `name1' if `name1' is a message number
465 d60 1
466 a60 1
467 and ending with `name1' if `name1' is \*(lqprev\*(rq, or \*(lqlast\*(rq.
468 d63 2
469 a64 2
470 with `name1', and `\-n' always means up to `n' messages ending
471 with `name1'.
472 d72 2
473 a73 2
474 In addition to the pre-defined message names given above,
475 \fIMH\fP supports user-defined sequences names.
476 d94 2
477 a95 2
478 are specific to each folder, and are
479 defined using the \fIpick\fP and \fImark\fP commands.
480 d98 1
481 a98 1
482 There are two varieties of sequences: \fIpublic\fR sequences,
483 d105 1
484 a105 1
485 \fIpick\fR (and \fImark\fR\^) create \fIpublic\fR sequences
486 d116 1
487 a116 1
488 \*(lqSequence\-Negation\*(rq in the \&.mh\(ruprofile;
489 d141 1
490 a141 1
491 \&.mh\(ruprofile; its value should be a sequence name, or multiple
492 d155 1
493 a155 1
494 \fBNote:\fP there is a performance penalty in using the  
495 d158 2
496 a159 1
497 \fBall\fP \fIMH\fR programs have to update the sequence information for
498 d161 2
499 a162 2
500 Although most programs read this information,
501 usually only \fIpick\fR and \fImark\fR have to write this information out.
502 d190 15
503 @
504
505
506 1.3
507 log
508 @jlr
509 @
510 text
511 @d2 1
512 a2 1
513 .\" @@(#)$Id: mh-sequence.rf,v 1.2 90/12/27 14:55:16 mh Exp Locker: mh $
514 a8 3
515 .de UH
516 .SS "\\$1"
517 ..
518 d60 1
519 a60 1
520 .UH "User\-Defined Message Sequences"
521 d86 1
522 a86 1
523 .UH "Public and Private User-Defined Sequences"
524 d101 1
525 a101 1
526 .UH "Sequence Negation"
527 d125 1
528 a125 1
529 .UH "The Previous Sequence"
530 d152 1
531 a152 1
532 .UH "The Unseen Sequence"
533 @
534
535
536 1.2
537 log
538 @jlr
539 @
540 text
541 @d2 1
542 a2 1
543 .\" @@(#)$Id: mh-sequence.rf,v 1.1 90/12/27 12:25:16 mh Exp $
544 d83 1
545 a83 1
546 which are part of the user-defined sequence `name'.
547 d97 1
548 a97 1
549 \fIpick\fR (and \fImark\fR\|) create \fIpublic\fR sequences
550 d116 1
551 a116 1
552 Sequence\-Negation:\| not
553 d142 1
554 a142 1
555 Previous\-Sequence:\| pseq
556 d169 1
557 a169 1
558 Unseen\-Sequence:\| unseen
559 d176 1
560 a176 1
561 whenever \fIshow\fR (or \fInext\fR or \fIprev\fR\|) displays a message,
562 d192 1
563 a192 1
564 mark(1), pick(1), mh-profile(5)
565 @
566
567
568 1.1
569 log
570 @Initial revision
571 @
572 text
573 @d2 1
574 a2 1
575 .\" @@(#)$Id: mh-profile.rf,v 1.8 90/12/18 12:49:13 mh Exp $
576 d7 1
577 a7 1
578 any \fIMH\fR commands
579 d12 2
580 a13 3
581 Most \fIMH\fP commands accept a `msg' or `msgs' argument.
582 The word
583 `msg' refers to one message, and `msgs' refers to one or more
584 d15 2
585 a16 5
586 This describes how messages are specified to \fIMH\fP commands.
587
588 .ne 10
589 A message name may be a number (e.g., 1, 10, 234) or one of
590 the \*(lqreserved\*(rq message names: 
591 d20 1
592 a20 1
593 .ta +\w'first   'u
594 d25 1
595 a25 1
596 prev    the message numerically preceeding \*(lqcur\*(rq
597 a26 1
598 \&.     a shorthand for \*(lqcur\*(rq
599 d32 1
600 d40 3
601 a42 4
602 A message range is specified as \*(lqname1\-name2\*(rq, where
603 `name1' and `name2' are message names, or
604 as \*(lqname1:n\*(rq, where `name1'
605 is a message name and `n' is an integer.
606 d44 2
607 a45 2
608 The specification \*(lqname1\-name2\*(rq desginates up to
609 This designates all the messages from `name1' to `name2' inclusive.
610 d49 1
611 a49 1
612 The specification \*(lqname1:n\*(rq desginates up to `n' messages,
613 d53 1
614 a53 1
615 The interpretation of `n' may be overridden by preceeding `n' with 
616 d60 2
617 d97 1
618 a97 1
619 \fIpick\fR (and \fImark\fR\0) create \fIpublic\fR sequences
620 d105 9
621 a113 4
622 The \fIMH\fP user may desire to specify all messages not
623 present in a user-defined sequence.
624 This capability is realized through the entry 
625 \*(lqSequence\-Negation:\*(rq in the \&.mh\(ruprofile.
626 a114 7
627 The \*(lqSequence\-Negation:\*(rq profile entry may consist of
628 any string.  If it is defined,
629 it may be used to preface an existing user-defined
630 sequence name.  This designation then refers to those messages
631 not present in the specified sequence name.
632 For example, if the entry is:
633
634 d116 1
635 a116 1
636 Sequence\-Negation:\0not
637 d124 1
638 a124 1
639 the user should beware of defining new sequences whose names
640 d126 1
641 a126 1
642 \*(lqSequence\-Negation:\*(rq profile entry.
643 d132 7
644 a138 5
645 If the entry \*(lqPrevious\-Sequence:\*(rq is defined in the
646 \&.mh\(ruprofile,
647 then when the command finishes,
648 it will define the sequence(s) named in the value of this entry as being
649 exactly those messages that were specified.
650 d142 1
651 a142 1
652 Previous\-Sequence:\0pseq
653 a145 2
654 More than one sequence name may be placed in this entry,
655 separated with spaces.
656 d147 5
657 a151 5
658 There is a performance penalty in using the  
659 \*(lqPrevious\-Sequence:\*(rq entry.
660 It
661 is that all \fIMH\fR progams have to update the sequence information for
662 the folder each time they run
663 d154 1
664 d156 1
665 a156 1
666 Finally, some users like to distinguish between messages which have been
667 d160 6
668 a165 5
669 Whenever \fIinc\fR places new messages in a folder,
670 if the entry \*(lqUnseen\-Sequence:\*(rq is defined in the \&.mh\(ruprofile,
671 then when the command finishes,
672 \fIinc\fR will add the new messages to the sequence(s) named in the value of
673 this entry.
674 d169 1
675 a169 1
676 Unseen\-Sequence:\0 unseen
677 d172 2
678 a173 3
679 Unlike the behavior of the \*(lqPrevious\-Sequence\*(rq entry in the profile
680 however,
681 the sequence(s) will \fBnot\fR be zero'd.
682 d176 3
683 a178 2
684 whenever \fIshow\fR (or \fInext\fR or \fIprev\fR\0) displays a message,
685 they remove those messages from any sequences named by the
686 @