X-Git-Url: http://git.marmaro.de/?p=mmh;a=blobdiff_plain;f=man%2Fmh-sequence.man7;h=0ad2c4a4e73ba4e0c4326035d53720b00d95a4d0;hp=b96230ea94aecfd3e959c2687c9969b2eaf9cfaa;hb=18591f8e001ecedbee48a51c1d1f08ebaa1c15c8;hpb=c2360569e1d8d3678e294eb7c1354cb8bf7501c1 diff --git a/man/mh-sequence.man7 b/man/mh-sequence.man7 index b96230e..0ad2c4a 100644 --- a/man/mh-sequence.man7 +++ b/man/mh-sequence.man7 @@ -3,110 +3,124 @@ .\" .TH MH-SEQUENCE %manext7% "%nmhdate%" MH.6.8 [%nmhversion%] .SH NAME -mh-sequence \- sequence specification for nmh message system -.SH SYNOPSIS -most -.B nmh -commands +mh-sequence \- sequence specification for mh message system .SH DESCRIPTION A sequence (or sequence set) is a symbolic name representing a message or collection of messages. -.B nmh +.B mmh 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 +.B mmh 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: +or one of these `reserved' 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 +.I "Name Description +f the first message in the folder +p the message numerically preceding `c' +c the most recently accessed message +n the message numerically following `c' +l the last message in the folder .fi .RE .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 `c'. .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. +and 325, `f' is 5 and `l' is 325. If `c' +is 94, then `p' is 10 and `n' 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 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 `name1\-name2' or +`name:i', where `name', `name1' and `name2' are message names, +and `i' 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 `name1\-name2' designates all currently existing +messages from `name1' to `name2' inclusive. The `reserved' +message name `a' (``all'') is a shorthand for the message range +`f\-l'. .PP -The specification \*(lqname:n\*(rq designates up to `n' messages. +.RS 5 +.nf +.ta +\w'\fIName\fP 'u +.I "Name Description +a all messages in the folder (i.e. `f\-l') +.fi +.RE +.PP +The specification `name:i' designates up to `i' 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 -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 reserved names `f' `c', or `n', The +messages end with `name' if `name' is `p' or `l'. +The interpretation of `i' may be overridden by preceding `i' with a +plus or minus sign; `+i' always means up to `i' messages starting with +`name', and `\-i' always means up to `i' messages ending with `name'. .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 +`c' or `a', depending on which makes more sense +for each command (see the individual man pages for details). +.PP +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 -which is used by the +There is also a special `reserved' message name `b' (``beyond'') +which can be used with the .B mhpath -command. +command. It refers to the next (not yet used) message number +after `l'. +.PP +.RS 5 +.nf +.ta +\w'\fIName\fP 'u +.I "Name Description +b the next message number beyond `l' +.fi +.RE .SS "User\-Defined Message Sequences" -In addition to the \*(lqreserved\*(rq (pre-defined) message names given +In addition to the `reserved' (pre-defined) message names given above, -.B nmh +.B mmh supports user-defined sequence names. User-defined sequences allow the -.B nmh +.B mmh 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 -be one of the \*(lqreserved\*(rq message names above. After defining a +be one of the `reserved' message names above. After defining a sequence, it can be used wherever an -.B nmh +.B mmh command expects a `msg' or `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 +The specification `name:i' may be used, and it designates up +to the first `i' messages (or last `i' messages for `\-i') which are elements of the user-defined sequence `name'. .PP -The specifications \*(lqname:next\*(rq and \*(lqname:prev\*(rq may also +The specifications `name:n' and `name:p' 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:first\*(rq and \*(lqname:last\*(rq are -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 +The specifications `name:f' and `name:l' are +equivalent to `name:1' and `name:\-1', respectively. The +specification `name:c' is not allowed (use just `c' instead). +Note: The syntax of these message range specifications is subject to change in the future. .PP User-defined sequence names are specific to each folder. They are @@ -115,21 +129,21 @@ 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 -.B nmh +.B mmh 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 `Mh\-Sequences' profile entry (default is .IR \&.mh_sequences ). Private sequences are accessible only to the -.B nmh +.B mmh user that defined those sequences and are kept in the user's -.B nmh +.B mh context file. .PP In general, the commands that create sequences (such as @@ -138,53 +152,63 @@ and .BR mark ) will create public sequences if the folder for which the sequences are being defined is writable by the -.B nmh +.B mmh user. For most commands, this can be overridden by using the switches .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 +the `Mh\-Sequences' profile entry is defined but empty, then \fIprivate\fR sequences will be created instead. .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 -\*(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: +.B Mmh +provides the ability to select all messages +.B not +elements of a user-defined sequence. +A special string is used to preface an existing user-defined +sequence name. This specification then refers to those +messages not elements of the specified sequence name. +The default negation prefix is the exlamation mark `!', +but it may be change to any string, by defining the entry +`Sequence\-Negation' in the +.B mmh +profile file. +For example, if the profile entry is: .PP .RS 5 Sequence\-Negation: not .RE .PP then anytime an -.B nmh -command is given \*(lqnotfoo\*(rq as a `msg' or +.B mmh +command is given `notfoo' as a `msg' or `msgs' argument, it would substitute all messages that are not elements -of the sequence \*(lqfoo\*(rq. +of the sequence `foo'. .PP Obviously, the user should beware of defining sequences with names that -begin with the value of the \*(lqSequence\-Negation\*(rq profile entry. +begin with the value of the `Sequence\-Negation' profile entry. +The default value `!' was chosen due to its similar meaning in the C +programming language, and because it cannot be part of a user-defined +sequence. But if your shell provides history expansion, +you might need to quote the exlamation mark (prefix it with a backslash). +.PP +To deactivate the negation mechanism, define Sequence\-Negation in your +profile to an empty value. .SS "The Previous Sequence" -.B Nmh +.B Mmh provides the ability to remember the `msgs' or `msg' argument last given to an -.B nmh -command. The entry \*(lqPrevious\-Sequence\*(rq +.B mmh +command. The entry `Previous\-Sequence' should be defined in the -.B nmh +.B mmh profile; its value should be a sequence name or multiple sequence names separated by spaces. If this entry is defined, when an -.B nmh +.B mmh 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 @@ -194,19 +218,19 @@ Previous\-Sequence: pseq .RE .PP directs any -.B nmh +.B mmh command that accepts a `msg' or `msgs' argument to -define the sequence \*(lqpseq\*(rq as those messages when it finishes. +define the sequence `pseq' as those messages when it finishes. .PP .BR Note : there can be a performance penalty in using the -\*(lqPrevious\-Sequence\*(rq facility. If it is used, +`Previous\-Sequence' facility. If it is used, .B all -.B nmh +.B mmh programs have to write the sequence information to the .I \&.mh_sequences file for the folder each time they run. If the -\*(lqPrevious\-Sequence\*(rq profile entry is not included, only +`Previous\-Sequence' profile entry is not included, only .B pick and .B mark @@ -221,7 +245,6 @@ The commands .BR inc , .BR rcvstore , .BR show , -.BR mhshow , and .B flist honor the sequence. @@ -243,7 +266,6 @@ be zeroed by .PP Similarly, whenever .BR show , -.BR mhshow , .BR next , or .B prev @@ -251,13 +273,13 @@ display a message, that message will be removed from the unseen sequence. .PP The default unseen sequence is named `u'. -To change, define a \*(lqUnseen\-Sequence\*(rq entry in your profile. +To change, define a `Unseen\-Sequence' entry in your profile. It may also contain multiple sequence names, separated by spaces. In this case, anything that applied to a single unseen sequence, applies to multiple ones, too. .PP The unseen sequence mechanism is automatically activated. -To deactivate it, define the \*(lqUnseen\-Sequence\*(rq entry +To deactivate it, define the `Unseen\-Sequence' entry in your profile with an empty value.