1 .TH MH-SEQUENCE %manext5% "June 11, 2013" "%nmhversion%"
6 mh-sequence \- sequence specification for nmh message system
8 A sequence (or sequence set) is a symbolic name representing a
9 message or collection of messages.
11 has several internally
12 defined sequences, as well as allowing users to define their own
14 .SS "Message Specification and Pre\-Defined Message Sequences"
17 commands accept a `msg' or `msgs' specification, where
18 `msg' indicates one message and `msgs' indicates one or more messages.
19 To designate a message, you may use either its number (e.g., 1, 10, 234)
20 or one of these \*(lqreserved\*(rq message names:
26 first the first message in the folder
27 last the last message in the folder
28 cur the most recently accessed message
29 prev the message numerically preceding \*(lqcur\*(rq
30 next the message numerically following \*(lqcur\*(rq
34 In commands that take a `msg' argument, the default is \*(lqcur\*(rq.
35 As a shorthand, \*(lq\&.\*(rq is equivalent to \*(lqcur\*(rq.
37 For example: In a folder containing five messages numbered 5, 10, 94, 177
38 and 325, \*(lqfirst\*(rq is 5 and \*(lqlast\*(rq is 325. If \*(lqcur\*(rq
39 is 94, then \*(lqprev\*(rq is 10 and \*(lqnext\*(rq is 177.
41 The word `msgs' indicates that one or more messages may be specified.
42 Such a specification consists of one message designation or of several
43 message designations, as separate arguments. A message designation consists
44 either of a message name as defined above, or a message range.
46 A message range is specified as \*(lqname1\-name2\*(rq or
47 \*(lqname:n\*(rq, where `name', `name1' and `name2' are message names,
48 and `n' is an integer.
50 The specification \*(lqname1\-name2\*(rq designates all currently existing
51 messages from `name1' to `name2' inclusive. The \*(lqreserved\*(rq
52 message name \*(lqall\*(rq is a shorthand for the message range
53 \*(lqfirst\-last\*(rq.
55 The specification \*(lqname:n\*(rq designates up to `n' messages.
56 These messages start with `name' if `name' is a message number or one of
57 the reserved names \*(lqfirst\*(rq \*(lqcur\*(rq, or \*(lqnext\*(rq, The
58 messages end with `name' if `name' is \*(lqprev\*(rq or \*(lqlast\*(rq.
59 The interpretation of `n' may be overridden by preceding `n' with a
60 plus or minus sign; `+n' always means up to `n' messages starting with
61 `name', and `\-n' always means up to `n' messages ending with `name'.
63 Substituting `=' for `:' (i.e., \*(lqname=n\*(rq) will reduce the
64 selection from a range of up to `n' messages, to a selection of
65 just the `n'th message. So for example, while \*(lqname:-3\*(rq
66 selects the 3 messages ending with `name', \*(lqname=-3\*(rq selects
67 just the 2nd previous message. It is an error if the requested
68 message does not exist (i.e., there aren't enough messages in the
71 In commands which accept a `msgs' argument, the default is either
72 \*(lqcur\*(rq or \*(lqall\*(rq, depending on which makes more sense
73 for each command (see the individual man pages for details). Repeated
74 specifications of the same message have the same effect as a single
75 specification of the message.
77 There is also a special \*(lqreserved\*(rq message name \*(lqnew\*(rq
81 .SS "User\-Defined Message Sequences"
82 In addition to the \*(lqreserved\*(rq (pre-defined) message names given
85 supports user-defined sequence names. User-defined
88 user a tremendous amount of power in dealing
89 with groups of messages in the same folder by allowing the user to bind
90 a group of messages to a meaningful symbolic name.
92 The name used to denote a message sequence must consist of an alphabetic
93 character followed by zero or more alphanumeric characters, and can not
94 be one of the \*(lqreserved\*(rq message names above. After defining a
95 sequence, it can be used wherever an
97 command expects a `msg' or
100 Some forms of message ranges are allowed with user-defined sequences.
101 The specification \*(lqname:n\*(rq may be used, and it designates up
102 to the first `n' messages (or last `n' messages for `\-n') which are
103 elements of the user-defined sequence `name'.
105 The specifications \*(lqname:next\*(rq and \*(lqname:prev\*(rq may also
106 be used, and they designate the next or previous message (relative to the
107 current message) which is an element of the user-defined sequence `name'.
108 The specifications \*(lqname:first\*(rq and \*(lqname:last\*(rq are
109 equivalent to \*(lqname:1\*(rq and \*(lqname:\-1\*(rq, respectively. The
110 specification \*(lqname:cur\*(rq is not allowed (use just \*(lqcur\*(rq
111 instead). The syntax of these message range specifications is subject
112 to change in the future.
114 Single messages (as opposed to ranges) may also be selected by
115 substituting `=' for `:', as in \*(lqname=n\*(rq. This will reduce
116 the selection from being a range of up to `n' messages, to being a
117 selection of just the `n'th message. So while \*(lqseq:5\*(rq
118 selects the first 5 messages of seqence `seq', \*(lqseq=5\*(rq
119 selects just the 5th message of the sequence. It is
120 an error if the requested message does not exist (i.e., there aren't
121 at least `n' messages in the sequence).
123 User-defined sequence names are specific to each folder. They are
130 .SS "Public and Private User-Defined Sequences"
131 There are two varieties of user-defined sequences:
132 public and private. Public sequences of a folder are accessible to any
134 user that can read that folder. They are kept in each folder
135 in the file determined by the \*(lqmh\-sequences\*(rq profile entry
137 .IR \&.mh\(rusequences ).
138 Private sequences are accessible
141 user that defined those sequences and are kept in
146 In general, the commands that create sequences (such as
150 will create public sequences if the folder for which
151 the sequences are being defined is writable by the
154 For most commands, this can be overridden by using the switches
158 But if the folder is read\-only, or if
159 the \*(lqmh\-sequences\*(rq profile entry is defined but empty, then
160 \fIprivate\fR sequences will be created instead.
161 .SS "Sequence Negation"
163 provides the ability to select all messages not elements of a
164 user-defined sequence. To do this, the user should define the entry
165 \*(lqSequence\-Negation\*(rq in the
167 profile file; its value
168 may be any string. This string is then used to preface an existing
169 user-defined sequence name. This specification then refers to those
170 messages not elements of the specified sequence name. For example, if
171 the profile entry is:
174 Sequence\-Negation: not
179 command is given \*(lqnotfoo\*(rq as a `msg' or
180 `msgs' argument, it would substitute all messages that are not elements
181 of the sequence \*(lqfoo\*(rq.
183 Obviously, the user should beware of defining sequences with names that
184 begin with the value of the \*(lqSequence\-Negation\*(rq profile entry.
185 .SS "The Previous Sequence"
187 provides the ability to remember the `msgs' or `msg' argument
190 command. The entry \*(lqPrevious\-Sequence\*(rq
191 should be defined in the
193 profile; its value should be a sequence
194 name or multiple sequence names, as separate arguments. If this entry
195 is defined, when when an
197 command finishes, it will define the
198 sequence(s) named in the value of this entry to be those messages that
199 were specified to the command. Hence, a profile entry of
202 Previous\-Sequence: pseq
207 command that accepts a `msg' or `msgs' argument to
208 define the sequence \*(lqpseq\*(rq as those messages when it finishes.
211 there can be a performance penalty in using the
212 \*(lqPrevious\-Sequence\*(rq facility. If it is used,
215 programs have to write the sequence information to the
216 .I \&.mh\(rusequences
217 file for the folder each time they run. If the
218 \*(lqPrevious\-Sequence\*(rq profile entry is not included, only
223 .B \&.mh\(rusequences
225 .SS "The Unseen Sequence"
226 Finally, many users like to indicate which messages have not been
227 previously seen by them. The commands
234 honor the profile entry
235 \*(lqUnseen\-Sequence\*(rq to support this activity. This entry
238 should be defined as one or more sequence
239 names, as separate arguments. If there is a value for
240 \*(lqUnseen\-Sequence\*(rq in the profile, then whenever new messages
241 are placed in a folder (using
245 the new messages will also be added to all the sequences named in this
246 profile entry. For example, a profile entry of
249 Unseen\-Sequence: unseen
254 to add new messages to the sequence \*(lqunseen\*(rq.
255 Unlike the behavior of the \*(lqPrevious\-Sequence\*(rq entry in the
256 profile, however, the sequence(s) will
267 displays a message, that message will be removed from
268 any sequences named by the \*(lqUnseen\-Sequence\*(rq entry in the
270 .SS Sequence File Format
271 The sequence file format is based on the RFC\-5322 message format. Each line
272 of the sequence file corresponds to one sequence. The line starts with the
273 sequence name followed by a `:', then followed by a space-separated list of message numbers
274 that correspond to messages that are part of the named sequence. A contiguous
275 range of messages can be represented as \*(lqlownum\-highnum\*(rq.
277 .B Sample sequence file
288 commands that modify the sequence file will silently remove sequences for
289 nonexistant messages when the sequence file is updated. The exception to
290 this is the \*(lqcur\*(rq sequence, which is allowed to point to a
292 .SS Sequence File Locking
293 The \*(lqdatalocking\*(rq profile entry controls the type of locking used
294 when reading and writing sequence files. The locking mechanisms supported
297 This protects sequence file integrity when multiple
299 commands are run simultaneously.
301 commands that modify the sequence file use transactional locks; the lock
302 is held from the time the sequence file is read until it it written out.
303 This ensures that modifications to the sequence file will not be lost
304 if multiple commands are run simultaneously. Long\-running
310 will release the sequence lock during the bulk of their runtime and reread
311 the sequence file after their processing is complete to reduce lock
315 Currently transactional locks are
317 supported for public sequences; private sequences will not get corrupted, but
318 the possibility exists that two
320 commands run simultaneously that add messages to a private sequence could result in
321 one command's messages not appearing on the requested sequence.
325 .ta \w'%nmhetcdir%/ExtraBigFileName 'u
326 ^$HOME/\&.mh\(ruprofile~^The user profile
327 ^<mh\-dir>/context~^The user context
328 ^<folder>/\&.mh\(rusequences~^File for public sequences
330 .SH "PROFILE COMPONENTS"
334 .ta \w'ExtraBigProfileName 'u
335 ^mh-sequences:~^Name of file to store public sequences
336 ^Sequence\-Negation:~^To designate messages not in a sequence
337 ^Previous\-Sequence:~^The last message specification given
338 ^Unseen\-Sequence:~^Those messages not yet seen by the user
projects / nmh / blob