+.TH MH-SEQUENCE %manext5% "June 11, 2013" "%nmhversion%"
.\"
.\" %nmhwarning%
.\"
-.TH MH-SEQUENCE %manext5% "%nmhdate%" MH.6.8 [%nmhversion%]
.SH NAME
mh-sequence \- sequence specification for nmh message system
-.SH SYNOPSIS
-most
-.B nmh
-commands
.SH DESCRIPTION
A sequence (or sequence set) is a symbolic name representing a
message or collection of messages.
has several internally
defined sequences, as well as allowing users to define their own
sequences.
-
.SS "Message Specification and Pre\-Defined Message Sequences"
Most
.B nmh
.PP
The word `msgs' indicates that one or more messages may be specified.
Such a specification consists of one message designation or of several
-message designations separated by spaces. A message designation consists
+message designations, as separate arguments. A message designation consists
either of a message name as defined above, or a message range.
.PP
A message range is specified as \*(lqname1\-name2\*(rq or
plus or minus sign; `+n' always means up to `n' messages starting with
`name', and `\-n' always means up to `n' messages ending with `name'.
.PP
+Substituting `=' for `:' (i.e., \*(lqname=n\*(rq) will reduce the
+selection from a range of up to `n' messages, to a selection of
+just the `n'th message. So for example, while \*(lqname:-3\*(rq
+selects the 3 messages ending with `name', \*(lqname=-3\*(rq selects
+just the 2nd previous message. It is an error if the requested
+message does not exist (i.e., there aren't enough messages in the
+folder).
+.PP
In commands which accept a `msgs' argument, the default is either
\*(lqcur\*(rq or \*(lqall\*(rq, depending on which makes more sense
for each command (see the individual man pages for details). Repeated
which is used by the
.B mhpath
command.
-
.SS "User\-Defined Message Sequences"
In addition to the \*(lqreserved\*(rq (pre-defined) message names given
above,
instead). The syntax of these message range specifications is subject
to change in the future.
.PP
+Single messages (as opposed to ranges) may also be selected by
+substituting `=' for `:', as in \*(lqname=n\*(rq. This will reduce
+the selection from being a range of up to `n' messages, to being a
+selection of just the `n'th message. So while \*(lqseq:5\*(rq
+selects the first 5 messages of seqence `seq', \*(lqseq=5\*(rq
+selects just the 5th message of the sequence. It is
+an error if the requested message does not exist (i.e., there aren't
+at least `n' messages in the sequence).
+.PP
User-defined sequence names are specific to each folder. They are
defined using the
.B pick
But if the folder is read\-only, or if
the \*(lqmh\-sequences\*(rq profile entry is defined but empty, then
\fIprivate\fR sequences will be created instead.
-
.SS "Sequence Negation"
.B Nmh
provides the ability to select all messages not elements of a
.PP
Obviously, the user should beware of defining sequences with names that
begin with the value of the \*(lqSequence\-Negation\*(rq profile entry.
-
.SS "The Previous Sequence"
.B Nmh
provides the ability to remember the `msgs' or `msg' argument
should be defined in the
.B nmh
profile; its value should be a sequence
-name or multiple sequence names separated by spaces. If this entry
+name or multiple sequence names, as separate arguments. If this entry
is defined, when when an
.B nmh
command finishes, it will define the
will write to the
.B \&.mh\(rusequences
file.
-
.SS "The Unseen Sequence"
Finally, many users like to indicate which messages have not been
previously seen by them. The commands
in the
.I \&.mh\(ruprofile
should be defined as one or more sequence
-names separated by spaces. If there is a value for
+names, as separate arguments. If there is a value for
\*(lqUnseen\-Sequence\*(rq in the profile, then whenever new messages
are placed in a folder (using
.B inc
displays a message, that message will be removed from
any sequences named by the \*(lqUnseen\-Sequence\*(rq entry in the
profile.
-
+.SS Sequence File Format
+The sequence file format is based on the RFC\-5322 message format. Each line
+of the sequence file corresponds to one sequence. The line starts with the
+sequence name followed by a `:', then followed by a space-separated list of message numbers
+that correspond to messages that are part of the named sequence. A contiguous
+range of messages can be represented as \*(lqlownum\-highnum\*(rq.
+.PP
+.B Sample sequence file
+.PP
+.RS 5
+.nf
+work: 3 6 8 22-33 46
+unseen: 47 49-51 54
+cur: 46
+.fi
+.RE
+.PP
+.B Nmh
+commands that modify the sequence file will silently remove sequences for
+nonexistant messages when the sequence file is updated. The exception to
+this is the \*(lqcur\*(rq sequence, which is allowed to point to a
+nonexistant message.
+.SS Sequence File Locking
+The \*(lqdatalocking\*(rq profile entry controls the type of locking used
+when reading and writing sequence files. The locking mechanisms supported
+are detailed in
+.IR mh\-profile (5).
+This protects sequence file integrity when multiple
+.B nmh
+commands are run simultaneously.
+.B Nmh
+commands that modify the sequence file use transactional locks; the lock
+is held from the time the sequence file is read until it it written out.
+This ensures that modifications to the sequence file will not be lost
+if multiple commands are run simultaneously. Long\-running
+.B nmh
+commands, such as
+.B inc
+and
+.BR pick ,
+will release the sequence lock during the bulk of their runtime and reread
+the sequence file after their processing is complete to reduce lock
+contention time.
+.PP
+.B Note:
+Currently transactional locks are
+.B only
+supported for public sequences; private sequences will not get corrupted, but
+the possibility exists that two
+.B nmh
+commands run simultaneously that add messages to a private sequence could result in
+one command's messages not appearing on the requested sequence.
.SH FILES
.fc ^ ~
.nf
^<mh\-dir>/context~^The user context
^<folder>/\&.mh\(rusequences~^File for public sequences
.fi
-
.SH "PROFILE COMPONENTS"
.fc ^ ~
.nf
^Previous\-Sequence:~^The last message specification given
^Unseen\-Sequence:~^Those messages not yet seen by the user
.fi
-
.SH "SEE ALSO"
-flist(1), mark(1), pick(1), mh-profile(5)
-
+.IR flist (1),
+.IR mark (1),
+.IR pick (1),
+.IR mh-profile (5)
.SH DEFAULTS
None
projects / nmh / blobdiff