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
       <folder>/.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), mark(1), pick(1), mh-profile(5)

DEFAULTS

       None

MH.6.8                                             2019-01-06                                   MH-SEQUENCE(7mh)