mh-sequence.man: document new '=+' and '=-' for selecting relative msgs

also add a line-item to docs/pending-release-notes.

diff --git a/docs/pending-release-notes b/docs/pending-release-notes
index e88165d..b16b7c1 100644 (file)
--- a/docs/pending-release-notes
+++ b/docs/pending-release-notes
@@ -54,6 +54,8 @@ NEW FEATURES
 - There is no longer a per-folder maximum number of sequences.
 - For the SMTP MTA TLS can now be negotiated at the beginning of the
   connection with the -initialtls switch.
 - There is no longer a per-folder maximum number of sequences.
 - For the SMTP MTA TLS can now be negotiated at the beginning of the
   connection with the -initialtls switch.

+- Messages can now be selected using a relative offset from some other
+  message, or from the start or end of a sequence.  See mh-sequences(5).

 
 ----------------------------
 OBSOLETE/DEPRECATED FEATURES
 
 ----------------------------
 OBSOLETE/DEPRECATED FEATURES

diff --git a/man/mh-sequence.man b/man/mh-sequence.man
index c47b02b..8fbba7d 100644 (file)
--- a/man/mh-sequence.man
+++ b/man/mh-sequence.man
@@ -64,6 +64,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
 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
 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 +115,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
 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
 User-defined sequence names are specific to each folder.  They are
 defined using the
 .B pick