# HG changeset patch
# User Stephen J. Turnbull <stephen@xemacs.org>
# Date 1304136287 -32400
# Node ID d12a0c55b174ddddcf806c7025335e75acdbf93e
# Parent  156c1a62a82d7223e3d92f4621732f6850bc146b
[mq]: matchspec

diff -r 156c1a62a82d -r d12a0c55b174 CHANGES-beta
--- a/CHANGES-beta	Sat Apr 30 12:57:04 2011 +0900
+++ b/CHANGES-beta	Sat Apr 30 13:04:47 2011 +0900
@@ -1,5 +1,17 @@
 # DO NOT PUT A VERSION MARKER HERE, ADDED AT RELEASE
 
+Major Features and Backward Incompatible Changes
+User-Visible Bug Fixes and Minor Improvements
+
+-- improve: Backward-compatible MATCHSPEC in face-property-matching-instance. -- Stephen Turnbull
+
+Build Infrastructure and Source Tree
+Documentation
+Lisp API
+Internal API and Implementation
+Testing and Debugging
+
+
 to XEmacs 21.5.31 "ginger"
 
 Major Features and Backward Incompatible Changes
diff -r 156c1a62a82d -r d12a0c55b174 lisp/ChangeLog
--- a/lisp/ChangeLog	Sat Apr 30 12:57:04 2011 +0900
+++ b/lisp/ChangeLog	Sat Apr 30 13:04:47 2011 +0900
@@ -2,6 +2,11 @@
 
 	* XEmacs 21.5.31 "ginger" is released.
 
+2011-04-30  Stephen J. Turnbull  <stephen@xemacs.org>
+
+	* faces.el (face-property-matching-instance):
+	Allow backward compatibility to the 21.4 API.  Update docstring.
+
 2011-04-26  Stephen J. Turnbull  <stephen@xemacs.org>
 
 	* XEmacs 21.5.30 "garlic" is released.
diff -r 156c1a62a82d -r d12a0c55b174 lisp/faces.el
--- a/lisp/faces.el	Sat Apr 30 12:57:04 2011 +0900
+++ b/lisp/faces.el	Sat Apr 30 13:04:47 2011 +0900
@@ -238,16 +238,19 @@
 					&optional domain default
 					no-fallback)
   "Return the instance of FACE's PROPERTY matching MATCHSPEC in DOMAIN.
-Currently the only useful value for MATCHSPEC is a charset, when used
-in conjunction with the face's font; this allows you to retrieve a
-font that can be used to display a particular charset, rather than just
-any font.
+Currently MATCHSPEC is used only for the 'font property, when its value
+should be a cons \(CHARSET . STAGE) \(see `specifier-matching-instance'
+for a full description of the matching process).  This allows you to
+retrieve a font that can be used to display a particular charset, rather
+than just any font.  For backward compatibility, MATCHSPEC may be a
+charset, which is interpreted as \(CHARSET . final).
 
-Other than MATCHSPEC, this function is identical to `face-property-instance'.
-See also `specifier-matching-instance' for a fuller description of the
-matching process."
+See `face-property-instance' for usage of the other arguments."
 
   (setq face (get-face face))
+  ;; For compatibility with 21.4-oriented code, eg, x-symbol-mule.el.
+  (when (charsetp matchspec)
+    (setq matchspec (cons matchspec 'final)))
   (let ((value (get face property)))
     (when (specifierp value)
       (setq value (specifier-matching-instance value matchspec domain
diff -r 156c1a62a82d -r d12a0c55b174 src/ChangeLog
--- a/src/ChangeLog	Sat Apr 30 12:57:04 2011 +0900
+++ b/src/ChangeLog	Sat Apr 30 13:04:47 2011 +0900
@@ -2,6 +2,11 @@
 
 	* XEmacs 21.5.31 "ginger" is released.
 
+2011-04-30  Stephen J. Turnbull  <stephen@xemacs.org>
+
+	* specifier.c (Fspecifier_matching_instance):
+	Add comment about backward-incompatibility of MATCHSPEC.
+
 2011-04-26  Stephen J. Turnbull  <stephen@xemacs.org>
 
 	* XEmacs 21.5.30 "garlic" is released.
diff -r 156c1a62a82d -r d12a0c55b174 src/specifier.c
--- a/src/specifier.c	Sat Apr 30 12:57:04 2011 +0900
+++ b/src/specifier.c	Sat Apr 30 13:04:47 2011 +0900
@@ -3171,6 +3171,10 @@
 				 no_fallback, 1);
 }
 
+/* MATCHSPEC is backward-incompatible with code written to 21.4's API.
+   So far such code has been seen only in x-symbol-mule.el, and that
+   was addressed by a change `face-property-matching-instance'.
+   See tracker issue752 for a more general patch against 21.5.29. */
 DEFUN ("specifier-matching-instance", Fspecifier_matching_instance, 2, 5, 0, /*
 Return an instance for SPECIFIER in DOMAIN that matches MATCHSPEC.
 If no instance can be generated for this domain, return DEFAULT.