bionic (5) mh-sequence.5mh.gz

Provided by: nmh_1.7.1~RC3-1build1_amd64 bug

NAME

       mh-sequence - sequence specification for nmh message system

DESCRIPTION

       A  sequence  (or  sequence set) is a symbolic name representing 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:

            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, as separate arguments.  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 message 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'.

       Substituting `=' for `:' (i.e., “name=n”) will reduce the selection from a range of up to  `n'  messages,
       to  a selection of just the `n'th message.  So for example, while “name:-3” selects the 3 messages ending
       with `name', “name=-3” selects just the 2nd previous message.  It is an error if  the  requested  message
       does not exist (i.e., there aren't enough messages in the folder).

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

       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 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 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' messages 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.

       Single messages (as opposed to ranges) may also be selected by substituting `=' for `:', as in  “name=n”.
       This will reduce the selection from being a range of up to `n' messages, to being a selection of just the
       `n'th message.  So while “seq:5” selects the first 5 messages of sequence `seq', “seq=5” selects just the
       5th  message of the sequence.  It is an error if the requested message does not exist (i.e., there aren't
       at least `n' messages in the sequence).

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

   Sequence Negation
       Nmh provides the ability to select all messages not elements 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  any  time  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 “Previous-Sequence” should be defined in the nmh profile; its value should be a  sequence  name  or
       multiple  sequence names, as separate arguments.  If this entry is defined, 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  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,  many users like to indicate which messages have not been previously seen by them.  The commands
       flist, inc, mhshow, rcvstore, and  show  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, as separate
       arguments.  If there is a value for “Unseen-Sequence” in the profile,  then  whenever  new  messages  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.

   Sequence File Format
       The sequence file format is based on the RFC 5322  message  format.   Each  line  of  the  sequence  file
       corresponds  to one sequence.  The line starts with the sequence name followed by a `:', then followed by
       a space-separated list of message numbers that  correspond  to  messages  that  are  part  of  the  named
       sequence.  A contiguous range of messages can be represented as “lownum-highnum”.

       Sample sequence file

            work: 3 6 8 22-33 46
            unseen: 47 49-51 54
            cur: 46

       Nmh  commands  that modify the sequence file will silently remove sequences for nonexistent messages when
       the sequence file is updated.  The exception to this is the “cur” sequence, which is allowed to point  to
       a nonexistent message.

   Sequence File Locking
       The  “datalocking”  profile  entry  controls  the  type of locking used when reading and writing sequence
       files.  The locking mechanisms supported are detailed in  mh-profile(5).   This  protects  sequence  file
       integrity  when multiple nmh commands are run simultaneously.  Nmh commands that modify the sequence file
       use transactional locks; the lock is held from the time the sequence file is read  until  it  it  written
       out.   This ensures that modifications to the sequence file will not be lost if multiple commands are run
       simultaneously.  Long-running nmh commands, such as inc and pick, will release the sequence  lock  during
       the  bulk of their runtime and reread the sequence file after their processing is complete to reduce lock
       contention time.

       Note: Currently transactional locks are only supported for public sequences; private sequences  will  not
       get corrupted, but the possibility exists that two nmh commands run simultaneously that add messages to a
       private sequence could result in one command's messages not appearing on the requested sequence.

FILES

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