X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/85bb87a28dff30d9e90ec80ab33cd97a3f07cb9d..07661005b9a36338ab158bcbe7762788a1df4030:/man/mh-sequence.man

diff --git a/man/mh-sequence.man b/man/mh-sequence.man
index c47b02b7..0f876e97 100644
--- a/man/mh-sequence.man
+++ b/man/mh-sequence.man
@@ -1,13 +1,9 @@
-.TH MH-SEQUENCE %manext5% "January 9, 2001" "%nmhversion%"
+.TH MH-SEQUENCE %manext5% "June 11, 2013" "%nmhversion%"
 .\"
 .\" %nmhwarning%
 .\"
 .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.
@@ -44,7 +40,7 @@ is 94, then \*(lqprev\*(rq is 10 and \*(lqnext\*(rq is 177.
 .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
@@ -64,6 +60,14 @@ The interpretation of `n' may be overridden by preceding `n' with a
 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
@@ -107,6 +111,15 @@ specification \*(lqname:cur\*(rq is not allowed (use just \*(lqcur\*(rq
 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
@@ -178,7 +191,7 @@ command.  The entry \*(lqPrevious\-Sequence\*(rq
 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
@@ -223,7 +236,7 @@ honor the profile entry
 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
@@ -254,6 +267,28 @@ or
 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