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.

   Message Specification and Pre-Defined Message 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"

       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.

   User-Defined Message Sequences
       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  specifications
       "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 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

       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.

   Sequence Negation
       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.

   The Previous Sequence
       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.

       "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.

   The Unseen Sequence
       Finally, many users like to indicate which  messages  have
       not been previously seen by them.  The commands inc, rcvs­
       tore, show, mhshow, 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 all the sequences named
       in this profile 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, mhshow, next, or prev displays a
       message,  that  message will be removed from any sequences
       named by the "Unseen-Sequence" entry in the profile.


FILES

       $HOME/.mh_profile                    The user profile
       <mh-dir>/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


CONTEXT

       All


Man(1) output converted with man2html