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

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