Added test case for commit 4318012376e06229307c0ed4f62a00faae9edc63.

[nmh] / man / mh-sequence.man

diff --git a/man/mh-sequence.man b/man/mh-sequence.man
index 7d2c72b4504531e3d8853a1e6229c748dbc29a68..4b1e19200b9c0d151757b9c2c2566d3f24aaf436 100644 (file)
--- a/man/mh-sequence.man
+++ b/man/mh-sequence.man
@@ -1,64 +1,65 @@
+.TH MH-SEQUENCE %manext5% "June 11, 2013" "%nmhversion%"

 .\"
 .\" %nmhwarning%
 .\"
 .\" %nmhwarning%

-.\" $Id$

 .\"
 .\"

-.\" include the -mh macro file
-.so %etcdir%/tmac.h
-.\"
-.TH MH-SEQUENCE %manext5% MH.6.8 [%nmhversion%]

 .SH NAME
 mh-sequence \- sequence specification for nmh message system
 .SH NAME
 mh-sequence \- sequence specification for nmh message system

-.SH SYNOPSIS
-.in +.5i
-.ti -.5i
-most \fInmh\fR commands
-.in -.5i

 .SH DESCRIPTION
 A sequence (or sequence set) is a symbolic name representing a
 .SH DESCRIPTION
 A sequence (or sequence set) is a symbolic name representing a

-message or collection of messages.  \fInmh\fP has several internally
+message or collection of messages.
+.B nmh
+has several internally

 defined sequences, as well as allowing users to define their own
 sequences.
 defined sequences, as well as allowing users to define their own
 sequences.

-
-.Uh "Message Specification and Pre\-Defined Message Sequences"
-Most \fInmh\fP commands accept a `msg' or `msgs' specification, where
+.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.
 To designate a message, you may use either its number (e.g., 1, 10, 234)
 or one of these \*(lqreserved\*(rq message names:
 `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:

-.in +.5i
-.sp 1
-.nf
-.ta +\w'\fIName\fP      'u
-\fIName\fP     \fIDescription\fR
-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
-.re
-.fi
-.in -.5i
-
+.PP
+.RS 5
+.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.
 In commands that take a `msg' argument, the default is \*(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
 is 94, then \*(lqprev\*(rq is 10 and \*(lqnext\*(rq is 177.
 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
 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
 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.
 either of a message name as defined above, or a message range.

-
+.PP

 A message range is specified as \*(lqname1\-name2\*(rq or
 \*(lqname:n\*(rq, where `name', `name1' and `name2' are message names,
 and `n' is an integer.
 A message range is specified as \*(lqname1\-name2\*(rq or
 \*(lqname:n\*(rq, where `name', `name1' and `name2' are message names,
 and `n' is an integer.

-
+.PP

 The specification \*(lqname1\-name2\*(rq designates all currently existing
 messages from `name1' to `name2' inclusive.  The \*(lqreserved\*(rq
 message name \*(lqall\*(rq is a shorthand for the message range
 \*(lqfirst\-last\*(rq.
 The specification \*(lqname1\-name2\*(rq designates all currently existing
 messages from `name1' to `name2' inclusive.  The \*(lqreserved\*(rq
 message name \*(lqall\*(rq is a shorthand for the message range
 \*(lqfirst\-last\*(rq.

-
+.PP

 The specification \*(lqname:n\*(rq designates up to `n' messages.
 These messages start with `name' if `name' is a message number or one of
 the reserved names \*(lqfirst\*(rq \*(lqcur\*(rq, or \*(lqnext\*(rq, The
 The specification \*(lqname:n\*(rq designates up to `n' messages.
 These messages start with `name' if `name' is a message number or one of
 the reserved names \*(lqfirst\*(rq \*(lqcur\*(rq, or \*(lqnext\*(rq, The


@@ -66,34 +67,49 @@ messages end with `name' if `name' is \*(lqprev\*(rq or \*(lqlast\*(rq.
 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'.
 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
 specifications of the same message have the same effect as a single
 specification of the message.
 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
 specifications of the same message have the same effect as a single
 specification of the message.

-
+.PP

 There is also a special \*(lqreserved\*(rq message name \*(lqnew\*(rq
 There is also a special \*(lqreserved\*(rq message name \*(lqnew\*(rq

-which is used by the \fImhpath\fR command.
-
-.Uh "User\-Defined Message Sequences"
+which is used by the
+.B mhpath
+command.
+.SS "User\-Defined Message Sequences"

 In addition to the \*(lqreserved\*(rq (pre-defined) message names given
 In addition to the \*(lqreserved\*(rq (pre-defined) message names given

-above, \fInmh\fP supports user-defined sequence names.  User-defined
-sequences allow the \fInmh\fR user a tremendous amount of power in dealing
+above,
+.B nmh
+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.
 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
 be one of the \*(lqreserved\*(rq message names above.  After defining a
 The name used to denote a message sequence must consist of an alphabetic
 character followed by zero or more alphanumeric characters, and can not
 be one of the \*(lqreserved\*(rq message names above.  After defining a

-sequence, it can be used wherever an \fInmh\fR command expects a `msg' or
+sequence, it can be used wherever an
+.B nmh
+command expects a `msg' or

 `msgs' argument.
 `msgs' argument.

-
+.PP

 Some forms of message ranges are allowed with user-defined sequences.
 The specification \*(lqname:n\*(rq may be used, and it designates up
 to the first `n' messages (or last `n' messages for `\-n') which are
 elements of the user-defined sequence `name'.
 Some forms of message ranges are allowed with user-defined sequences.
 The specification \*(lqname:n\*(rq may be used, and it designates up
 to the first `n' messages (or last `n' messages for `\-n') which are
 elements of the user-defined sequence `name'.

-
+.PP

 The specifications \*(lqname:next\*(rq and \*(lqname:prev\*(rq may also
 be used, and they designate the next or previous message (relative to the
 current message) which is an element of the user-defined sequence `name'.
 The specifications \*(lqname:next\*(rq and \*(lqname:prev\*(rq may also
 be used, and they designate the next or previous message (relative to the
 current message) which is an element of the user-defined sequence `name'.


@@ -102,108 +118,246 @@ equivalent to \*(lqname:1\*(rq and \*(lqname:\-1\*(rq, respectively.  The
 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.
 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 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).
+.PP

 User-defined sequence names are specific to each folder.  They are
 User-defined sequence names are specific to each folder.  They are

-defined using the \fIpick\fP and \fImark\fP commands.
-
-.Uh "Public and Private User-Defined Sequences"
-There are two varieties of user-defined sequences: \fIpublic\fR and
-\fIprivate\fR.  \fIPublic\fR sequences of a folder are accessible to any
-\fInmh\fR user that can read that folder.  They are kept in each folder
+defined using the
+.B pick
+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
+.B nmh
+user that can read that folder.  They are kept in each folder

 in the file determined by the \*(lqmh\-sequences\*(rq profile entry
 in the file determined by the \*(lqmh\-sequences\*(rq profile entry

-(default is \&.mh\(rusequences).  \fIPrivate\fR sequences are accessible
-only to the \fInmh\fR user that defined those sequences and are kept in
-the user's \fInmh\fR context file.
-
-In general, the commands that create sequences (such as \fIpick\fR and
-\fImark\fR) will create \fIpublic\fR sequences if the folder for which
-the sequences are being defined is writable by the \fInmh\fR user.
+(default is
+.IR \&.mh\(rusequences ).
+Private sequences are accessible
+only to the
+.B nmh
+user that defined those sequences and are kept in
+the user's
+.B nmh
+context file.
+.PP
+In general, the commands that create sequences (such as
+.B pick
+and
+.BR mark )
+will create public sequences if the folder for which
+the sequences are being defined is writable by the
+.B nmh
+user.

 For most commands, this can be overridden by using the switches
 For most commands, this can be overridden by using the switches

-`\-public' and `\-private'.  But if the folder is read\-only, or if
+.B \-public
+and
+.BR \-private .
+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.
 the \*(lqmh\-sequences\*(rq profile entry is defined but empty, then
 \fIprivate\fR sequences will be created instead.

-
-.Uh "Sequence Negation"
-\fInmh\fP provides the ability to select all messages not elements of a
+.SS "Sequence Negation"
+.B Nmh
+provides the ability to select all messages not elements of a

 user-defined sequence.  To do this, the user should define the entry
 user-defined sequence.  To do this, the user should define the entry

-\*(lqSequence\-Negation\*(rq in the \fInmh\fR profile file; its value
+\*(lqSequence\-Negation\*(rq in the
+.B nmh
+profile file; its value

 may be any string.  This string is then used to preface an existing
 user-defined sequence name.  This specification then refers to those
 messages not elements of the specified sequence name.  For example, if
 the profile entry is:
 may be any string.  This string is then used to preface an existing
 user-defined sequence name.  This specification then refers to those
 messages not elements of the specified sequence name.  For example, if
 the profile entry is:

-
-.ti +.5i
-Sequence\-Negation:\^ not
-
-then anytime an \fInmh\fR command is given \*(lqnotfoo\*(rq as a `msg' or
+.PP
+.RS 5
+Sequence\-Negation: not
+.RE
+.PP
+then anytime an
+.B nmh
+command is given \*(lqnotfoo\*(rq as a `msg' or

 `msgs' argument, it would substitute all messages that are not elements
 of the sequence \*(lqfoo\*(rq.
 `msgs' argument, it would substitute all messages that are not elements
 of the sequence \*(lqfoo\*(rq.

-
+.PP

 Obviously, the user should beware of defining sequences with names that
 begin with the value of the \*(lqSequence\-Negation\*(rq profile entry.
 Obviously, the user should beware of defining sequences with names that
 begin with the value of the \*(lqSequence\-Negation\*(rq profile entry.

-
-.Uh "The Previous Sequence"
-\fInmh\fR provides the ability to remember the `msgs' or `msg' argument
-last given to an \fInmh\fR command.  The entry \*(lqPrevious\-Sequence\*(rq
-should be defined in the \fInmh\fR profile; its value should be a sequence
-name or multiple sequence names separated by spaces.  If this entry
-is defined, when when an \fInmh\fP command finishes, it will define the
+.SS "The Previous Sequence"
+.B Nmh
+provides the ability to remember the `msgs' or `msg' argument
+last given to an
+.B nmh
+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, as separate arguments.  If this entry
+is defined, when 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
 sequence(s) named in the value of this entry to be those messages that
 were specified to the command.  Hence, a profile entry of

-
-.ti +.5i
-Previous\-Sequence:\^ pseq
-
-directs any \fInmh\fR command that accepts a `msg' or `msgs' argument to
+.PP
+.RS 5
+Previous\-Sequence: pseq
+.RE
+.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.
 define the sequence \*(lqpseq\*(rq as those messages when it finishes.

-
-\fBNote:\fP there can be a performance penalty in using the
-\*(lqPrevious\-Sequence\*(rq facility.  If it is used, \fBall\fP
-\fInmh\fR programs have to write the sequence information to the
-\&.mh\(rusequences file for the folder each time they run.  If the
+.PP
+.BR Note :
+there can be a performance penalty in using the
+\*(lqPrevious\-Sequence\*(rq facility.  If it is used,
+.B all
+.B nmh
+programs have to write the sequence information to the
+.I \&.mh\(rusequences
+file for the folder each time they run.  If the

 \*(lqPrevious\-Sequence\*(rq profile entry is not included, only
 \*(lqPrevious\-Sequence\*(rq profile entry is not included, only

-\fIpick\fR and \fImark\fR will write to the \&.mh\(rusequences file.
-
-.Uh "The Unseen Sequence"
+.B pick
+and
+.B mark
+will write to the
+.B \&.mh\(rusequences
+file.
+.SS "The Unseen Sequence"

 Finally, many users like to indicate which messages have not been
 Finally, many users like to indicate which messages have not been

-previously seen by them.  The commands \fIinc\fR, \fIrcvstore\fR,
-\fIshow\fR, \fImhshow\fR, and \fIflist\fR honor the profile entry
+previously seen by them.  The commands
+.BR inc ,
+.BR rcvstore ,
+.BR show ,
+.BR mhshow ,
+and
+.B flist
+honor the profile entry

 \*(lqUnseen\-Sequence\*(rq to support this activity.  This entry
 \*(lqUnseen\-Sequence\*(rq to support this activity.  This entry

-in the \&.mh\(ruprofile should be defined as one or more sequence
-names separated by spaces.  If there is a value for
+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
 \*(lqUnseen\-Sequence\*(rq in the profile, then whenever new messages

-are placed in a folder (using \fIinc\fR or \fIrcvstore\fR), the
-new messages will also be added to all the sequences named in this
+are placed in a folder (using
+.B inc
+or
+.BR rcvstore ),
+the new messages will also be added to all the sequences named in this

 profile entry.  For example, a profile entry of
 profile entry.  For example, a profile entry of

-
-.ti +.5i
-Unseen\-Sequence:\^ unseen
-
-directs \fIinc\fR to add new messages to the sequence \*(lqunseen\*(rq.
+.PP
+.RS 5
+Unseen\-Sequence: unseen
+.RE
+.PP
+directs
+.B inc
+to add new messages to the sequence \*(lqunseen\*(rq.

 Unlike the behavior of the \*(lqPrevious\-Sequence\*(rq entry in the
 Unlike the behavior of the \*(lqPrevious\-Sequence\*(rq entry in the

-profile, however, the sequence(s) will \fBnot\fR be zeroed by \fIinc\fP.
-
-Similarly, whenever \fIshow\fR, \fImhshow\fR, \fInext\fR, or
-\fIprev\fR\^ displays a message, that message will be removed from
+profile, however, the sequence(s) will
+.B not
+be zeroed by
+.BR inc .
+.PP
+Similarly, whenever
+.BR show ,
+.BR mhshow ,
+.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.
 any sequences named by the \*(lqUnseen\-Sequence\*(rq entry in the
 profile.

-
-.Fi
-^$HOME/\&.mh\(ruprofile~^The user profile
-^<mh\-dir>/context~^The user context
-^<folder>/\&.mh\(rusequences~^File for public sequences
-.Pr
-^mh-sequences:~^Name of file to store public sequences
-.Ps
-^Sequence\-Negation:~^To designate messages not in a sequence
-.Ps
-^Previous\-Sequence:~^The last message specification given
-.Ps
-^Unseen\-Sequence:~^Those messages not yet seen by the user
-.Sa
-flist(1), mark(1), pick(1), mh-profile(5)
-.De
+.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
+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
+.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"
+.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),
+.IR pick (1),
+.IR mh-profile (5)
+.SH DEFAULTS

 None
 None

-.Co
-All
-.En