Mercurial > hg > Applications > mh

comparison doc/mh-sequence.me @ 0:bce86c4163a3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 MH-SEQUENCE 5
4 .NA
5 mh-sequence \- sequence specification for MH message system
6 .SY
7 most \fIMH\fR commands
8 .DE
9 Most \fIMH\fP commands accept a `msg' or `msgs' specification, where
10 `msg' indicates one message and `msgs' indicates one or more
11 messages.
12 To designate a message, you may use either its number (e.g., 1, 10, 234)
13 or one of these \*(lqreserved\*(rq message names:
14 .in +.5i
15 .sp 1
16 .nf
17 .ta +\w'\fIName\fP 'u
18 \fIName\fP \fIDescription\fR
19 first the first message in the folder
20 last the last message in the folder
21 cur the most recently accessed message
22 prev the message numerically preceding \*(lqcur\*(rq
23 next the message numerically following \*(lqcur\*(rq
24 .re
25 .fi
26 .in -.5i
27
28 In commands that take a `msg' argument, the default is \*(lqcur\*(rq.
29 As a shorthand, \*(lq\&.\*(rq is equivalent to \*(lqcur\*(rq.
30
31 For example: In a folder containing five messages numbered 5, 10, 94,
32 177 and 325, \*(lqfirst\*(rq is 5 and \*(lqlast\*(rq is 325.
33 If \*(lqcur\*(rq is 94, then \*(lqprev\*(rq is 10 and \*(lqnext\*(rq
34 is 177.
35
36 The word `msgs' indicates that one or more messages may be specified.
37 Such a specification consists of one message designation or of several message
38 designations separated by spaces.
39 A message designation consists either
40 of a message name as defined above, or a message range.
41
42 A message range is specified as \*(lqname1\-name2\*(rq
43 or \*(lqname:n\*(rq,
44 where `name', `name1' and `name2' are message names, and `n' is an integer.
45
46 The specification \*(lqname1\-name2\*(rq
47 designates all currently-existing messages from `name1' to `name2' inclusive.
48 The message name \*(lqall\*(rq is a shorthand for the message
49 range \*(lqfirst\-last\*(rq.
50
51 The specification \*(lqname:n\*(rq designates up to `n' messages.
52 These messages start with `name' if `name' is a message number
53 or one of the reserved names \*(lqfirst\*(rq \*(lqcur\*(rq, or \*(lqnext\*(rq,
54 The messages end with `name' if `name' is \*(lqprev\*(rq or \*(lqlast\*(rq.
55 The interpretation of `n' may be overridden by preceding `n' with
56 a plus or minus sign; `+n' always means up to `n' messages starting
57 with `name', and `\-n' always means up to `n' messages ending
58 with `name'.
59
60 In commands which accept a `msgs' argument, the default is either
61 \*(lqcur\*(rq or \*(lqall\*(rq, depending on which makes more sense
62 for each command (see the individual man pages for details).
63 Repeated specifications of the same message have the same effect as
64 a single specification of the message.
65
66 .Uh "User\-Defined Message Sequences"
67 In addition to the \*(lqreserved\*(rq (pre-defined) message names given above,
68 \fIMH\fP supports user-defined sequence names.
69 User-defined sequences allow the \fIMH\fR user a tremendous amount of power
70 in dealing with groups of messages in the same folder
71 by allowing the user to bind a group of messages to a meaningful symbolic
72 name.
73
74 The name used to denote a message sequence must consist of
75 an alphabetic character followed by zero or more
76 alphanumeric characters, and can not be one of the \*(lqreserved\*(rq
77 message names above.
78 After defining a sequence,
79 it can be used wherever an \fIMH\fR command expects a `msg' or `msgs'
80 argument.
81
82 Some forms of message ranges are allowed with user-defined
83 sequences. The
84 specification \*(lqname:n\*(rq may be used, and it
85 designates up to the first `n' messages (or last `n' messages for `\-n')
86 which are elements of the user-defined sequence `name'.
87
88 The specifications \*(lqname:next\*(rq and \*(lqname:prev\*(rq
89 may also be used, and they designate the
90 next or previous message (relative to the current message)
91 which is an element of the user-defined sequence `name'.
92 The specificaitions
93 \*(lqname:first\*(rq and \*(lqname:last\*(rq are equivalent
94 to \*(lqname:1\*(rq and \*(lqname:\-1\*(rq, respectively.
95 The specification \*(lqname:cur\*(rq is not allowed
96 (use just \*(lqcur\*(rq instead).
97 The syntax of these message range
98 specifcations is subject to change
99 in the future.
100
101 User-defined sequence names
102 are specific to each folder.
103 They are defined using the \fIpick\fP and \fImark\fP commands.
104
105 .Uh "Public and Private User-Defined Sequences"
106 There are two varieties of sequences: \fIpublic\fR sequences
107 and \fIprivate\fR sequences.
108 \fIPublic\fR sequences of a folder are accessible to any \fIMH\fR user that
109 can read that folder and are kept in the \&.mh\(rusequences file in the folder.
110 \fIPrivate\fR sequences are accessible only to the \fIMH\fR user that defined
111 those sequences and are kept in the user's \fIMH\fR context file.
112 By default,
113 \fIpick\fR and \fImark\fR create \fIpublic\fR sequences
114 if the folder for which the sequences are being defined is writable by the
115 \fIMH\fR user.
116 Otherwise, \fIprivate\fR sequences are created.
117 This can be overridden with the `\-public' and `\-private' switches
118 to \fImark\fP.
119
120 .Uh "Sequence Negation"
121 \fIMH\fP provides the ability to select all messages
122 not elements of a user-defined sequence. To do this,
123 the user should define the entry
124 \*(lqSequence\-Negation\*(rq in the \fIMH\fR profile file;
125 its value may be any string.
126 This string is then used to preface an existing user-defined
127 sequence name. This specification then refers to those messages
128 not elements of the specified sequence name.
129 For example, if the profile entry is:
130
131 .ti +.5i
132 Sequence\-Negation:\^ not
133
134 then anytime an \fIMH\fR command is given \*(lqnotfoo\*(rq as a `msg' or
135 `msgs' argument,
136 it would substitute all messages that are not elements of the sequence
137 \*(lqfoo\*(rq.
138
139 Obviously,
140 the user should beware of defining sequences with names that
141 begin with the value of the
142 \*(lqSequence\-Negation\*(rq profile entry.
143
144 .Uh "The Previous Sequence"
145 \fIMH\fR provides the ability
146 to remember the `msgs' or
147 `msg' argument last given to an \fIMH\fR command.
148 The entry \*(lqPrevious\-Sequence\*(rq should be defined in the
149 \fIMH\fR profile; its value should be a sequence name or multiple
150 sequence names separated by spaces.
151 If this entry is defined, when
152 when an \fIMH\fP command finishes,
153 it will define the sequence(s) named in the value of this entry to be
154 those messages that were specified to the command.
155 Hence, a profile entry of
156
157 .ti +.5i
158 Previous\-Sequence:\^ pseq
159
160 directs any \fIMH\fR command that accepts a `msg' or `msgs' argument to
161 define the sequence \*(lqpseq\*(rq as those messages when it finishes.
162
163 \fBNote:\fP there can be a performance penalty in using the
164 \*(lqPrevious\-Sequence\*(rq facility.
165 If it is used,
166 \fBall\fP \fIMH\fR programs have to write the sequence information
167 to the \&.mh\(rusequences file for
168 the folder each time they run.
169 If the \*(lqPrevious\-Sequence\*(rq profile entry is not included,
170 only \fIpick\fR and \fImark\fR will write to the \&.mh\(rusequences file.
171
172 .Uh "The Unseen Sequence"
173 Finally, some users like to indicate messages which have not been
174 previously seen by them.
175 Both \fIinc\fR and \fIshow\fR honor the profile entry
176 \*(lqUnseen\-Sequence\*(rq to support this activity.
177 This entry in the \&.mh\(ruprofile should be defined
178 as one or more sequence names separated by spaces.
179 If there is a value for \*(lqUnseen\-Sequence\*(rq in the profile,
180 then whenever \fIinc\fR places new messages in a folder,
181 the new messages will also be added to the sequence(s) named
182 in the value of this entry.
183 Hence, a profile entry of
184
185 .ti +.5i
186 Unseen\-Sequence:\^ unseen
187
188 directs \fIinc\fR to add new messages to the sequence \*(lqunseen\*(rq.
189 Unlike the behavior of the \*(lqPrevious\-Sequence\*(rq entry in the profile,
190 however, the sequence(s) will \fBnot\fR be zeroed by \fIinc\fP.
191
192 Similarly,
193 whenever \fIshow\fR (or \fInext\fR or \fIprev\fR\^) displays a message,
194 that message will be removed
195 from any sequences named by the
196 \*(lqUnseen\-Sequence\*(rq entry in the profile.
197
198 .Fi
199 ^$HOME/\&.mh\(ruprofile~^The user profile
200 ^<mh\-dir>/context~^The user context
201 ^<folder>/\&.mh\(rusequences~^Public sequences for <folder>
202 .Pr
203 ^Sequence\-Negation:~^To designate messages not in a sequence
204 .Ps
205 ^Previous\-Sequence:~^The last message specification given
206 .Ps
207 ^Unseen\-Sequence:~^Those messages not yet seen by the user
208 .Sa
209 mh(1), mark(1), pick(1), mh-profile(5)
210 .De
211 None
212 .Co
213 All
214 .Bu
215 User-defined sequences are stored in the \&.mh\(rusequences file
216 as a series of message specifications separated by spaces.
217 If a user-defined sequence contains too many individual
218 message specifications,
219 that line in the file may become too long for \fIMH\fP to handle.
220 This will generate the error message \*(lq\&.mh\(rusequences is
221 poorly formatted\*(rq. You'll have to edit the file by hand to
222 remove the offending line.
223
224 This can happen to users who define the \*(lqPrevious\-Sequence\*(rq entry in
225 the \fIMH\fP profile
226 and have a folder containing many messages with gaps in the numbering.
227 A workaround for large folders is to minimize numbering gaps by using
228 \*(lqfolder\ \-pack\*(rq often.
229 .En