mutt stable branch with some hacks
Update pattern documentation.
Note that ~b, ~B, ~h, ~M, and ~X read the message in, and that this
can be much slower.
Change =b, =B, =h table rows to document just the IMAP behavior. The
"=" simple string behavior is already covered below, and makes it less
obvious whether "***)" should be added to those entries in the table.
Break up the simple string and imap server-side matching explanation
into two paragraphs.
Add ~M to the list of patterns you can't use message scoring with.
Add equivalent, if briefer, explanations to the muttrc.man page.
+58
-29
+45
-28
doc/manual.xml.head
+45
-28
doc/manual.xml.head
···
3904
3904
</cmdsynopsis>
3905
3905
3906
3906
<para>
3907
-
The <command>score</command> commands adds <emphasis>value</emphasis> to
3908
-
a message's score if <emphasis>pattern</emphasis> matches it.
3909
-
<emphasis>pattern</emphasis> is a string in the format described in the
3910
-
<link linkend="patterns">patterns</link> section (note: For efficiency
3911
-
reasons, patterns which scan information not available in the index,
3912
-
such as <literal>~b</literal>, <literal>~B</literal>, <literal>~h</literal>,
3913
-
or <literal>~X</literal> may not be used). <emphasis>value</emphasis> is
3914
-
a positive or negative integer. A message's final score is the sum
3915
-
total of all matching <command>score</command> entries. However, you
3916
-
may optionally prefix <emphasis>value</emphasis> with an equal sign
3917
-
(<quote>=</quote>) to cause evaluation to stop at a particular entry if
3918
-
there is a match. Negative final scores are rounded up to 0.
3907
+
The <command>score</command> commands adds <emphasis>value</emphasis>
3908
+
to a message's score if <emphasis>pattern</emphasis> matches it.
3909
+
<emphasis>pattern</emphasis> is a string in the format described in
3910
+
the <link linkend="patterns">patterns</link> section (note: For
3911
+
efficiency reasons, patterns which scan information not available in
3912
+
the index, such as <literal>~b</literal>, <literal>~B</literal>,
3913
+
<literal>~h</literal>, <literal>~M</literal>, or <literal>~X</literal>
3914
+
may not be used). <emphasis>value</emphasis> is a positive or
3915
+
negative integer. A message's final score is the sum total of all
3916
+
matching <command>score</command> entries. However, you may
3917
+
optionally prefix <emphasis>value</emphasis> with an equal sign
3918
+
(<quote>=</quote>) to cause evaluation to stop at a particular entry
3919
+
if there is a match. Negative final scores are rounded up to 0.
3919
3920
</para>
3920
3921
3921
3922
<para>
···
5176
5177
</thead>
5177
5178
<tbody>
5178
5179
<row><entry>~A</entry><entry>all messages</entry></row>
5179
-
<row><entry>~b <emphasis>EXPR</emphasis></entry><entry>messages which contain <emphasis>EXPR</emphasis> in the message body</entry></row>
5180
-
<row><entry>=b <emphasis>STRING</emphasis></entry><entry>messages which contain <emphasis>STRING</emphasis> in the message body. If IMAP is enabled, searches for <emphasis>STRING</emphasis> on the server, rather than downloading each message and searching it locally.</entry></row>
5181
-
<row><entry>~B <emphasis>EXPR</emphasis></entry><entry>messages which contain <emphasis>EXPR</emphasis> in the whole message</entry></row>
5182
-
<row><entry>=B <emphasis>STRING</emphasis></entry><entry>messages which contain <emphasis>STRING</emphasis> in the whole message. If IMAP is enabled, searches for <emphasis>STRING</emphasis> on the server, rather than downloading each message and searching it locally.</entry></row>
5180
+
<row><entry>~b <emphasis>EXPR</emphasis></entry><entry>messages which contain <emphasis>EXPR</emphasis> in the message body ***)</entry></row>
5181
+
<row><entry>=b <emphasis>STRING</emphasis></entry><entry>If IMAP is enabled, like ~b but searches for <emphasis>STRING</emphasis> on the server, rather than downloading each message and searching it locally.</entry></row>
5182
+
<row><entry>~B <emphasis>EXPR</emphasis></entry><entry>messages which contain <emphasis>EXPR</emphasis> in the whole message ***)</entry></row>
5183
+
<row><entry>=B <emphasis>STRING</emphasis></entry><entry>If IMAP is enabled, like ~B but searches for <emphasis>STRING</emphasis> on the server, rather than downloading each message and searching it locally.</entry></row>
5183
5184
<row><entry>~c <emphasis>EXPR</emphasis></entry><entry>messages carbon-copied to <emphasis>EXPR</emphasis></entry></row>
5184
5185
<row><entry>%c <emphasis>GROUP</emphasis></entry><entry>messages carbon-copied to any member of <emphasis>GROUP</emphasis></entry></row>
5185
5186
<row><entry>~C <emphasis>EXPR</emphasis></entry><entry>messages either to: or cc: <emphasis>EXPR</emphasis></entry></row>
···
5194
5195
<row><entry>%f <emphasis>GROUP</emphasis></entry><entry>messages originating from any member of <emphasis>GROUP</emphasis></entry></row>
5195
5196
<row><entry>~g</entry><entry>cryptographically signed messages</entry></row>
5196
5197
<row><entry>~G</entry><entry>cryptographically encrypted messages</entry></row>
5197
-
<row><entry>~h <emphasis>EXPR</emphasis></entry><entry>messages which contain <emphasis>EXPR</emphasis> in the message header</entry></row>
5198
-
<row><entry>=h <emphasis>STRING</emphasis></entry><entry>messages which contain <emphasis>STRING</emphasis> in the message header. If IMAP is enabled, searches for <emphasis>STRING</emphasis> on the server, rather than downloading each message and searching it locally; <emphasis>STRING</emphasis> must be of the form <quote>header: substring</quote> (see below).</entry></row>
5198
+
<row><entry>~h <emphasis>EXPR</emphasis></entry><entry>messages which contain <emphasis>EXPR</emphasis> in the message header ***)</entry></row>
5199
+
<row><entry>=h <emphasis>STRING</emphasis></entry><entry>If IMAP is enabled, like ~h but searches for <emphasis>STRING</emphasis> on the server, rather than downloading each message and searching it locally; <emphasis>STRING</emphasis> must be of the form <quote>header: substring</quote> (see below).</entry></row>
5199
5200
<row><entry>~H <emphasis>EXPR</emphasis></entry><entry>messages with a spam attribute matching <emphasis>EXPR</emphasis></entry></row>
5200
5201
<row><entry>~i <emphasis>EXPR</emphasis></entry><entry>messages which match <emphasis>EXPR</emphasis> in the <quote>Message-ID</quote> field</entry></row>
5201
5202
<row><entry>~k</entry><entry>messages which contain PGP key material</entry></row>
···
5203
5204
<row><entry>%L <emphasis>GROUP</emphasis></entry><entry>message either originated or received by any member of <emphasis>GROUP</emphasis></entry></row>
5204
5205
<row><entry>~l</entry><entry>messages addressed to a known mailing list</entry></row>
5205
5206
<row><entry>~m [<emphasis>MIN</emphasis>]-[<emphasis>MAX</emphasis>]</entry><entry>messages in the range <emphasis>MIN</emphasis> to <emphasis>MAX</emphasis> *)</entry></row>
5206
-
<row><entry>~M <emphasis>EXPR</emphasis></entry><entry>messages which contain a mime Content-Type matching <emphasis>EXPR</emphasis></entry></row>
5207
+
<row><entry>~M <emphasis>EXPR</emphasis></entry><entry>messages which contain a mime Content-Type matching <emphasis>EXPR</emphasis> ***)</entry></row>
5207
5208
<row><entry>~n [<emphasis>MIN</emphasis>]-[<emphasis>MAX</emphasis>]</entry><entry>messages with a score in the range <emphasis>MIN</emphasis> to <emphasis>MAX</emphasis> *)</entry></row>
5208
5209
<row><entry>~N</entry><entry>new messages</entry></row>
5209
5210
<row><entry>~O</entry><entry>old messages</entry></row>
···
5221
5222
<row><entry>~v</entry><entry>messages part of a collapsed thread.</entry></row>
5222
5223
<row><entry>~V</entry><entry>cryptographically verified messages</entry></row>
5223
5224
<row><entry>~x <emphasis>EXPR</emphasis></entry><entry>messages which contain <emphasis>EXPR</emphasis> in the <quote>References</quote> or <quote>In-Reply-To</quote> field</entry></row>
5224
-
<row><entry>~X [<emphasis>MIN</emphasis>]-[<emphasis>MAX</emphasis>]</entry><entry>messages with <emphasis>MIN</emphasis> to <emphasis>MAX</emphasis> attachments *)</entry></row>
5225
+
<row><entry>~X [<emphasis>MIN</emphasis>]-[<emphasis>MAX</emphasis>]</entry><entry>messages with <emphasis>MIN</emphasis> to <emphasis>MAX</emphasis> attachments *) ***)</entry></row>
5225
5226
<row><entry>~y <emphasis>EXPR</emphasis></entry><entry>messages which contain <emphasis>EXPR</emphasis> in the <quote>X-Label</quote> field</entry></row>
5226
5227
<row><entry>~z [<emphasis>MIN</emphasis>]-[<emphasis>MAX</emphasis>]</entry><entry>messages with a size in the range <emphasis>MIN</emphasis> to <emphasis>MAX</emphasis> *) **)</entry></row>
5227
5228
<row><entry>~=</entry><entry>duplicated messages (see <link linkend="duplicate-threads">$duplicate_threads</link>)</entry></row>
···
5254
5255
<para>
5255
5256
**) The suffixes <quote>K</quote> and <quote>M</quote> are allowed to
5256
5257
specify kilobyte and megabyte respectively.
5258
+
</para>
5259
+
5260
+
<para>
5261
+
***) These patterns read each message in, and can therefore be much
5262
+
slower. Over IMAP this will entail downloading each message. They
5263
+
can not be used for <link linkend="score-command">message
5264
+
scoring</link>, and it is recommended to avoid using them for index
5265
+
coloring.
5257
5266
</para>
5258
5267
5259
5268
<para>
···
5262
5271
one level of backslash (<quote>\</quote>), which is normally used for
5263
5272
quoting. If it is your intention to use a backslash in the regular
5264
5273
expression, you will need to use two backslashes instead
5265
-
(<quote>\\</quote>). You can force Mutt to treat
5274
+
(<quote>\\</quote>).
5275
+
</para>
5276
+
5277
+
<para>
5278
+
You can force Mutt to treat
5266
5279
<emphasis>EXPR</emphasis> as a simple string instead of a regular
5267
5280
expression by using = instead of ~ in the pattern name. For example,
5268
5281
<literal>=b *.*</literal> will find all messages that contain the
5269
5282
literal string <quote>*.*</quote>. Simple string matches are less
5270
-
powerful than regular expressions but can be considerably faster. This
5271
-
is especially true for IMAP folders, because string matches can be
5272
-
performed on the server instead of by fetching every message. IMAP
5273
-
treats <literal>=h</literal> specially: it must be of the form
5274
-
<quote>header: substring</quote> and will not partially match header
5275
-
names. The substring part may be omitted if you simply wish to find
5276
-
messages containing a particular header without regard to its value.
5283
+
powerful than regular expressions but can be considerably faster.
5284
+
</para>
5285
+
5286
+
<para>
5287
+
For IMAP folders, string matches <literal>=b</literal>,
5288
+
<literal>=B</literal>, and <literal>=h</literal> will be performed on
5289
+
the server instead of by fetching every message. IMAP treats
5290
+
<literal>=h</literal> specially: it must be of the form <quote>header:
5291
+
substring</quote> and will not partially match header names. The
5292
+
substring part may be omitted if you simply wish to find messages
5293
+
containing a particular header without regard to its value.
5277
5294
</para>
5278
5295
5279
5296
<para>
+13
-1
doc/muttrc.man.head
+13
-1
doc/muttrc.man.head
···
504
504
messages which contain \fIEXPR\fP in the message body.
505
505
.TP
506
506
=b \fISTRING\fP
507
-
messages which contain \fISTRING\fP in the message body. If IMAP is enabled, searches for \fISTRING\fP on the server, rather than downloading each message and searching it locally.
507
+
If IMAP is enabled, like ~b but searches for \fISTRING\fP on the server, rather than downloading each message and searching it locally.
508
508
.TP
509
509
~B \fIEXPR\fP
510
510
messages which contain \fIEXPR\fP in the whole message.
511
+
.TP
512
+
=B \fISTRING\fP
513
+
If IMAP is enabled, like ~B but searches for \fISTRING\fP on the server, rather than downloading each message and searching it locally.
511
514
.TP
512
515
~c \fIEXPR\fP
513
516
messages carbon-copied to \fIEXPR\fP
···
553
556
.TP
554
557
~h \fIEXPR\fP
555
558
messages which contain \fIEXPR\fP in the message header
559
+
.TP
560
+
=h \fISTRING\fP
561
+
If IMAP is enabled, like ~h but searches for \fISTRING\fP on the server, rather than downloading each message and searching it locally. \fISTRING\fP must be of the form \(lqheader: substring\(rq
556
562
.TP
557
563
~H \fIEXPR\fP
558
564
messages with spam tags matching \fIEXPR\fP
···
663
669
.PP
664
670
With the \fB~z\fP operator, the suffixes \(lqK\(rq and \(lqM\(rq are allowed to specify
665
671
kilobyte and megabyte respectively.
672
+
.PP
673
+
The \fB~b\fP, \fB~B\fP, \fB~h\fP, \fB~M\fP, and \fB~X\fP operators
674
+
require reading each message in, which can be much slower.
675
+
.PP
676
+
You can force Mutt to treat \fIEXPR\fP as a simple string instead of a
677
+
regular expression by using = instead of ~ in the pattern name.
666
678
.SS Matching dates
667
679
.PP
668
680
The \fB~d\fP and \fB~r\fP operators are used to match date ranges,