--- name: "mh-sequence" section: "7mh" platform: "linux" package: "mmh" version: "0.4-4" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/mh-sequence/7mh" --- # mh-sequence(7mh) sequence specification for mh message system ## NAME mh-sequence - sequence specification for mh message system ## DESCRIPTION A sequence (or sequence set) is a symbolic name representing a message or collection of messages. **mmh** has several internally defined sequences, as well as allowing users to define their own sequences. ### Message Specification and Pre-Defined Message Sequences Most **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 \`reserved' message names: ``` 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 ``` In commands that take a \`msg' argument, the default is \`c'. For example: In a folder containing five messages numbered 5, 10, 94, 177 and 325, \`f' is 5 and \`l' is 325. If \`c' is 94, then \`p' is 10 and \`n' is 177. 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. A message range is specified as \`name1-name2' or \`name:i', where \`name', \`name1' and \`name2' are message names, and \`i' is an integer. 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'. ``` Name Description a all messages in the folder (i.e. `f-l') ``` 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 \`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'. In commands which accept a \`msgs' argument, the default is either \`c' or \`a', 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. There is also a special \`reserved' message name \`b' (\`\`beyond'') which can be used with the **mhpath** command. It refers to the next (not yet used) message number after \`l'. ``` Name Description b the next message number beyond `l' ``` ### User-Defined Message Sequences In addition to the \`reserved' (pre-defined) message names given above, **mmh** supports user-defined sequence names. User-defined sequences allow the **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. 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 \`reserved' message names above. After defining a sequence, it can be used wherever an **mmh** command expects a \`msg' or \`msgs' argument. Some forms of message ranges are allowed with user-defined sequences. 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'. 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 \`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. User-defined sequence names are specific to each folder. They are defined using the **pick** and **mark** commands. ### 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 **mmh** user that can read that folder. They are kept in each folder in the file determined by the \`Mh-Sequences' profile entry (default is *.mh\_sequences*). Private sequences are accessible only to the **mmh** user that defined those sequences and are kept in the user's **mh** context file. In general, the commands that create sequences (such as **pick** and **mark**) will create public sequences if the folder for which the sequences are being defined is writable by the **mmh** user. For most commands, this can be overridden by using the switches **-public** and **-private**. But if the folder is read-only, or if the \`Mh-Sequences' profile entry is defined but empty, then *private* sequences will be created instead. ### Sequence Negation **Mmh** provides the ability to select all messages **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 **mmh** profile file. For example, if the profile entry is: Sequence-Negation: not then anytime an **mmh** command is given \`notfoo' as a \`msg' or \`msgs' argument, it would substitute all messages that are not elements of the sequence \`foo'. Obviously, the user should beware of defining sequences with names that 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). To deactivate the negation mechanism, define Sequence-Negation in your profile to an empty value. ### The Previous Sequence **Mmh** provides the ability to remember the \`msgs' or \`msg' argument last given to an **mmh** command. The entry \`Previous-Sequence' should be defined in the **mmh** profile; its value should be a sequence name or multiple sequence names separated by spaces. If this entry is defined, when an **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 Previous-Sequence: pseq directs any **mmh** command that accepts a \`msg' or \`msgs' argument to define the sequence \`pseq' as those messages when it finishes. **Note**: there can be a performance penalty in using the \`Previous-Sequence' facility. If it is used, **all** **mmh** programs have to write the sequence information to the *.mh\_sequences* file for the folder each time they run. If the \`Previous-Sequence' profile entry is not included, only **pick** and **mark** will write to the **.mh\_sequences** file. ### The Unseen Sequence Finally, the unseen sequence indicates which messages have not been previously seen by the user. The commands **inc**, **rcvstore**, **show**, and **flist** honor the sequence. Whenever new messages are placed in a folder (using **inc** or **rcvstore**), the new messages will also be added to the unseen sequence. **inc**, for example, adds new messages to the unseen sequence. Unlike the behavior of the previous sequence, however, the unseen sequence will **not** be zeroed by **inc**. Similarly, whenever **show**, **next**, or **prev** display a message, that message will be removed from the unseen sequence. The default unseen sequence is named \`u'. 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. The unseen sequence mechanism is automatically activated. To deactivate it, define the \`Unseen-Sequence' entry in your profile with an empty value. ## FILES ``` ^$HOME/.mmh/profile~^The user profile ^$HOME/.mmh/context~^The user context ^/.mh_sequences~^File for public sequences ``` ## PROFILE COMPONENTS ``` ^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 ``` ## SEE ALSO [flist(1)](/flist/1.md), [mark(1)](/mark/1.md), [pick(1)](/pick/1.md), [mh-profile(5)](/mh-profile/5.md) ## DEFAULTS None