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.

diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index 4be247820eb530ff1082485dfbb15af91f2a6bcb..467df72f7f4f982659b9638b07b7504b9f2f47c6 100644 (file)
--- a/doc/manual.xml.head
+++ b/doc/manual.xml.head
@@ -5700,9 +5700,9 @@ message-hook '~f freshmeat-news' 'set pager="less \"+/^  subject: .*\""'
         <link linkend="patterns">patterns</link> section (note: For efficiency
         reasons, patterns which scan information not available in the index,
         such as <literal>~b</literal>, <literal>~B</literal>,
-        <literal>~h</literal>, or <literal>~X</literal> may not be used).
-        <emphasis>value</emphasis> is a positive or negative integer.
-        A message's final score is the sum total of all matching
+        <literal>~h</literal>, <literal>~M</literal>, or <literal>~X</literal>
+        may not be used).  <emphasis>value</emphasis> is a positive or negative
+        integer. A message's final score is the sum total of all matching
         <command>score</command> entries. However, you may optionally prefix
         <emphasis>value</emphasis> with an equal sign (<quote>=</quote>) to
         cause evaluation to stop at a particular entry if there is a match.
@@ -7099,14 +7099,13 @@ set index_format="%4C %Z %{%b %d} %-15.15L (%?l?%4l&amp;%4c?)%*  %s"
                 <entry>~b <emphasis>EXPR</emphasis></entry>
                 <entry>
                   messages which contain <emphasis>EXPR</emphasis> in the
-                  message body
+                  message body ***)
                 </entry>
               </row>
               <row>
                 <entry>=b <emphasis>STRING</emphasis></entry>
                 <entry>
-                  messages which contain <emphasis>STRING</emphasis> in the
-                  message body. If IMAP is enabled, searches for
+                  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>
@@ -7114,16 +7113,15 @@ set index_format="%4C %Z %{%b %d} %-15.15L (%?l?%4l&amp;%4c?)%*  %s"
               <row>
                 <entry>~B <emphasis>EXPR</emphasis></entry>
                 <entry>
-                  messages which contain <emphasis>EXPR</emphasis> in the whole
-                  message
+                  messages which contain <emphasis>EXPR</emphasis>in the whole
+                  message ***)
                 </entry>
               </row>
               <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
+                  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>
@@ -7219,19 +7217,18 @@ set index_format="%4C %Z %{%b %d} %-15.15L (%?l?%4l&amp;%4c?)%*  %s"
               <row>
                 <entry>~h <emphasis>EXPR</emphasis></entry>
                 <entry>
-                  messages which contain <emphasis>EXPR</emphasis> in the
-                  message header
+                   messages which contain <emphasis>EXPR</emphasis>in the
+                   message header ***)
                 </entry>
               </row>
               <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).
+                   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>
               <row>
@@ -7310,8 +7307,8 @@ set index_format="%4C %Z %{%b %d} %-15.15L (%?l?%4l&amp;%4c?)%*  %s"
               <row>
                 <entry>~M <emphasis>EXPR</emphasis></entry>
                 <entry>
-                  messages which contain a mime Content-Type matching 
-                  <emphasis>EXPR</emphasis>
+                   messages which contain a mime Content-Type matching
+                   <emphasis>EXPR</emphasis>****)
                 </entry>
               </row>
               <row>
@@ -7421,10 +7418,10 @@ set index_format="%4C %Z %{%b %d} %-15.15L (%?l?%4l&amp;%4c?)%*  %s"
                 </entry>
               </row>
               <row>
-                <entry>~X [<emphasis>MIN</emphasis>]-[<emphasis>MAX</emphasis>]</entry>
+                <entry>~X [ <emphasis>MIN</emphasis>]-[ <emphasis>MAX</emphasis>]</entry>
                 <entry>
-                  messages with <emphasis>MIN</emphasis> to
-                  <emphasis>MAX</emphasis> attachments&#160;*)
+                   messages with <emphasis>MIN</emphasis>to
+                   <emphasis>MAX</emphasis>attachments *) ****)
                 </entry>
               </row>
               <row>
@@ -7518,21 +7515,33 @@ set index_format="%4C %Z %{%b %d} %-15.15L (%?l?%4l&amp;%4c?)%*  %s"
           are even more general and powerful than the other types of ranges.
           Read on and see <xref linkend="message-ranges" /> below.
         </para>
+        <para>
+          ****) These patterns read each message in, and can therefore be much
+          slower.  Over IMAP this will entail downloading each message.  They
+          can not be used for <link linkend="score-command">message scoring</link>,
+          and it is recommended to avoid using them for index coloring.
+        </para>
         <para>
           Special attention has to be paid when using regular expressions
           inside of patterns. Specifically, NeoMutt's parser for these patterns
           will strip one level of backslash (<quote>\</quote>), which is
           normally used for quoting. If it is your intention to use a backslash
           in the regular expression, you will need to use two backslashes
-          instead (<quote>\\</quote>). You can force NeoMutt to treat
+          instead (<quote>\\</quote>).
+        </para>
+        <para>
+          You can force NeoMutt to treat
           <emphasis>EXPR</emphasis> as a simple substring instead of a regular
           expression by using = instead of ~ in the pattern name. For example,
           <literal>=b *.*</literal> will find all messages that contain the
           literal string <quote>*.*</quote>. Simple string matches are less
           powerful than regular expressions but can be considerably faster.
-          This is especially true for IMAP folders, because string matches can
-          be performed on the server instead of by fetching every message. IMAP
-          treats <literal>=h</literal> specially: it must be of the form
+        </para>
+        <para>
+          For IMAP folders, string matches <literal>=b</literal>,
+          <literal>=B</literal>, and <literal>=h</literal> will be performed on
+          the server instead of by fetching every message. IMAP treats
+          <literal>=h</literal> specially: it must be of the form
           <quote>header: substring</quote> and will not partially match header
           names. The substring part may be omitted if you simply wish to find
           messages containing a particular header without regard to its value.