Doc improvements for face remapping.

* face-remap.el (face-remap-add-relative, face-remap-set-base)
(buffer-face-set, buffer-face-toggle, buffer-face-mode-invoke):
Doc fixes.

* doc/lispref/display.texi (Face Remapping): Minor clarification.

* doc/lispref/text.texi (Special Properties): Clarify the meaning of a
list of faces in the `face' property.

Fixes: debbugs:11225

3 files changed, 28 insertions, 22 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 3c9f26d6a24..cbe081ca6b4 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,10 @@
+2012-06-09  Chong Yidong  <cyd@gnu.org>
+
+        * text.texi (Special Properties): Clarify the meaning of a list of
+        faces in the `face' property.
+
+        * display.texi (Face Remapping): Minor clarification.
+
 2012-06-08  Chong Yidong  <cyd@gnu.org>
 
         * display.texi (Face Attributes): Font family does not accept
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 53e800bfbf0..3725b6fd820 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2511,39 +2511,34 @@ Scale,,, emacs, The GNU Emacs Manual}).
 The value of this variable is an alist whose elements have the form
 @code{(@var{face} . @var{remapping})}.  This causes Emacs to display
 any text having the face @var{face} with @var{remapping}, rather than
-the ordinary definition of @var{face}.  @var{remapping} may be any
-face specification suitable for a @code{face} text property: either a
-face name, or a property list of attribute/value pairs, or a list in
-which each element is either a face name or a property list
-(@pxref{Special Properties}).
+the ordinary definition of @var{face}.
+
+@var{remapping} may be any face specification suitable for a
+@code{face} text property: either a face (i.e.@: a face name or a
+property list of attribute/value pairs), or a list of faces.  For
+details, see the description of the @code{face} text property in
+@ref{Special Properties}.  @var{remapping} serves as the complete
+specification for the remapped face---it replaces the normal
+definition of @var{face}, instead of modifying it.
 
 If @code{face-remapping-alist} is buffer-local, its local value takes
 effect only within that buffer.
 
-Two points bear emphasizing:
-
-@enumerate
-@item
-@var{remapping} serves as the complete specification for the remapped
-face---it replaces the normal definition of @var{face}, instead of
-modifying it.
-
-@item
-If @var{remapping} references the same face name @var{face}, either
-directly or via the @code{:inherit} attribute of some other face in
-@var{remapping}, that reference uses the normal definition of
-@var{face}.  In other words, the remapping cannot be recursive.
+Note: face remapping is non-recursive.  If @var{remapping} references
+the same face name @var{face}, either directly or via the
+@code{:inherit} attribute of some other face in @var{remapping}, that
+reference uses the normal definition of @var{face}.  For instance, if
+the @code{mode-line} face is remapped using this entry in
+@code{face-remapping-alist}:
 
-For instance, if the @code{mode-line} face is remapped using this
-entry in @code{face-remapping-alist}:
 @example
 (mode-line italic mode-line)
 @end example
+
 @noindent
 then the new definition of the @code{mode-line} face inherits from the
 @code{italic} face, and the @emph{normal} (non-remapped) definition of
 @code{mode-line} face.
-@end enumerate
 @end defvar
 
   The following functions implement a higher-level interface to
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index e2bdc707c5b..63a6d2cbab3 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -3004,7 +3004,11 @@ time you want to specify a particular attribute for certain text.
 @xref{Face Attributes}.
 
 @item
-A list, where each element uses one of the two forms listed above.
+A list of faces.  This specifies a face which is an aggregate of the
+attributes of each of the listed faces.  Faces occurring earlier in
+the list have higher priority.  Each list element must have one of the
+two above forms (i.e.@: either a face name or a property list of face
+attributes).
 @end itemize
 
 Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by