* lisp/mail/rmail.el (rmail-message-filter): Mark as obsolete.

* etc/NEWS: Mention this.

Fixes: debbugs:2624

etc/NEWS

@@ -725,6 +725,11 @@ more variants, including Mercury, and a lot more.
 *** The command `rmail-epa-decrypt' decrypts OpenPGP data
 in the Rmail incoming message.
 
+---
+*** The variable `rmail-message-filter' no longer has any effect.
+This change was made in Emacs 23.1 but was not advertised at the time.
+Try using `rmail-show-message-hook' instead.
+
 ** Shell mode
 
 *** Shell mode uses pcomplete rules, with the standard completion UI.

lisp/ChangeLog

@@ -1,3 +1,7 @@
+2011-11-23  Glenn Morris  <rgm@gnu.org>
+
+	* mail/rmail.el (rmail-message-filter): Mark as obsolete.  (Bug#2624)
+
 2011-11-22  Stefan Monnier  <monnier@iro.umontreal.ca>
 
 	* server.el (server-eval-and-print): Allow C-g (bug#6585).

lisp/mail/rmail.el

@@ -482,6 +482,7 @@ still the current message in the Rmail buffer.")
 ;; It's not clear what it should do now, since there is nothing that
 ;; records when a message is shown for the first time (unseen is not
 ;; necessarily the same thing).
+;; See http://lists.gnu.org/archive/html/emacs-devel/2009-03/msg00013.html
 (defcustom rmail-message-filter nil
   "If non-nil, a filter function for new messages in RMAIL.
 Called with region narrowed to the message, including headers,
@@ -489,6 +490,10 @@ before obeying `rmail-ignored-headers'."
   :group 'rmail-headers
   :type '(choice (const nil) function))
 
+(make-obsolete-variable 'rmail-message-filter
+			"it is not used (try `rmail-show-message-hook')."
+			"23.1")
+
 (defcustom rmail-automatic-folder-directives nil
   "List of directives specifying where to put a message.
 Each element of the list is of the form: