--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/mh-sequence.me	Mon Apr 18 23:46:02 2005 +0900
@@ -0,0 +1,229 @@
+.\"	This file is automatically generated.  Do not edit!
+.\" @(#)$Id$
+.SC MH-SEQUENCE 5
+.NA
+mh-sequence \- sequence specification for MH message system
+.SY
+most \fIMH\fR commands
+.DE
+Most \fIMH\fP 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 \*(lqreserved\*(rq message names: 
+.in +.5i
+.sp 1
+.nf
+.ta +\w'\fIName\fP      'u
+\fIName\fP	\fIDescription\fR
+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 \*(lqcur\*(rq
+next	the message numerically following \*(lqcur\*(rq
+.re
+.fi
+.in -.5i
+
+In commands that take a `msg' argument, the default is \*(lqcur\*(rq.
+As a shorthand, \*(lq\&.\*(rq is equivalent to \*(lqcur\*(rq.
+
+For example: In a folder containing five messages numbered 5, 10, 94,
+177 and 325, \*(lqfirst\*(rq is 5 and \*(lqlast\*(rq is 325.
+If \*(lqcur\*(rq is 94, then \*(lqprev\*(rq is 10 and \*(lqnext\*(rq
+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 \*(lqname1\-name2\*(rq
+or \*(lqname:n\*(rq,
+where `name', `name1' and `name2' are message names, and `n' is an integer.
+
+The specification \*(lqname1\-name2\*(rq 
+designates all currently-existing messages from `name1' to `name2' inclusive.
+The message name \*(lqall\*(rq is a shorthand for the message
+range \*(lqfirst\-last\*(rq.
+
+The specification \*(lqname:n\*(rq designates up to `n' messages.
+These messages start with `name' if `name' is a message number
+or one of the reserved names \*(lqfirst\*(rq \*(lqcur\*(rq, or \*(lqnext\*(rq,
+The messages end with `name' if `name' is \*(lqprev\*(rq or \*(lqlast\*(rq.
+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
+\*(lqcur\*(rq or \*(lqall\*(rq, 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.
+
+.Uh "User\-Defined Message Sequences"
+In addition to the \*(lqreserved\*(rq (pre-defined) message names given above,
+\fIMH\fP supports user-defined sequence names.
+User-defined sequences allow the \fIMH\fR 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 \*(lqreserved\*(rq
+message names above.
+After defining a sequence,
+it can be used wherever an \fIMH\fR command expects a `msg' or `msgs'
+argument.
+
+Some forms of message ranges are allowed with user-defined
+sequences.  The 
+specification \*(lqname:n\*(rq 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 \*(lqname:next\*(rq and \*(lqname:prev\*(rq
+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 
+\*(lqname:first\*(rq and \*(lqname:last\*(rq are equivalent
+to \*(lqname:1\*(rq and \*(lqname:\-1\*(rq, respectively.
+The specification \*(lqname:cur\*(rq is not allowed
+(use just \*(lqcur\*(rq 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 \fIpick\fP and \fImark\fP commands.
+
+.Uh "Public and Private User-Defined Sequences"
+There are two varieties of sequences: \fIpublic\fR sequences
+and \fIprivate\fR sequences.
+\fIPublic\fR sequences of a folder are accessible to any \fIMH\fR user that
+can read that folder and are kept in the \&.mh\(rusequences file in the folder.
+\fIPrivate\fR sequences are accessible only to the \fIMH\fR user that defined
+those sequences and are kept in the user's \fIMH\fR context file.
+By default,
+\fIpick\fR and \fImark\fR create \fIpublic\fR sequences
+if the folder for which the sequences are being defined is writable by the
+\fIMH\fR user.
+Otherwise, \fIprivate\fR sequences are created.
+This can be overridden with the `\-public' and `\-private' switches
+to \fImark\fP.
+
+.Uh "Sequence Negation"
+\fIMH\fP provides the ability to select all messages
+not elements of a user-defined sequence.  To do this,
+the user should define the entry
+\*(lqSequence\-Negation\*(rq in the \fIMH\fR 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:
+
+.ti +.5i
+Sequence\-Negation:\^ not
+
+then anytime an \fIMH\fR command is given \*(lqnotfoo\*(rq as a `msg' or
+`msgs' argument,
+it would substitute all messages that are not elements of the sequence
+\*(lqfoo\*(rq.
+
+Obviously,
+the user should beware of defining sequences with names that
+begin with the value of the
+\*(lqSequence\-Negation\*(rq profile entry.
+
+.Uh "The Previous Sequence"
+\fIMH\fR provides the ability
+to remember the `msgs' or
+`msg' argument last given to an \fIMH\fR command.
+The entry \*(lqPrevious\-Sequence\*(rq should be defined in the
+\fIMH\fR profile; its value should be a sequence name or multiple
+sequence names separated by spaces.
+If this entry is defined, when
+when an \fIMH\fP 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
+
+.ti +.5i
+Previous\-Sequence:\^ pseq
+
+directs any \fIMH\fR command that accepts a `msg' or `msgs' argument to
+define the sequence \*(lqpseq\*(rq as those messages when it finishes.
+
+\fBNote:\fP there can be a performance penalty in using the  
+\*(lqPrevious\-Sequence\*(rq facility.
+If it is used,
+\fBall\fP \fIMH\fR programs have to write the sequence information 
+to the \&.mh\(rusequences file for
+the folder each time they run.
+If the \*(lqPrevious\-Sequence\*(rq profile entry is not included,
+only \fIpick\fR and \fImark\fR will write to the \&.mh\(rusequences file.
+
+.Uh "The Unseen Sequence"
+Finally, some users like to indicate messages which have not been
+previously seen by them.
+Both \fIinc\fR and \fIshow\fR honor the profile entry
+\*(lqUnseen\-Sequence\*(rq to support this activity.
+This entry in the \&.mh\(ruprofile should be defined
+as one or more sequence names separated by spaces.
+If there is a value for \*(lqUnseen\-Sequence\*(rq in the profile,
+then whenever \fIinc\fR places new messages in a folder,
+the new messages will also be added to the sequence(s) named
+in the value of this entry.
+Hence, a profile entry of
+
+.ti +.5i
+Unseen\-Sequence:\^ unseen
+
+directs \fIinc\fR to add new messages to the sequence \*(lqunseen\*(rq.
+Unlike the behavior of the \*(lqPrevious\-Sequence\*(rq entry in the profile,
+however, the sequence(s) will \fBnot\fR be zeroed by \fIinc\fP.
+
+Similarly,
+whenever \fIshow\fR (or \fInext\fR or \fIprev\fR\^) displays a message,
+that message will be removed
+from any sequences named by the
+\*(lqUnseen\-Sequence\*(rq entry in the profile.
+
+.Fi
+^$HOME/\&.mh\(ruprofile~^The user profile
+^<mh\-dir>/context~^The user context
+^<folder>/\&.mh\(rusequences~^Public sequences for <folder>
+.Pr
+^Sequence\-Negation:~^To designate messages not in a sequence
+.Ps
+^Previous\-Sequence:~^The last message specification given
+.Ps
+^Unseen\-Sequence:~^Those messages not yet seen by the user
+.Sa
+mh(1), mark(1), pick(1), mh-profile(5)
+.De
+None
+.Co
+All
+.Bu
+User-defined sequences are stored in the \&.mh\(rusequences file 
+as a series of message specifications separated by spaces.
+If a user-defined sequence contains too many individual
+message specifications,
+that line in the file may become too long for \fIMH\fP to handle.
+This will generate the error message \*(lq\&.mh\(rusequences is
+poorly formatted\*(rq.  You'll have to edit the file by hand to
+remove the offending line. 
+
+This can happen to users who define the \*(lqPrevious\-Sequence\*(rq entry in
+the \fIMH\fP profile
+and have a folder containing many messages with gaps in the numbering.
+A workaround for large folders is to minimize numbering gaps by using
+\*(lqfolder\ \-pack\*(rq often.
+.En