MH-SEQUENCE(5)                                     MH-SEQUENCE(5)

NAME
       mh-sequence  - sequence specification for nmh message sys-
       tem

SYNOPSIS
       most nmh commands

DESCRIPTION
       A sequence (or sequence set) is a symbolic name represent-
       ing  a message or collection of messages.  nmh has several
       internally defined sequences, as well as allowing users to
       define their own sequences.

       Most  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
       "reserved" message names:

            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 "cur"
            next      the message numerically following "cur"

       In  commands  that  take  a `msg' argument, the default is
       "cur".  As a shorthand, "." is equivalent to "cur".

       For example: In a folder containing five messages numbered
       5,  10,  94,  177 and 325, "first" is 5 and "last" is 325.
       If "cur" is 94, then "prev" is 10 and "next" 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:n",
       where  `name',  `name1' and `name2' are message names, and
       `n' is an integer.

       The specification "name1-name2" designates  all  currently
       existing  messages from `name1' to `name2' inclusive.  The
       "reserved" message name "all" is a shorthand for the  mes-
       sage range "first-last".

       The  specification "name:n" designates up to `n' messages.
       These messages start with `name' if `name'  is  a  message
       number  or  one  of  the  reserved names "first" "cur", or
       "next", The messages end with `name' if `name'  is  "prev"
       or "last".  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'.

       In commands which accept a `msgs' argument, the default is
       either "cur" or "all", 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 mes-
       sage.

       There  is  also  a  special  "reserved" message name "new"
       which is used by the mhpath command.

       In addition to the "reserved" (pre-defined) message  names
       given  above,  nmh  supports  user-defined sequence names.
       User-defined sequences allow the  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  mes-
       sages to a meaningful symbolic name.

       The name used to denote a message sequence must consist of
       an alphabetic character followed by zero or more  alphanu-
       meric  characters,  and  can  not be one of the "reserved"
       message names above.  After defining a sequence, it can be
       used  wherever  an  nmh  command expects a `msg' or `msgs'
       argument.

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

       The specifications "name:next" and "name:prev" 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 specificaitions
       "name:first" and "name:last" are  equivalent  to  "name:1"
       and "name:-1", respectively.  The specification "name:cur"
       is not allowed (use just "cur" instead).   The  syntax  of
       these  message range specifcations 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.

       There  are two varieties of user-defined sequences: public
       and private.  Public sequences of a folder are  accessible
       to  any nmh 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 nmh user that
       defined  those  sequences  and  are kept in the user's nmh
       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  nmh  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.

       nmh  provides  the ability to select all messages not ele-
       ments of a user-defined sequence.  To do  this,  the  user
       should  define  the  entry  "Sequence-Negation" in the 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:

            Sequence-Negation: not

       then anytime an nmh 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.

       nmh provides the ability to remember the `msgs'  or  `msg'
       argument  last given to an nmh command.  The entry "Previ-
       ous-Sequence" should be defined in the  nmh  profile;  its
       value should be a sequence name or multiple sequence names
       separated by spaces.  If this entry is defined, when  when
       an  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

            Previous-Sequence: pseq

       directs  any  nmh  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 nmh pro-
       grams  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.

       Finally, many users like to indicate which  messages  have
       not been previously seen by them.  The commands inc, rcvs-
       tore,  show,   and   flist   honor   the   profile   entry
       "Unseen-Sequence" to support this activity.  This entry in
       the .mh_profile should be defined as one or more  sequence
       names  separated  by  spaces.   If  there  is  a value for
       "Unseen-Sequence" in the profile, then whenever  new  mes-
       sages  are placed in a folder (using inc or rcvstore), the
       new messages will also be added to the  sequence(s)  named
       in  the value of this entry.  For example, a profile entry
       of

            Unseen-Sequence: unseen

       directs inc to add new messages to the sequence  "unseen".
       Unlike  the  behavior  of the "Previous-Sequence" entry in
       the profile, however, the sequence(s) will not  be  zeroed
       by inc.

       Similarly, whenever show (or next or prev) displays a mes-
       sage, that message will  be  removed  from  any  sequences
       named by the "Unseen-Sequence" entry in the profile.

       ^$HOME/.mh_profile~^The    user   profile   ^<mh-dir>/con-
       text~^The user context  ^<folder>/.mh_sequences~^File  for
       public  sequences  ^mh-sequences:~^Name  of  file to store
       public sequences  ^Sequence-Negation:~^To  designate  mes-
       sages not in a sequence ^Previous-Sequence:~^The last mes-
       sage specification given ^Unseen-Sequence:~^Those messages
       not  yet  seen by the user flist(1), mark(1), pick(1), mh-
       profile(5) None All

[nmh-0.27]                    MH.6.8                            1