1MH-SEQUENCE(5)                File Formats Manual               MH-SEQUENCE(5)
2
3
4

NAME

6       mh-sequence - sequence specification for nmh message system
7

DESCRIPTION

9       A  sequence (or sequence set) is a symbolic name representing a message
10       or  collection  of  messages.   nmh  has  several  internally   defined
11       sequences, as well as allowing users to define their own sequences.
12
13   Message Specification and Pre-Defined Message Sequences
14       Most  nmh  commands accept a `msg' or `msgs' specification, where `msg'
15       indicates one message and `msgs' indicates one or  more  messages.   To
16       designate  a  message, you may use either its number (e.g., 1, 10, 234)
17       or one of these “reserved” message names:
18
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 “cur”
23            next   the message numerically following “cur”
24
25       In commands that take a `msg' argument, the default  is  “cur”.   As  a
26       shorthand, “.” is equivalent to “cur”.
27
28       For  example:  In a folder containing five messages numbered 5, 10, 94,
29       177 and 325, “first” is 5 and “last” is 325.   If  “cur”  is  94,  then
30       “prev” is 10 and “next” is 177.
31
32       The  word  `msgs' indicates that one or more messages may be specified.
33       Such a specification consists of one message designation or of  several
34       message  designations,  as  separate  arguments.  A message designation
35       consists either of a message name as defined above, or a message range.
36
37       A message range  is  specified  as  “name1-name2”  or  “name:n”,  where
38       `name', `name1' and `name2' are message names, and `n' is an integer.
39
40       The  specification “name1-name2” designates all currently existing mes‐
41       sages from `name1' to `name2' inclusive.  The “reserved”  message  name
42       “all” is a shorthand for the message range “first-last”.
43
44       The  specification  “name:n” designates up to `n' messages.  These mes‐
45       sages start with `name' if `name' is a message number  or  one  of  the
46       reserved  names  “first” “cur”, or “next”, The messages end with `name'
47       if `name' is “prev” or “last”.  The interpretation of `n' may be  over‐
48       ridden by preceding `n' with a plus or minus sign; `+n' always means up
49       to `n' messages starting with `name', and `-n' always means up  to  `n'
50       messages ending with `name'.
51
52       Substituting  `='  for  `:'  (i.e., “name=n”) will reduce the selection
53       from a range of up to `n' messages, to a selection of  just  the  `n'th
54       message.  So for example, while “name:-3” selects the 3 messages ending
55       with `name', “name=-3” selects just the 2nd previous message.  It is an
56       error  if  the  requested  message  does  not exist (i.e., there aren't
57       enough messages in the folder).
58
59       In commands which accept a `msgs' argument, the default is either “cur”
60       or “all”, depending on which makes more sense for each command (see the
61       individual man pages for details).  Repeated specifications of the same
62       message have the same effect as a single specification of the message.
63
64       There  is also a special “reserved” message name “new” which is used by
65       the mhpath command.
66
67   User-Defined Message Sequences
68       In addition to the “reserved” (pre-defined) message names given  above,
69       nmh supports user-defined sequence names.  User-defined sequences allow
70       the nmh user a tremendous amount of power in  dealing  with  groups  of
71       messages  in  the  same  folder by allowing the user to bind a group of
72       messages to a meaningful symbolic name.
73
74       The name used to denote a message sequence must consist  of  an  alpha‐
75       betic  character  followed by zero or more alphanumeric characters, and
76       can not be one of the “reserved” message names above.  After defining a
77       sequence,  it  can  be  used wherever an nmh command expects a `msg' or
78       `msgs' argument.
79
80       Some forms of message ranges are allowed with  user-defined  sequences.
81       The  specification  “name:n”  may  be used, and it designates up to the
82       first `n' messages (or last `n' messages for `-n') which  are  elements
83       of the user-defined sequence `name'.
84
85       The  specifications  “name:next”  and “name:prev” may also be used, and
86       they designate the next or previous message (relative  to  the  current
87       message)  which is an element of the user-defined sequence `name'.  The
88       specifications “name:first” and “name:last” are equivalent to  “name:1”
89       and  “name:-1”,  respectively.   The  specification  “name:cur”  is not
90       allowed (use just “cur” instead).  The syntax of  these  message  range
91       specifications is subject to change in the future.
92
93       Single  messages (as opposed to ranges) may also be selected by substi‐
94       tuting `=' for `:', as in “name=n”.  This  will  reduce  the  selection
95       from  being a range of up to `n' messages, to being a selection of just
96       the `n'th message.  So while “seq:5” selects the first  5  messages  of
97       sequence  `seq',  “seq=5” selects just the 5th message of the sequence.
98       It is an error if the requested message does  not  exist  (i.e.,  there
99       aren't at least `n' messages in the sequence).
100
101       User-defined  sequence  names  are  specific  to each folder.  They are
102       defined using the pick and mark commands.
103
104   Public and Private User-Defined Sequences
105       There are two varieties of user-defined sequences: public and  private.
106       Public  sequences  of  a folder are accessible to any nmh user that can
107       read that folder.  They are kept in each folder in the file  determined
108       by  the  “mh-sequences” profile entry (default is .mh_sequences).  Pri‐
109       vate sequences are accessible only to the nmh user that  defined  those
110       sequences and are kept in the user's nmh context file.
111
112       In  general, the commands that create sequences (such as pick and mark)
113       will create public sequences if the folder for which the sequences  are
114       being defined is writable by the nmh user.  For most commands, this can
115       be overridden by using the switches -public and -private.  But  if  the
116       folder  is read-only, or if the “mh-sequences” profile entry is defined
117       but empty, then private sequences will be created instead.
118
119   Sequence Negation
120       Nmh provides the ability to select all messages not elements of a user-
121       defined  sequence.   To  do  this,  the  user  should  define the entry
122       “Sequence-Negation” in the nmh profile  file;  its  value  may  be  any
123       string.   This  string is then used to preface an existing user-defined
124       sequence name.  This specification then refers to  those  messages  not
125       elements  of  the specified sequence name.  For example, if the profile
126       entry is:
127
128            Sequence-Negation: not
129
130       then any time an nmh command is given “notfoo” as  a  `msg'  or  `msgs'
131       argument, it would substitute all messages that are not elements of the
132       sequence “foo”.
133
134       Obviously, the user should beware of defining sequences with names that
135       begin with the value of the “Sequence-Negation” profile entry.
136
137   The Previous Sequence
138       Nmh  provides the ability to remember the `msgs' or `msg' argument last
139       given to an nmh  command.   The  entry  “Previous-Sequence”  should  be
140       defined in the nmh profile; its value should be a sequence name or mul‐
141       tiple sequence names, as separate arguments.  If this entry is defined,
142       when  an  nmh command finishes, it will define the sequence(s) named in
143       the value of this entry to be those messages that were specified to the
144       command.  Hence, a profile entry of
145
146            Previous-Sequence: pseq
147
148       directs  any  nmh  command  that  accepts a `msg' or `msgs' argument to
149       define the sequence “pseq” as those messages when it finishes.
150
151       Note:  there  can  be  a  performance  penalty  in  using  the  “Previ‐
152       ous-Sequence”  facility.  If it is used, all nmh programs have to write
153       the sequence information to the .mh_sequences file for the folder  each
154       time  they  run.   If  the  “Previous-Sequence”  profile  entry  is not
155       included, only pick and mark will write to the .mh_sequences file.
156
157   The Unseen Sequence
158       Finally, many users like to indicate which messages have not been  pre‐
159       viously  seen  by them.  The commands flist, inc, mhshow, rcvstore, and
160       show honor the profile entry “Unseen-Sequence” to support  this  activ‐
161       ity.   This  entry  in the .mh_profile should be defined as one or more
162       sequence names, as  separate  arguments.   If  there  is  a  value  for
163       “Unseen-Sequence” in the profile, then whenever new messages are placed
164       in a folder (using inc or rcvstore), the  new  messages  will  also  be
165       added to all the sequences named in this profile entry.  For example, a
166       profile entry of
167
168            Unseen-Sequence: unseen
169
170       directs inc to add new messages to the sequence “unseen”.   Unlike  the
171       behavior  of the “Previous-Sequence” entry in the profile, however, the
172       sequence(s) will not be zeroed by inc.
173
174       Similarly, whenever show, mhshow, next, or  prev  displays  a  message,
175       that   message  will  be  removed  from  any  sequences  named  by  the
176       “Unseen-Sequence” entry in the profile.
177
178   Sequence File Format
179       The sequence file format is based on the RFC 5322 message format.  Each
180       line of the sequence file corresponds to one sequence.  The line starts
181       with the sequence name followed by a `:', then followed by a space-sep‐
182       arated  list  of  message  numbers that correspond to messages that are
183       part of the named sequence.  A contiguous range of messages can be rep‐
184       resented as “lownum-highnum”.
185
186       Sample sequence file
187
188            work: 3 6 8 22-33 46
189            unseen: 47 49-51 54
190            cur: 46
191
192       Nmh  commands  that  modify  the  sequence  file  will  silently remove
193       sequences for nonexistent messages when the sequence file  is  updated.
194       The  exception to this is the “cur” sequence, which is allowed to point
195       to a nonexistent message.
196
197   Sequence File Locking
198       The “datalocking” profile entry controls the type of locking used  when
199       reading  and  writing sequence files.  The locking mechanisms supported
200       are detailed in mh-profile(5).  This protects sequence  file  integrity
201       when  multiple  nmh commands are run simultaneously.  Nmh commands that
202       modify the sequence file use transactional locks; the lock is held from
203       the  time  the  sequence  file  is  read until it it written out.  This
204       ensures that modifications to the sequence file will  not  be  lost  if
205       multiple  commands  are run simultaneously.  Long-running nmh commands,
206       such as inc and pick, will release the sequence lock during the bulk of
207       their  runtime  and  reread the sequence file after their processing is
208       complete to reduce lock contention time.
209
210       Note: Currently transactional  locks  are  only  supported  for  public
211       sequences;  private sequences will not get corrupted, but the possibil‐
212       ity exists that two nmh commands run simultaneously that  add  messages
213       to  a  private  sequence  could  result  in  one command's messages not
214       appearing on the requested sequence.
215

FILES

217       $HOME/.mh-profile   The user's profile.
218       <mh-dir>/context    The user's context.
219       <folder>/.mh-sequences
220                           File for public sequences.
221

PROFILE COMPONENTS

223       mh-sequences:       Name of file to store public sequences.
224       Sequence-Negation:  To designate messages not in a sequence.
225       Previous-Sequence:  The last message specification given.
226       Unseen-Sequence:    Those messages not yet seen by the user.
227

SEE ALSO

229       flist(1), mark(1), pick(1), mh-profile(5)
230

DEFAULTS

232       None
233
234
235
236nmh-1.7.1                         2013-10-17                    MH-SEQUENCE(5)
Impressum