1 .TH MH-SEQUENCE %manext5% "January 9, 2001" "%nmhversion%"
6 mh-sequence \- sequence specification for nmh message system
12 A sequence (or sequence set) is a symbolic name representing a
13 message or collection of messages.
15 has several internally
16 defined sequences, as well as allowing users to define their own
18 .SS "Message Specification and Pre\-Defined Message Sequences"
21 commands accept a `msg' or `msgs' specification, where
22 `msg' indicates one message and `msgs' indicates one or more messages.
23 To designate a message, you may use either its number (e.g., 1, 10, 234)
24 or one of these \*(lqreserved\*(rq message names:
30 first the first message in the folder
31 last the last message in the folder
32 cur the most recently accessed message
33 prev the message numerically preceding \*(lqcur\*(rq
34 next the message numerically following \*(lqcur\*(rq
38 In commands that take a `msg' argument, the default is \*(lqcur\*(rq.
39 As a shorthand, \*(lq\&.\*(rq is equivalent to \*(lqcur\*(rq.
41 For example: In a folder containing five messages numbered 5, 10, 94, 177
42 and 325, \*(lqfirst\*(rq is 5 and \*(lqlast\*(rq is 325. If \*(lqcur\*(rq
43 is 94, then \*(lqprev\*(rq is 10 and \*(lqnext\*(rq is 177.
45 The word `msgs' indicates that one or more messages may be specified.
46 Such a specification consists of one message designation or of several
47 message designations separated by spaces. A message designation consists
48 either of a message name as defined above, or a message range.
50 A message range is specified as \*(lqname1\-name2\*(rq or
51 \*(lqname:n\*(rq, where `name', `name1' and `name2' are message names,
52 and `n' is an integer.
54 The specification \*(lqname1\-name2\*(rq designates all currently existing
55 messages from `name1' to `name2' inclusive. The \*(lqreserved\*(rq
56 message name \*(lqall\*(rq is a shorthand for the message range
57 \*(lqfirst\-last\*(rq.
59 The specification \*(lqname:n\*(rq designates up to `n' messages.
60 These messages start with `name' if `name' is a message number or one of
61 the reserved names \*(lqfirst\*(rq \*(lqcur\*(rq, or \*(lqnext\*(rq, The
62 messages end with `name' if `name' is \*(lqprev\*(rq or \*(lqlast\*(rq.
63 The interpretation of `n' may be overridden by preceding `n' with a
64 plus or minus sign; `+n' always means up to `n' messages starting with
65 `name', and `\-n' always means up to `n' messages ending with `name'.
67 Substituting `=' for `:' (i.e., \*(lqname=n\*(rq) will reduce the
68 selection from a range of up to `n' messages, to a selection of
69 just the `n'th message. So for example, while \*(lqname:-3\*(rq
70 selects the 3 messages ending with `name', \*(lqname=-3\*(rq selects
71 just the 2nd previous message. It is an error if the requested
72 message does not exist (i.e., there aren't enough messages in the
75 In commands which accept a `msgs' argument, the default is either
76 \*(lqcur\*(rq or \*(lqall\*(rq, depending on which makes more sense
77 for each command (see the individual man pages for details). Repeated
78 specifications of the same message have the same effect as a single
79 specification of the message.
81 There is also a special \*(lqreserved\*(rq message name \*(lqnew\*(rq
85 .SS "User\-Defined Message Sequences"
86 In addition to the \*(lqreserved\*(rq (pre-defined) message names given
89 supports user-defined sequence names. User-defined
92 user a tremendous amount of power in dealing
93 with groups of messages in the same folder by allowing the user to bind
94 a group of messages to a meaningful symbolic name.
96 The name used to denote a message sequence must consist of an alphabetic
97 character followed by zero or more alphanumeric characters, and can not
98 be one of the \*(lqreserved\*(rq message names above. After defining a
99 sequence, it can be used wherever an
101 command expects a `msg' or
104 Some forms of message ranges are allowed with user-defined sequences.
105 The specification \*(lqname:n\*(rq may be used, and it designates up
106 to the first `n' messages (or last `n' messages for `\-n') which are
107 elements of the user-defined sequence `name'.
109 The specifications \*(lqname:next\*(rq and \*(lqname:prev\*(rq may also
110 be used, and they designate the next or previous message (relative to the
111 current message) which is an element of the user-defined sequence `name'.
112 The specifications \*(lqname:first\*(rq and \*(lqname:last\*(rq are
113 equivalent to \*(lqname:1\*(rq and \*(lqname:\-1\*(rq, respectively. The
114 specification \*(lqname:cur\*(rq is not allowed (use just \*(lqcur\*(rq
115 instead). The syntax of these message range specifications is subject
116 to change in the future.
118 Single messages (as opposed to ranges) may also be selected by
119 substituting `=' for `:', as in \*(lqname=n\*(rq. This will reduce
120 the selection from being a range of up to `n' messages, to being a
121 selection of just the `n'th message. So while \*(lqseq:5\*(rq
122 selects the first 5 messages of seqence `seq', \*(lqseq=5\*(rq
123 selects just the 5th message of the sequence. It is
124 an error if the requested message does not exist (i.e., there aren't
125 at least `n' messages in the sequence).
127 User-defined sequence names are specific to each folder. They are
134 .SS "Public and Private User-Defined Sequences"
135 There are two varieties of user-defined sequences:
136 public and private. Public sequences of a folder are accessible to any
138 user that can read that folder. They are kept in each folder
139 in the file determined by the \*(lqmh\-sequences\*(rq profile entry
141 .IR \&.mh\(rusequences ).
142 Private sequences are accessible
145 user that defined those sequences and are kept in
150 In general, the commands that create sequences (such as
154 will create public sequences if the folder for which
155 the sequences are being defined is writable by the
158 For most commands, this can be overridden by using the switches
162 But if the folder is read\-only, or if
163 the \*(lqmh\-sequences\*(rq profile entry is defined but empty, then
164 \fIprivate\fR sequences will be created instead.
165 .SS "Sequence Negation"
167 provides the ability to select all messages not elements of a
168 user-defined sequence. To do this, the user should define the entry
169 \*(lqSequence\-Negation\*(rq in the
171 profile file; its value
172 may be any string. This string is then used to preface an existing
173 user-defined sequence name. This specification then refers to those
174 messages not elements of the specified sequence name. For example, if
175 the profile entry is:
178 Sequence\-Negation: not
183 command is given \*(lqnotfoo\*(rq as a `msg' or
184 `msgs' argument, it would substitute all messages that are not elements
185 of the sequence \*(lqfoo\*(rq.
187 Obviously, the user should beware of defining sequences with names that
188 begin with the value of the \*(lqSequence\-Negation\*(rq profile entry.
189 .SS "The Previous Sequence"
191 provides the ability to remember the `msgs' or `msg' argument
194 command. The entry \*(lqPrevious\-Sequence\*(rq
195 should be defined in the
197 profile; its value should be a sequence
198 name or multiple sequence names separated by spaces. If this entry
199 is defined, when when an
201 command finishes, it will define the
202 sequence(s) named in the value of this entry to be those messages that
203 were specified to the command. Hence, a profile entry of
206 Previous\-Sequence: pseq
211 command that accepts a `msg' or `msgs' argument to
212 define the sequence \*(lqpseq\*(rq as those messages when it finishes.
215 there can be a performance penalty in using the
216 \*(lqPrevious\-Sequence\*(rq facility. If it is used,
219 programs have to write the sequence information to the
220 .I \&.mh\(rusequences
221 file for the folder each time they run. If the
222 \*(lqPrevious\-Sequence\*(rq profile entry is not included, only
227 .B \&.mh\(rusequences
229 .SS "The Unseen Sequence"
230 Finally, many users like to indicate which messages have not been
231 previously seen by them. The commands
238 honor the profile entry
239 \*(lqUnseen\-Sequence\*(rq to support this activity. This entry
242 should be defined as one or more sequence
243 names separated by spaces. If there is a value for
244 \*(lqUnseen\-Sequence\*(rq in the profile, then whenever new messages
245 are placed in a folder (using
249 the new messages will also be added to all the sequences named in this
250 profile entry. For example, a profile entry of
253 Unseen\-Sequence: unseen
258 to add new messages to the sequence \*(lqunseen\*(rq.
259 Unlike the behavior of the \*(lqPrevious\-Sequence\*(rq entry in the
260 profile, however, the sequence(s) will
271 displays a message, that message will be removed from
272 any sequences named by the \*(lqUnseen\-Sequence\*(rq entry in the
274 .SS Sequence File Locking
275 The \*(lqdatalocking\*(rq profile entry controls the type of locking used
276 when reading and writing sequence files. The locking mechanisms supported
279 This protects sequence file integrity when multiple
281 commands are run simultaneously.
283 commands that modify the sequence file use transactional locks; the lock
284 is held from the time the sequence file is read until it it written out.
285 This ensures that modifications to the sequence file will not be lost
286 if multiple commands are run simultaneously. Long\-running
292 will release the sequence lock during the bulk of their runtime and reread
293 the sequence file after their processing is complete to reduce lock
297 Currently transactional locks are
299 supported for public sequences; private sequences will not get corrupted, but
300 the possibility exists that two
302 commands run simultaneously that add messages to a private sequence could result in
303 one command's messages not appearing on the requested sequence.
307 .ta \w'%etcdir%/ExtraBigFileName 'u
308 ^$HOME/\&.mh\(ruprofile~^The user profile
309 ^<mh\-dir>/context~^The user context
310 ^<folder>/\&.mh\(rusequences~^File for public sequences
312 .SH "PROFILE COMPONENTS"
316 .ta \w'ExtraBigProfileName 'u
317 ^mh-sequences:~^Name of file to store public sequences
318 ^Sequence\-Negation:~^To designate messages not in a sequence
319 ^Previous\-Sequence:~^The last message specification given
320 ^Unseen\-Sequence:~^Those messages not yet seen by the user
projects / nmh / blob