git.marmaro.de Git - mmh/blob - docs/historical/mh-6.8.5/doc/mh-sequence.me

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