X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/05d340f4adbf3534470550c5fd917b2331d3951e..372d8d466d78a89031d07323b898b4e0703336dc:/man/mh-sequence.man diff --git a/man/mh-sequence.man b/man/mh-sequence.man index 5abb26c1..6590e5b6 100644 --- a/man/mh-sequence.man +++ b/man/mh-sequence.man @@ -1,4 +1,4 @@ -.TH MH-SEQUENCE %manext5% "January 9, 2001" "%nmhversion%" +.TH MH-SEQUENCE %manext5% "March 23, 2017" "%nmhversion%" .\" .\" %nmhwarning% .\" @@ -8,28 +8,35 @@ mh-sequence \- sequence specification for nmh message system 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. @@ -40,7 +47,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 @@ -67,7 +74,7 @@ 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 +.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 @@ -82,12 +89,11 @@ command. 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 @@ -115,7 +121,7 @@ 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 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). @@ -126,7 +132,6 @@ defined using the 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 @@ -174,7 +179,7 @@ the profile entry is: 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 @@ -191,12 +196,12 @@ 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 -is defined, when when an +name or multiple sequence names, as separate arguments. If this entry +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 @@ -204,8 +209,8 @@ 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 @@ -225,20 +230,18 @@ 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 +.B show +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 separated by spaces. If there is a value for -\*(lqUnseen\-Sequence\*(rq in the profile, then whenever new messages -are placed in a folder (using +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 ), @@ -264,9 +267,30 @@ Similarly, whenever .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 @@ -290,31 +314,38 @@ 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 +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 -^/context~^The user context -^/\&.mh\(rusequences~^File for public sequences -.fi +.PD 0 +.TP 20 +$HOME/\&.mh\-profile +The user's profile. +.TP 20 +/context +The user's context. +.TP 20 +/\&.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),