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 In commands which accept a `msgs' argument, the default is either
68 \*(lqcur\*(rq or \*(lqall\*(rq, depending on which makes more sense
69 for each command (see the individual man pages for details). Repeated
70 specifications of the same message have the same effect as a single
71 specification of the message.
73 There is also a special \*(lqreserved\*(rq message name \*(lqnew\*(rq
77 .SS "User\-Defined Message Sequences"
78 In addition to the \*(lqreserved\*(rq (pre-defined) message names given
81 supports user-defined sequence names. User-defined
84 user a tremendous amount of power in dealing
85 with groups of messages in the same folder by allowing the user to bind
86 a group of messages to a meaningful symbolic name.
88 The name used to denote a message sequence must consist of an alphabetic
89 character followed by zero or more alphanumeric characters, and can not
90 be one of the \*(lqreserved\*(rq message names above. After defining a
91 sequence, it can be used wherever an
93 command expects a `msg' or
96 Some forms of message ranges are allowed with user-defined sequences.
97 The specification \*(lqname:n\*(rq may be used, and it designates up
98 to the first `n' messages (or last `n' messages for `\-n') which are
99 elements of the user-defined sequence `name'.
101 The specifications \*(lqname:next\*(rq and \*(lqname:prev\*(rq may also
102 be used, and they designate the next or previous message (relative to the
103 current message) which is an element of the user-defined sequence `name'.
104 The specifications \*(lqname:first\*(rq and \*(lqname:last\*(rq are
105 equivalent to \*(lqname:1\*(rq and \*(lqname:\-1\*(rq, respectively. The
106 specification \*(lqname:cur\*(rq is not allowed (use just \*(lqcur\*(rq
107 instead). The syntax of these message range specifications is subject
108 to change in the future.
110 User-defined sequence names are specific to each folder. They are
117 .SS "Public and Private User-Defined Sequences"
118 There are two varieties of user-defined sequences:
119 public and private. Public sequences of a folder are accessible to any
121 user that can read that folder. They are kept in each folder
122 in the file determined by the \*(lqmh\-sequences\*(rq profile entry
124 .IR \&.mh\(rusequences ).
125 Private sequences are accessible
128 user that defined those sequences and are kept in
133 In general, the commands that create sequences (such as
137 will create public sequences if the folder for which
138 the sequences are being defined is writable by the
141 For most commands, this can be overridden by using the switches
145 But if the folder is read\-only, or if
146 the \*(lqmh\-sequences\*(rq profile entry is defined but empty, then
147 \fIprivate\fR sequences will be created instead.
148 .SS "Sequence Negation"
150 provides the ability to select all messages not elements of a
151 user-defined sequence. To do this, the user should define the entry
152 \*(lqSequence\-Negation\*(rq in the
154 profile file; its value
155 may be any string. This string is then used to preface an existing
156 user-defined sequence name. This specification then refers to those
157 messages not elements of the specified sequence name. For example, if
158 the profile entry is:
161 Sequence\-Negation: not
166 command is given \*(lqnotfoo\*(rq as a `msg' or
167 `msgs' argument, it would substitute all messages that are not elements
168 of the sequence \*(lqfoo\*(rq.
170 Obviously, the user should beware of defining sequences with names that
171 begin with the value of the \*(lqSequence\-Negation\*(rq profile entry.
172 .SS "The Previous Sequence"
174 provides the ability to remember the `msgs' or `msg' argument
177 command. The entry \*(lqPrevious\-Sequence\*(rq
178 should be defined in the
180 profile; its value should be a sequence
181 name or multiple sequence names separated by spaces. If this entry
182 is defined, when when an
184 command finishes, it will define the
185 sequence(s) named in the value of this entry to be those messages that
186 were specified to the command. Hence, a profile entry of
189 Previous\-Sequence: pseq
194 command that accepts a `msg' or `msgs' argument to
195 define the sequence \*(lqpseq\*(rq as those messages when it finishes.
198 there can be a performance penalty in using the
199 \*(lqPrevious\-Sequence\*(rq facility. If it is used,
202 programs have to write the sequence information to the
203 .I \&.mh\(rusequences
204 file for the folder each time they run. If the
205 \*(lqPrevious\-Sequence\*(rq profile entry is not included, only
210 .B \&.mh\(rusequences
212 .SS "The Unseen Sequence"
213 Finally, many users like to indicate which messages have not been
214 previously seen by them. The commands
221 honor the profile entry
222 \*(lqUnseen\-Sequence\*(rq to support this activity. This entry
225 should be defined as one or more sequence
226 names separated by spaces. If there is a value for
227 \*(lqUnseen\-Sequence\*(rq in the profile, then whenever new messages
228 are placed in a folder (using
232 the new messages will also be added to all the sequences named in this
233 profile entry. For example, a profile entry of
236 Unseen\-Sequence: unseen
241 to add new messages to the sequence \*(lqunseen\*(rq.
242 Unlike the behavior of the \*(lqPrevious\-Sequence\*(rq entry in the
243 profile, however, the sequence(s) will
254 displays a message, that message will be removed from
255 any sequences named by the \*(lqUnseen\-Sequence\*(rq entry in the
260 .ta \w'%etcdir%/ExtraBigFileName 'u
261 ^$HOME/\&.mh\(ruprofile~^The user profile
262 ^<mh\-dir>/context~^The user context
263 ^<folder>/\&.mh\(rusequences~^File for public sequences
265 .SH "PROFILE COMPONENTS"
269 .ta \w'ExtraBigProfileName 'u
270 ^mh-sequences:~^Name of file to store public sequences
271 ^Sequence\-Negation:~^To designate messages not in a sequence
272 ^Previous\-Sequence:~^The last message specification given
273 ^Unseen\-Sequence:~^Those messages not yet seen by the user