MH-SEQUENCE(5) [nmh-1.0.4] (MH.6.8) MH-SEQUENCE(5)
NAME
mh-sequence - sequence specification for nmh message system
SYNOPSIS
most nmh commands
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:
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 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
Page 1 (printed 2/1/01)
MH-SEQUENCE(5) [nmh-1.0.4] (MH.6.8) MH-SEQUENCE(5)
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 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.
User-defined sequence names are specific to each folder.
They are defined using the pick and mark commands.
Page 2 (printed 2/1/01)
MH-SEQUENCE(5) [nmh-1.0.4] (MH.6.8) MH-SEQUENCE(5)
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 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
Previous-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'
Page 3 (printed 2/1/01)
MH-SEQUENCE(5) [nmh-1.0.4] (MH.6.8) MH-SEQUENCE(5)
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 inc, rcvstore,
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 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.
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
Page 4 (printed 2/1/01)
MH-SEQUENCE(5) [nmh-1.0.4] (MH.6.8) MH-SEQUENCE(5)
All
Page 5 (printed 2/1/01)