User docs: Warn about order of filters. Fixes bug #602906

2 files changed, 20 insertions, 16 deletions

diff --git a/help/C/mail-filters-not-working.page b/help/C/mail-filters-not-working.page
index ed262f2eed..4923f417c0 100644
--- a/help/C/mail-filters-not-working.page
+++ b/help/C/mail-filters-not-working.page
@@ -7,11 +7,15 @@
     <link type="guide" xref="index#common-mail-problems" />
     <link type="seealso" xref="mail-filters" />
 
-    <revision pkgversion="2.28.3" version="0.1" date="2011-07-21" status="draft"/>
+    <revision pkgversion="3.1.5" version="0.2" date="2011-08-25" status="draft"/>
     <credit type="author">
       <name>April Gonzales</name>
       <email>loonycookie@gmail.com</email>
     </credit>
+    <credit type="author">
+      <name>Andre Klapper</name>
+      <email>ak-47@gmx.net</email>
+    </credit>
     <license>
       <p>Creative Commons Share Alike 3.0</p>
     </license>    
@@ -21,16 +25,12 @@
 <title>Mail filters are not working</title>
 <p>Your mail filters are probably working, however, they could be ordered in an inefficient way. This will make your filters run slowly, so it may seem like they are not working.</p>
 
-<p>The order of email filters is very important. If your first filter has a <gui>Stop Processing</gui> rule, then all the email messages that match this filter will ignore all the succeeding filters.</p> 
-
-<p>To check if a filter has a <gui>Stop Processing</gui> rule:</p>
-
-<steps>
-<item><p>Go to <guiseq><gui>Edit</gui><gui>Message Filters</gui></guiseq>.</p></item>
-<item><p>Select the filter and refer to the list of actions for that particular filter. </p></item>
-<item><p>The <gui>Stop Processing</gui> rule should be listed under the list of <gui>Actions</gui> if it is enabled.</p></item>
-</steps>
-
+<note>
+<p>Note that the order of filters is very important. They are applied to the original message in sequence, like a recipe.</p>
+<p>If your first filter has a <gui>Stop Processing</gui> rule, then all the email messages that match this filter will ignore all the succeeding filters.</p>
+<p>When you move a message to another folder, "moving" actually means appending a copy of the message to the destination folder and marking the original message for deletion. So any subsequent filter rules will be applied to the original message that is now marked for deletion. Therefore moving a message should usually appear last in a sequence of filter rules.</p>
+<p>To check the rules and their order of an existing filter, review its actions in the <gui>Then</gui> section by <link xref="mail-filters#editing">editing the filter</link>.</p>
+</note>
 
 <p>Another thing you have to keep in mind is that filters depend on the "new" flag that is set when a particular email message is initially fetched from the server. If you use another email client aside from Evolution, your filters may not work automatically.</p>
 
@@ -41,6 +41,3 @@
 </note>
 
 </page>
-
-
-
diff --git a/help/C/mail-filters.page b/help/C/mail-filters.page
index e8d902e494..a22768dca6 100644
--- a/help/C/mail-filters.page
+++ b/help/C/mail-filters.page
@@ -6,7 +6,7 @@
 
     <link type="guide" xref="mail-organizing"/>
 
-    <revision pkgversion="3.0.2" version="0.4" date="2011-07-30" status="final"/>
+    <revision pkgversion="3.0.2" version="0.5" date="2011-08-25" status="final"/>
     <credit type="author">
       <name>Andre Klapper</name>
       <email>ak-47@gmx.net</email>
@@ -38,7 +38,14 @@
 <item><p>Enter a name in the <gui>Rule name</gui> field.</p></item>
 <item><p>Define the conditions for the rule. For each condition, you first select which part of the message will be checked and then define the comparison.</p><p>For more information on the available conditions see <link xref="mail-filters-conditions">Available Filter conditions</link>.</p></item>
 <item><p>If you want to define multiple conditions, define under <gui>Find items</gui> if any or if all conditions have to apply, and click <gui style="button">Add Condition</gui> and repeat the previous step.</p></item>
-<item><p>Select the Actions for the Filter in the <gui>Then</gui> section.</p><p>For more information on the available actions see <link xref="mail-filters-actions">Available Filter actions</link>.</p></item>
+<item>
+<p>Select the Actions for the Filter in the <gui>Then</gui> section.</p><p>For more information on the available actions see <link xref="mail-filters-actions">Available Filter actions</link>.</p>
+<note>
+<p>Note that the order of filters is very important. They are applied to the original message in sequence, like a recipe.</p>
+<p>If your first filter has a <gui>Stop Processing</gui> rule, then all the email messages that match this filter will ignore all the succeeding filters.</p>
+<p>When you move a message to another folder, "moving" actually means appending a copy of the message to the destination folder and marking the original message for deletion. So any subsequent filter rules will be applied to the original message that is now marked for deletion. Therefore moving a message should usually appear last in a sequence of filter rules.</p>
+</note>
+</item>
 <item><p>If you want to define multiple actions, click <gui style="button">Add Action</gui> and repeat the previous step. For example, if you want no other existing filters to be applied choose <gui>Stop Processing</gui> as the second action in the list.</p></item>
 <item><p>Click <gui style="button">OK</gui>.</p></item>
 </steps>