git.marmaro.de Git - mmh/blob - man/mh-sequence.man

   1 .\"
   2 .\" %nmhwarning%
   3 .\" $Id$
   4 .\"
   5 .\" include the -mh macro file
   6 .so %etcdir%/tmac.h
   7 .\"
   8 .TH MH-SEQUENCE %manext5% MH.6.8 [%nmhversion%]
   9 .SH NAME
  10 mh-sequence \- sequence specification for nmh message system
  11 .SH SYNOPSIS
  12 .in +.5i
  13 .ti -.5i
  14 most \fInmh\fR commands
  15 .in -.5i
  16 .SH DESCRIPTION
  17 A sequence (or sequence set) is a symbolic name representing a
  18 message or collection of messages.  \fInmh\fP has several internally
  19 defined sequences, as well as allowing users to define their own
  20 sequences.
  21
  22 .Uh "Message Specification and Pre\-Defined Message Sequences"
  23 Most \fInmh\fP commands accept a `msg' or `msgs' specification, where
  24 `msg' indicates one message and `msgs' indicates one or more messages.
  25 To designate a message, you may use either its number (e.g., 1, 10, 234)
  26 or one of these \*(lqreserved\*(rq message names:
  27 .in +.5i
  28 .sp 1
  29 .nf
  30 .ta +\w'\fIName\fP      'u
  31 \fIName\fP      \fIDescription\fR
  32 first   the first message in the folder
  33 last    the last message in the folder
  34 cur     the most recently accessed message
  35 prev    the message numerically preceding \*(lqcur\*(rq
  36 next    the message numerically following \*(lqcur\*(rq
  37 .re
  38 .fi
  39 .in -.5i
  40
  41 In commands that take a `msg' argument, the default is \*(lqcur\*(rq.
  42 As a shorthand, \*(lq\&.\*(rq is equivalent to \*(lqcur\*(rq.
  43
  44 For example: In a folder containing five messages numbered 5, 10, 94, 177
  45 and 325, \*(lqfirst\*(rq is 5 and \*(lqlast\*(rq is 325.  If \*(lqcur\*(rq
  46 is 94, then \*(lqprev\*(rq is 10 and \*(lqnext\*(rq is 177.
  47
  48 The word `msgs' indicates that one or more messages may be specified.
  49 Such a specification consists of one message designation or of several
  50 message designations separated by spaces.  A message designation consists
  51 either of a message name as defined above, or a message range.
  52
  53 A message range is specified as \*(lqname1\-name2\*(rq or
  54 \*(lqname:n\*(rq, where `name', `name1' and `name2' are message names,
  55 and `n' is an integer.
  56
  57 The specification \*(lqname1\-name2\*(rq designates all currently existing
  58 messages from `name1' to `name2' inclusive.  The \*(lqreserved\*(rq
  59 message name \*(lqall\*(rq is a shorthand for the message range
  60 \*(lqfirst\-last\*(rq.
  61
  62 The specification \*(lqname:n\*(rq designates up to `n' messages.
  63 These messages start with `name' if `name' is a message number or one of
  64 the reserved names \*(lqfirst\*(rq \*(lqcur\*(rq, or \*(lqnext\*(rq, The
  65 messages end with `name' if `name' is \*(lqprev\*(rq or \*(lqlast\*(rq.
  66 The interpretation of `n' may be overridden by preceding `n' with a
  67 plus or minus sign; `+n' always means up to `n' messages starting with
  68 `name', and `\-n' always means up to `n' messages ending with `name'.
  69
  70 In commands which accept a `msgs' argument, the default is either
  71 \*(lqcur\*(rq or \*(lqall\*(rq, depending on which makes more sense
  72 for each command (see the individual man pages for details).  Repeated
  73 specifications of the same message have the same effect as a single
  74 specification of the message.
  75
  76 There is also a special \*(lqreserved\*(rq message name \*(lqnew\*(rq
  77 which is used by the \fImhpath\fR command.
  78
  79 .Uh "User\-Defined Message Sequences"
  80 In addition to the \*(lqreserved\*(rq (pre-defined) message names given
  81 above, \fInmh\fP supports user-defined sequence names.  User-defined
  82 sequences allow the \fInmh\fR user a tremendous amount of power in dealing
  83 with groups of messages in the same folder by allowing the user to bind
  84 a group of messages to a meaningful symbolic name.
  85
  86 The name used to denote a message sequence must consist of an alphabetic
  87 character followed by zero or more alphanumeric characters, and can not
  88 be one of the \*(lqreserved\*(rq message names above.  After defining a
  89 sequence, it can be used wherever an \fInmh\fR command expects a `msg' or
  90 `msgs' argument.
  91
  92 Some forms of message ranges are allowed with user-defined sequences.
  93 The specification \*(lqname:n\*(rq may be used, and it designates up
  94 to the first `n' messages (or last `n' messages for `\-n') which are
  95 elements of the user-defined sequence `name'.
  96
  97 The specifications \*(lqname:next\*(rq and \*(lqname:prev\*(rq may also
  98 be used, and they designate the next or previous message (relative to the
  99 current message) which is an element of the user-defined sequence `name'.
 100 The specifications \*(lqname:first\*(rq and \*(lqname:last\*(rq are
 101 equivalent to \*(lqname:1\*(rq and \*(lqname:\-1\*(rq, respectively.  The
 102 specification \*(lqname:cur\*(rq is not allowed (use just \*(lqcur\*(rq
 103 instead).  The syntax of these message range specifications is subject
 104 to change in the future.
 105
 106 User-defined sequence names are specific to each folder.  They are
 107 defined using the \fIpick\fP and \fImark\fP commands.
 108
 109 .Uh "Public and Private User-Defined Sequences"
 110 There are two varieties of user-defined sequences: \fIpublic\fR and
 111 \fIprivate\fR.  \fIPublic\fR sequences of a folder are accessible to any
 112 \fInmh\fR user that can read that folder.  They are kept in each folder
 113 in the file determined by the \*(lqmh\-sequences\*(rq profile entry
 114 (default is \&.mh\(rusequences).  \fIPrivate\fR sequences are accessible
 115 only to the \fInmh\fR user that defined those sequences and are kept in
 116 the user's \fInmh\fR context file.
 117
 118 In general, the commands that create sequences (such as \fIpick\fR and
 119 \fImark\fR) will create \fIpublic\fR sequences if the folder for which
 120 the sequences are being defined is writable by the \fInmh\fR user.
 121 For most commands, this can be overridden by using the switches
 122 `\-public' and `\-private'.  But if the folder is read\-only, or if
 123 the \*(lqmh\-sequences\*(rq profile entry is defined but empty, then
 124 \fIprivate\fR sequences will be created instead.
 125
 126 .Uh "Sequence Negation"
 127 \fInmh\fP provides the ability to select all messages not elements of a
 128 user-defined sequence.  To do this, the user should define the entry
 129 \*(lqSequence\-Negation\*(rq in the \fInmh\fR profile file; its value
 130 may be any string.  This string is then used to preface an existing
 131 user-defined sequence name.  This specification then refers to those
 132 messages not elements of the specified sequence name.  For example, if
 133 the profile entry is:
 134
 135 .ti +.5i
 136 Sequence\-Negation:\^ not
 137
 138 then anytime an \fInmh\fR command is given \*(lqnotfoo\*(rq as a `msg' or
 139 `msgs' argument, it would substitute all messages that are not elements
 140 of the sequence \*(lqfoo\*(rq.
 141
 142 Obviously, the user should beware of defining sequences with names that
 143 begin with the value of the \*(lqSequence\-Negation\*(rq profile entry.
 144
 145 .Uh "The Previous Sequence"
 146 \fInmh\fR provides the ability to remember the `msgs' or `msg' argument
 147 last given to an \fInmh\fR command.  The entry \*(lqPrevious\-Sequence\*(rq
 148 should be defined in the \fInmh\fR profile; its value should be a sequence
 149 name or multiple sequence names separated by spaces.  If this entry
 150 is defined, when when an \fInmh\fP command finishes, it will define the
 151 sequence(s) named in the value of this entry to be those messages that
 152 were specified to the command.  Hence, a profile entry of
 153
 154 .ti +.5i
 155 Previous\-Sequence:\^ pseq
 156
 157 directs any \fInmh\fR command that accepts a `msg' or `msgs' argument to
 158 define the sequence \*(lqpseq\*(rq as those messages when it finishes.
 159
 160 \fBNote:\fP there can be a performance penalty in using the
 161 \*(lqPrevious\-Sequence\*(rq facility.  If it is used, \fBall\fP
 162 \fInmh\fR programs have to write the sequence information to the
 163 \&.mh\(rusequences file for the folder each time they run.  If the
 164 \*(lqPrevious\-Sequence\*(rq profile entry is not included, only
 165 \fIpick\fR and \fImark\fR will write to the \&.mh\(rusequences file.
 166
 167 .Uh "The Unseen Sequence"
 168 Finally, many users like to indicate which messages have not been
 169 previously seen by them.  The commands \fIinc\fR, \fIrcvstore\fR,
 170 \fIshow\fR, \fImhshow\fR, and \fIflist\fR honor the profile entry
 171 \*(lqUnseen\-Sequence\*(rq to support this activity.  This entry
 172 in the \&.mh\(ruprofile should be defined as one or more sequence
 173 names separated by spaces.  If there is a value for
 174 \*(lqUnseen\-Sequence\*(rq in the profile, then whenever new messages
 175 are placed in a folder (using \fIinc\fR or \fIrcvstore\fR), the
 176 new messages will also be added to all the sequences named in this
 177 profile entry.  For example, a profile entry of
 178
 179 .ti +.5i
 180 Unseen\-Sequence:\^ unseen
 181
 182 directs \fIinc\fR to add new messages to the sequence \*(lqunseen\*(rq.
 183 Unlike the behavior of the \*(lqPrevious\-Sequence\*(rq entry in the
 184 profile, however, the sequence(s) will \fBnot\fR be zeroed by \fIinc\fP.
 185
 186 Similarly, whenever \fIshow\fR, \fImhshow\fR, \fInext\fR, or
 187 \fIprev\fR\^ displays a message, that message will be removed from
 188 any sequences named by the \*(lqUnseen\-Sequence\*(rq entry in the
 189 profile.
 190
 191 .Fi
 192 ^$HOME/\&.mh\(ruprofile~^The user profile
 193 ^<mh\-dir>/context~^The user context
 194 ^<folder>/\&.mh\(rusequences~^File for public sequences
 195 .Pr
 196 ^mh-sequences:~^Name of file to store public sequences
 197 .Ps
 198 ^Sequence\-Negation:~^To designate messages not in a sequence
 199 .Ps
 200 ^Previous\-Sequence:~^The last message specification given
 201 .Ps
 202 ^Unseen\-Sequence:~^Those messages not yet seen by the user
 203 .Sa
 204 flist(1), mark(1), pick(1), mh-profile(5)
 205 .De
 206 None
 207 .Co
 208 All
 209 .En