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

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