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

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