[Emacs-diffs] /srv/bzr/emacs/trunk r106488: Doc fixes related to rmail-automatic-folder-directives.

[Glenn Morris]

------------------------------------------------------------
revno: 106488
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Wed 2011-11-23 00:29:08 -0800
message:
  Doc fixes related to rmail-automatic-folder-directives.
  
  * mail/rmail.el (rmail-message-filter, rmail-auto-file): Doc fixes.
  (rmail-auto-file): Ignore case in the "special" field names,
  as mail-fetch-field does for all others.
modified:
  lisp/ChangeLog
  lisp/mail/rmail.el

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2011-11-23 07:49:53 +0000
+++ b/lisp/ChangeLog    2011-11-23 08:29:08 +0000
@@ -4,6 +4,10 @@
 
 2011-11-23  Glenn Morris  <address@hidden>
 
+       * mail/rmail.el (rmail-message-filter, rmail-auto-file): Doc fixes.
+       (rmail-auto-file): Ignore case in the "special" field names,
+       as mail-fetch-field does for all others.
+
        * mail/rmail.el (rmail-forward):
        * mail/rmailkwd.el (rmail-set-label):
        * mail/rmailout.el (rmail-output, rmail-output-as-seen)

=== modified file 'lisp/mail/rmail.el'
--- a/lisp/mail/rmail.el        2011-11-23 07:41:17 +0000
+++ b/lisp/mail/rmail.el        2011-11-23 08:29:08 +0000
@@ -495,29 +495,36 @@
                        "23.1")
 
 (defcustom rmail-automatic-folder-directives nil
-  "List of directives specifying where to put a message.
+  "List of directives specifying how to automatically file messages.
+Whenever Rmail shows a message in the folder that `rmail-file-name'
+specifies, it calls `rmail-auto-file' to maybe file the message in
+another folder according to this list.  Messages that are already
+marked as `filed', or are in different folders, are left alone.
+
 Each element of the list is of the form:
 
   (FOLDERNAME FIELD REGEXP [ FIELD REGEXP ] ... )
 
-Where FOLDERNAME is the name of a folder to put the message.
-If any of the field regexp's are nil, then it is ignored.
-
-If FOLDERNAME is \"/dev/null\", it is deleted.
-If FOLDERNAME is nil then it is deleted, and skipped.
-
-FIELD is the plain text name of a field in the message, such as
-\"subject\" or \"from\".  A FIELD of \"to\" will automatically include
-all text from the \"cc\" field as well.
-
-REGEXP is an expression to match in the preceding specified FIELD.
-FIELD/REGEXP pairs continue in the list.
-
-examples:
+FOLDERNAME is the name of a folder in which to put the message.
+If FOLDERNAME is nil then Rmail deletes the message, and moves on to
+the next.  If FOLDERNAME is \"/dev/null\", Rmail deletes the message,
+but does not move to the next.
+
+FIELD is the name of a header field in the message, such as
+\"subject\" or \"from\".  A FIELD of \"to\" includes all text
+from both the \"to\" and \"cc\" headers.
+
+REGEXP is a regular expression to match (case-sensitively) against
+the preceding specified FIELD.
+
+There may be any number of FIELD/REGEXP pairs.
+All pairs must match for a directive to apply to a message.
+For a given message, Rmail applies only the first matching directive.
+
+Examples:
   (\"/dev/null\" \"from\" \"@spam.com\") ; delete all mail from spam.com
   (\"RMS\" \"from\" \"address@hidden") ; save all mail from RMS.
-
-Note that this is only applied in the folder specifed by `rmail-file-name'."
+"
   :group 'rmail
   :version "21.1"
   :type '(repeat (sexp :tag "Directive")))
@@ -2941,8 +2948,11 @@
                        (cons overlay rmail-overlay-list))))))))))
 
 (defun rmail-auto-file ()
-  "Automatically move a message into a sub-folder based on criteria.
-Called when a new message is displayed."
+  "Automatically move a message into another sfolder based on criteria.
+This moves messages according to `rmail-automatic-folder-directives'.
+It only does something in the folder that `rmail-file-name' specifies.
+The function `rmail-show-message' calls this whenever it shows a message.
+This leaves a message alone if it already has the `filed' attribute."
   (if (or (zerop rmail-total-messages)
          (rmail-message-attr-p rmail-current-message "...F")
          (not (string= (buffer-file-name)
@@ -2962,10 +2972,14 @@
              directive-loop (cdr (car d)))
        (while (and (car directive-loop)
                    (let ((f (cond
-                             ((string= (car directive-loop) "from") from)
-                             ((string= (car directive-loop) "to") to)
-                             ((string= (car directive-loop) "subject") subj)
+                             ((string= (downcase (car directive-loop)) "from")
+                              from)
+                             ((string= (downcase (car directive-loop)) "to")
+                              to)
+                             ((string= (downcase (car directive-loop))
+                                       "subject") subj)
                              (t (mail-fetch-field (car directive-loop))))))
+                     ;; FIXME - shouldn't this ignore case?
                      (and f (string-match (car (cdr directive-loop)) f))))
          (setq directive-loop (cdr (cdr directive-loop))))
        ;; If there are no directives left, then it was a complete match.