Add note about message scoring and thread patterns. (see #3947)

Because scoring occurs before the mailbox is sorted, thread patterns
don't work.  Document a suggested workaround of pushing the score
command in a folder hook.

Also, fix the link target for the score command synopsis.

diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index 2895481110f8ab304b6835b2ebc6eaea43bb9917..db74e8ac561f1be48b213e5bad2a6be4dae0af79 100644 (file)
--- a/doc/manual.xml.head
+++ b/doc/manual.xml.head
@@ -3862,6 +3862,20 @@ pattern <quote>*</quote> is a special token which means to clear the
 list of all score entries.
 </para>
 
+<para>
+Scoring occurs as the messages are read in, before the mailbox is
+sorted.  Because of this, patterns which depend on threading, such as
+<emphasis>~=</emphasis>, <emphasis>~$</emphasis>, and
+<emphasis>~()</emphasis>, will not work by default.  A workaround is
+to push the scoring command in a folder hook.  This will cause the
+mailbox to be rescored after it is opened and input starts being
+processed:
+</para>
+
+<screen>
+folder-hook . 'push "&lt;enter-command&gt;score ~= 10&lt;enter&gt;"'
+</screen>
+
 </sect1>
 
 <sect1 id="spam">
@@ -9910,7 +9924,7 @@ The following are the commands understood by Mutt:
 
 <listitem>
 <cmdsynopsis>
-<command><link linkend="score">score</link></command>
+<command><link linkend="score-command">score</link></command>
 <arg choice="plain">
 <replaceable class="parameter">pattern</replaceable>
 </arg>
@@ -9918,7 +9932,7 @@ The following are the commands understood by Mutt:
 <replaceable class="parameter">value</replaceable>
 </arg>
 
-<command><link linkend="score">unscore</link></command>
+<command><link linkend="score-command">unscore</link></command>
 <group choice="req">
 <arg choice="plain">
 <replaceable class="parameter">*</replaceable>