From d2c966a84866d1fb91f694a46e2b75856b1859b0 Mon Sep 17 00:00:00 2001
From: Kevin McCarthy <kevin@8t8.us>
Date: Wed, 31 May 2017 16:18:29 -0700
Subject: [PATCH] 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.
---
 doc/manual.xml.head | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index 224e98ae1..e90b0d331 100644
--- a/doc/manual.xml.head
+++ b/doc/manual.xml.head
@@ -5066,6 +5066,17 @@ message-hook '~f freshmeat-news' 'set pager="less \"+/^  subject: .*\""'
       <command>score</command>command for it to be removed. The 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">
@@ -15962,7 +15973,7 @@ folder-hook ^pop 'set read_inc=1'</screen>
         <listitem>
           <cmdsynopsis>
             <command>
-              <link linkend="score">score</link>
+              <link linkend="score-command">score</link>
             </command>
             <arg choice="plain">
               <replaceable class="parameter">pattern</replaceable>
@@ -15971,7 +15982,7 @@ folder-hook ^pop 'set read_inc=1'</screen>
               <replaceable class="parameter">value</replaceable>
             </arg>
             <command>
-              <link linkend="score">unscore</link>
+              <link linkend="score-command">unscore</link>
             </command>
             <group choice="req">
               <arg choice="plain">
-- 
2.40.0