-.TH MH-SEQUENCE %manext5% "June 11, 2013" "%nmhversion%"
-.\"
+.TH MH-SEQUENCE %manext5% 2013-10-17 "%nmhversion%"
+.
.\" %nmhwarning%
-.\"
+.
.SH NAME
mh-sequence \- sequence specification for nmh message system
.SH DESCRIPTION
A sequence (or sequence set) is a symbolic name representing a
message or collection of messages.
.B nmh
-has several internally
-defined sequences, as well as allowing users to define their own
-sequences.
-.SS "Message Specification and Pre\-Defined Message Sequences"
+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
-commands accept a `msg' or `msgs' specification, where
-`msg' indicates one message and `msgs' indicates one or more messages.
+commands accept a `msg' or `msgs' specification, where `msg'
+indicates one message and `msgs' indicates one or more messages.
To designate a message, you may use either its number (e.g., 1, 10, 234)
or one of these \*(lqreserved\*(rq message names:
.PP
.RS 5
-.nf
-.ta +\w'\fIName\fP 'u
-.I "Name Description"
-first the first message in the folder
-last the last message in the folder
-cur the most recently accessed message
-prev the message numerically preceding \*(lqcur\*(rq
-next the message numerically following \*(lqcur\*(rq
-.fi
+.PD 0
+.TP
+.B first
+the first message in the folder
+.TP
+.B last
+the last message in the folder
+.TP
+.B cur
+the most recently accessed message
+.TP
+.B prev
+the message numerically preceding \*(lqcur\*(rq
+.TP
+.B next
+the message numerically following \*(lqcur\*(rq
.RE
+.PD
.PP
In commands that take a `msg' argument, the default is \*(lqcur\*(rq.
-As a shorthand, \*(lq\&.\*(rq is equivalent to \*(lqcur\*(rq.
+As a shorthand, \*(lq.\*(rq is equivalent to \*(lqcur\*(rq.
.PP
For example: In a folder containing five messages numbered 5, 10, 94, 177
and 325, \*(lqfirst\*(rq is 5 and \*(lqlast\*(rq is 325. If \*(lqcur\*(rq
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
+.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
In addition to the \*(lqreserved\*(rq (pre-defined) message names given
above,
.B nmh
-supports user-defined sequence names. User-defined
-sequences allow the
+supports user-defined sequence names. User-defined sequences allow the
.B nmh
-user a tremendous amount of power in dealing
-with groups of messages in the same folder by allowing the user to bind
-a group of messages to a meaningful symbolic name.
+user a tremendous amount of power in dealing with groups of messages
+in the same folder by allowing the user to bind a group of messages
+to a meaningful symbolic name.
.PP
The name used to denote a message sequence must consist of an alphabetic
character followed by zero or more alphanumeric characters, and can not
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 the first 5 messages of sequence `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).
and
.B mark
commands.
-.PP
.SS "Public and Private User-Defined Sequences"
There are two varieties of user-defined sequences:
public and private. Public sequences of a folder are accessible to any
user that can read that folder. They are kept in each folder
in the file determined by the \*(lqmh\-sequences\*(rq profile entry
(default is
-.IR \&.mh\(rusequences ).
+.IR \&.mh_sequences ).
Private sequences are accessible
only to the
.B nmh
.B \-public
and
.BR \-private .
-But if the folder is read\-only, or if
+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"
Sequence\-Negation: not
.RE
.PP
-then anytime an
+then any time an
.B nmh
command is given \*(lqnotfoo\*(rq as a `msg' or
`msgs' argument, it would substitute all messages that are not elements
.B nmh
profile; its value should be a sequence
name or multiple sequence names, as separate arguments. If this entry
-is defined, when when an
+is defined, when an
.B nmh
-command finishes, it will define the
-sequence(s) named in the value of this entry to be those messages that
-were specified to the command. Hence, a profile entry of
+command finishes, it will define the sequence(s) named in the value
+of this entry to be those messages that were specified to the command.
+Hence, a profile entry of
.PP
.RS 5
Previous\-Sequence: pseq
.PP
directs any
.B nmh
-command that accepts a `msg' or `msgs' argument to
-define the sequence \*(lqpseq\*(rq as those messages when it finishes.
+command that accepts a `msg' or `msgs' argument to define the sequence
+\*(lqpseq\*(rq as those messages when it finishes.
.PP
.BR Note :
there can be a performance penalty in using the
.B all
.B nmh
programs have to write the sequence information to the
-.I \&.mh\(rusequences
+.I \&.mh_sequences
file for the folder each time they run. If the
\*(lqPrevious\-Sequence\*(rq profile entry is not included, only
.B pick
and
.B mark
will write to the
-.B \&.mh\(rusequences
+.B \&.mh_sequences
file.
.SS "The Unseen Sequence"
Finally, many users like to indicate which messages have not been
previously seen by them. The commands
+.BR flist ,
.BR inc ,
-.BR rcvstore ,
-.BR show ,
.BR mhshow ,
+.BR rcvstore ,
and
-.B flist
-honor the profile entry
-\*(lqUnseen\-Sequence\*(rq to support this activity. This entry
-in the
-.I \&.mh\(ruprofile
-should be defined as one or more sequence
-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 show
+honor the profile entry \*(lqUnseen\-Sequence\*(rq to support this
+activity. This entry in the
+.I \&.mh_profile
+should be defined as one or more sequence 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
or
.BR rcvstore ),
to add new messages to the sequence \*(lqunseen\*(rq.
Unlike the behavior of the \*(lqPrevious\-Sequence\*(rq entry in the
profile, however, the sequence(s) will
-.B not
+.I not
be zeroed by
.BR inc .
.PP
.BR next ,
or
.B prev
-displays a message, that message will be removed from
-any sequences named by the \*(lqUnseen\-Sequence\*(rq entry in the
-profile.
+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
+nonexistent messages when the sequence file is updated. The exception to
+this is the \*(lqcur\*(rq sequence, which is allowed to point to a
+nonexistent 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
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
+if multiple commands are run simultaneously. Long-running
.B nmh
commands, such as
.B inc
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
+Note:
+Currently transactional locks are 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
-.ta \w'%etcdir%/ExtraBigFileName 'u
-^$HOME/\&.mh\(ruprofile~^The user profile
-^<mh\-dir>/context~^The user context
-^<folder>/\&.mh\(rusequences~^File for public sequences
-.fi
+.PD 0
+.TP 20
+$HOME/.mh\-profile
+The user's profile.
+.TP 20
+<mh-dir>/context
+The user's context.
+.TP 20
+<folder>/.mh\-sequences
+File for public sequences.
+.PD
.SH "PROFILE COMPONENTS"
-.fc ^ ~
-.nf
-.ta 2.4i
-.ta \w'ExtraBigProfileName 'u
-^mh-sequences:~^Name of file to store public sequences
-^Sequence\-Negation:~^To designate messages not in a sequence
-^Previous\-Sequence:~^The last message specification given
-^Unseen\-Sequence:~^Those messages not yet seen by the user
-.fi
+.PD 0
+.TP 20
+mh-sequences:
+Name of file to store public sequences.
+.TP 20
+Sequence\-Negation:
+To designate messages not in a sequence.
+.TP 20
+Previous\-Sequence:
+The last message specification given.
+.TP 20
+Unseen\-Sequence:
+Those messages not yet seen by the user.
+.PD
.SH "SEE ALSO"
.IR flist (1),
.IR mark (1),
projects / nmh / blobdiff