include new files in distribution
[mmh] / man / mh-sequence.man
1 .\"
2 .\" %nmhwarning%
3 .\" $Id$
4 .\"
5 .TH MH-SEQUENCE %manext5% "%nmhdate%" MH.6.8 [%nmhversion%]
6 .SH NAME
7 mh-sequence \- sequence specification for nmh message system
8 .SH SYNOPSIS
9 most
10 .B nmh
11 commands
12 .SH DESCRIPTION
13 A sequence (or sequence set) is a symbolic name representing a
14 message or collection of messages.
15 .B nmh
16 has several internally
17 defined sequences, as well as allowing users to define their own
18 sequences.
19
20 .SS "Message Specification and Pre\-Defined Message Sequences"
21 Most
22 .B nmh
23 commands accept a `msg' or `msgs' specification, where
24 `msg' indicates one message and `msgs' indicates one or more messages.
25 To designate a message, you may use either its number (e.g., 1, 10, 234)
26 or one of these \*(lqreserved\*(rq message names:
27 .PP
28 .RS 5
29 .nf
30 .ta +\w'\fIName\fP      'u
31 .I Name Description
32 first   the first message in the folder
33 last    the last message in the folder
34 cur     the most recently accessed message
35 prev    the message numerically preceding \*(lqcur\*(rq
36 next    the message numerically following \*(lqcur\*(rq
37 .fi
38 .RE
39 .PP
40 In commands that take a `msg' argument, the default is \*(lqcur\*(rq.
41 As a shorthand, \*(lq\&.\*(rq is equivalent to \*(lqcur\*(rq.
42 .PP
43 For example: In a folder containing five messages numbered 5, 10, 94, 177
44 and 325, \*(lqfirst\*(rq is 5 and \*(lqlast\*(rq is 325.  If \*(lqcur\*(rq
45 is 94, then \*(lqprev\*(rq is 10 and \*(lqnext\*(rq is 177.
46 .PP
47 The word `msgs' indicates that one or more messages may be specified.
48 Such a specification consists of one message designation or of several
49 message designations separated by spaces.  A message designation consists
50 either of a message name as defined above, or a message range.
51 .PP
52 A message range is specified as \*(lqname1\-name2\*(rq or
53 \*(lqname:n\*(rq, where `name', `name1' and `name2' are message names,
54 and `n' is an integer.
55 .PP
56 The specification \*(lqname1\-name2\*(rq designates all currently existing
57 messages from `name1' to `name2' inclusive.  The \*(lqreserved\*(rq
58 message name \*(lqall\*(rq is a shorthand for the message range
59 \*(lqfirst\-last\*(rq.
60 .PP
61 The specification \*(lqname:n\*(rq designates up to `n' messages.
62 These messages start with `name' if `name' is a message number or one of
63 the reserved names \*(lqfirst\*(rq \*(lqcur\*(rq, or \*(lqnext\*(rq, The
64 messages end with `name' if `name' is \*(lqprev\*(rq or \*(lqlast\*(rq.
65 The interpretation of `n' may be overridden by preceding `n' with a
66 plus or minus sign; `+n' always means up to `n' messages starting with
67 `name', and `\-n' always means up to `n' messages ending with `name'.
68 .PP
69 In commands which accept a `msgs' argument, the default is either
70 \*(lqcur\*(rq or \*(lqall\*(rq, depending on which makes more sense
71 for each command (see the individual man pages for details).  Repeated
72 specifications of the same message have the same effect as a single
73 specification of the message.
74 .PP
75 There is also a special \*(lqreserved\*(rq message name \*(lqnew\*(rq
76 which is used by the
77 .B mhpath
78 command.
79
80 .SS "User\-Defined Message Sequences"
81 In addition to the \*(lqreserved\*(rq (pre-defined) message names given
82 above,
83 .B nmh
84 supports user-defined sequence names.  User-defined
85 sequences allow the
86 .B nmh
87 user a tremendous amount of power in dealing
88 with groups of messages in the same folder by allowing the user to bind
89 a group of messages to a meaningful symbolic name.
90 .PP
91 The name used to denote a message sequence must consist of an alphabetic
92 character followed by zero or more alphanumeric characters, and can not
93 be one of the \*(lqreserved\*(rq message names above.  After defining a
94 sequence, it can be used wherever an
95 .B nmh
96 command expects a `msg' or
97 `msgs' argument.
98 .PP
99 Some forms of message ranges are allowed with user-defined sequences.
100 The specification \*(lqname:n\*(rq may be used, and it designates up
101 to the first `n' messages (or last `n' messages for `\-n') which are
102 elements of the user-defined sequence `name'.
103 .PP
104 The specifications \*(lqname:next\*(rq and \*(lqname:prev\*(rq may also
105 be used, and they designate the next or previous message (relative to the
106 current message) which is an element of the user-defined sequence `name'.
107 The specifications \*(lqname:first\*(rq and \*(lqname:last\*(rq are
108 equivalent to \*(lqname:1\*(rq and \*(lqname:\-1\*(rq, respectively.  The
109 specification \*(lqname:cur\*(rq is not allowed (use just \*(lqcur\*(rq
110 instead).  The syntax of these message range specifications is subject
111 to change in the future.
112 .PP
113 User-defined sequence names are specific to each folder.  They are
114 defined using the
115 .B pick
116 and
117 .B mark
118 commands.
119 .PP
120 .SS "Public and Private User-Defined Sequences"
121 There are two varieties of user-defined sequences:
122 public and private.  Public sequences of a folder are accessible to any
123 .B nmh
124 user that can read that folder.  They are kept in each folder
125 in the file determined by the \*(lqmh\-sequences\*(rq profile entry
126 (default is
127 .IR \&.mh\(rusequences ).
128 Private sequences are accessible
129 only to the
130 .B nmh
131 user that defined those sequences and are kept in
132 the user's
133 .B nmh
134 context file.
135 .PP
136 In general, the commands that create sequences (such as
137 .B pick
138 and
139 .BR mark )
140 will create public sequences if the folder for which
141 the sequences are being defined is writable by the
142 .B nmh
143 user.
144 For most commands, this can be overridden by using the switches
145 .B \-public
146 and
147 .BR \-private .
148 But if the folder is read\-only, or if
149 the \*(lqmh\-sequences\*(rq profile entry is defined but empty, then
150 \fIprivate\fR sequences will be created instead.
151
152 .SS "Sequence Negation"
153 .B Nmh
154 provides the ability to select all messages not elements of a
155 user-defined sequence.  To do this, the user should define the entry
156 \*(lqSequence\-Negation\*(rq in the
157 .B nmh
158 profile file; its value
159 may be any string.  This string is then used to preface an existing
160 user-defined sequence name.  This specification then refers to those
161 messages not elements of the specified sequence name.  For example, if
162 the profile entry is:
163 .PP
164 .RS 5
165 Sequence\-Negation: not
166 .RE
167 .PP
168 then anytime an
169 .B nmh
170 command is given \*(lqnotfoo\*(rq as a `msg' or
171 `msgs' argument, it would substitute all messages that are not elements
172 of the sequence \*(lqfoo\*(rq.
173 .PP
174 Obviously, the user should beware of defining sequences with names that
175 begin with the value of the \*(lqSequence\-Negation\*(rq profile entry.
176
177 .SS "The Previous Sequence"
178 .B Nmh
179 provides the ability to remember the `msgs' or `msg' argument
180 last given to an
181 .B nmh
182 command.  The entry \*(lqPrevious\-Sequence\*(rq
183 should be defined in the
184 .B nmh
185 profile; its value should be a sequence
186 name or multiple sequence names separated by spaces.  If this entry
187 is defined, when when an
188 .B nmh
189 command finishes, it will define the
190 sequence(s) named in the value of this entry to be those messages that
191 were specified to the command.  Hence, a profile entry of
192 .PP
193 .RS 5
194 Previous\-Sequence: pseq
195 .RE
196 .PP
197 directs any
198 .B nmh
199 command that accepts a `msg' or `msgs' argument to
200 define the sequence \*(lqpseq\*(rq as those messages when it finishes.
201 .PP
202 .BR Note :
203 there can be a performance penalty in using the
204 \*(lqPrevious\-Sequence\*(rq facility.  If it is used,
205 .B all
206 .B nmh
207 programs have to write the sequence information to the
208 .I \&.mh\(rusequences
209 file for the folder each time they run.  If the
210 \*(lqPrevious\-Sequence\*(rq profile entry is not included, only
211 .B pick
212 and
213 .B mark
214 will write to the
215 .B \&.mh\(rusequences
216 file.
217
218 .SS "The Unseen Sequence"
219 Finally, many users like to indicate which messages have not been
220 previously seen by them.  The commands
221 .BR inc ,
222 .BR rcvstore ,
223 .BR show ,
224 .BR mhshow ,
225 and
226 .B flist
227 honor the profile entry
228 \*(lqUnseen\-Sequence\*(rq to support this activity.  This entry
229 in the
230 .I \&.mh\(ruprofile
231 should be defined as one or more sequence
232 names separated by spaces.  If there is a value for
233 \*(lqUnseen\-Sequence\*(rq in the profile, then whenever new messages
234 are placed in a folder (using
235 .B inc
236 or
237 .BR rcvstore ),
238 the new messages will also be added to all the sequences named in this
239 profile entry.  For example, a profile entry of
240 .PP
241 .RS 5
242 Unseen\-Sequence: unseen
243 .RE
244 .PP
245 directs
246 .B inc
247 to add new messages to the sequence \*(lqunseen\*(rq.
248 Unlike the behavior of the \*(lqPrevious\-Sequence\*(rq entry in the
249 profile, however, the sequence(s) will
250 .B not
251 be zeroed by
252 .BR inc .
253 .PP
254 Similarly, whenever
255 .BR show ,
256 .BR mhshow ,
257 .BR next ,
258 or
259 .B prev
260 displays a message, that message will be removed from
261 any sequences named by the \*(lqUnseen\-Sequence\*(rq entry in the
262 profile.
263
264 .SH FILES
265 .fc ^ ~
266 .nf
267 .ta \w'%etcdir%/ExtraBigFileName  'u
268 ^$HOME/\&.mh\(ruprofile~^The user profile
269 ^<mh\-dir>/context~^The user context
270 ^<folder>/\&.mh\(rusequences~^File for public sequences
271 .fi
272
273 .SH "PROFILE COMPONENTS"
274 .fc ^ ~
275 .nf
276 .ta 2.4i
277 .ta \w'ExtraBigProfileName  'u
278 ^mh-sequences:~^Name of file to store public sequences
279 ^Sequence\-Negation:~^To designate messages not in a sequence
280 ^Previous\-Sequence:~^The last message specification given
281 ^Unseen\-Sequence:~^Those messages not yet seen by the user
282 .fi
283
284 .SH "SEE ALSO"
285 flist(1), mark(1), pick(1), mh-profile(5)
286
287 .SH DEFAULTS
288 None