Updates to Display chapter of Lisp manual.

* doc/lispref/display.texi (The Echo Area): Add xref to Output Streams.
(Displaying Messages): Improve doc of message.
(Echo Area Customization, Invisible Text): Copyedits.
(Invisible Text): Mention that spec comparison is done with eq.
(Width): Improve doc of char-width.
(Faces): Recommend using symbol instead of string for face name.
Minor clarifications.
(Defining Faces): Copyedits.  Update face example.
(Attribute Functions): Mark set-face-foreground etc as commands.
(Face Remapping): Mention text-scale-adjust.  Clarify
face-remapping-alist and related docs.
(Face Functions): Don't document make-face or copy-face.

* lisp/faces.el (make-face, make-empty-face, copy-face):
* lisp/face-remap.el (face-remap-add-relative, face-remap-set-base):
Doc fixes.

* src/xfaces.c (Vface_remapping_alist): Doc fix.

8 files changed, 276 insertions, 283 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 43ae349cb4c..77468f562c6 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,18 @@
+2012-03-21  Chong Yidong  <cyd@gnu.org>
+
+        * display.texi (The Echo Area): Add xref to Output Streams.
+        (Displaying Messages): Improve doc of message.
+        (Echo Area Customization, Invisible Text): Copyedits.
+        (Invisible Text): Mention that spec comparison is done with eq.
+        (Width): Improve doc of char-width.
+        (Faces): Recommend using symbol instead of string for face name.
+        Minor clarifications.
+        (Defining Faces): Copyedits.  Update face example.
+        (Attribute Functions): Mark set-face-foreground etc as commands.
+        (Face Remapping): Mention text-scale-adjust.  Clarify
+        face-remapping-alist and related docs.
+        (Face Functions): Don't document make-face or copy-face.
+
 2012-03-20  Chong Yidong  <cyd@gnu.org>
 
         * display.texi (Forcing Redisplay): Various rewrites to reflect
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index b68b0697936..dbcc1d1190b 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -243,14 +243,12 @@ This variable is automatically buffer-local in every buffer.
 (@pxref{Errors}), for messages made with the @code{message} primitive,
 and for echoing keystrokes.  It is not the same as the minibuffer,
 despite the fact that the minibuffer appears (when active) in the same
-place on the screen as the echo area.  The @cite{GNU Emacs Manual}
-specifies the rules for resolving conflicts between the echo area and
-the minibuffer for use of that screen space (@pxref{Minibuffer,, The
-Minibuffer, emacs, The GNU Emacs Manual}).
+place on the screen as the echo area.  @xref{Minibuffer,, The
+Minibuffer, emacs, The GNU Emacs Manual}.
 
-  You can write output in the echo area by using the Lisp printing
-functions with @code{t} as the stream (@pxref{Output Functions}), or
-explicitly.
+  Apart from the functions documented in this section, you can print
+Lisp objects to the echo area by specifying @code{t} as the output
+stream.  @xref{Output Streams}.
 
 @menu
 * Displaying Messages:: Explicitly displaying text in the echo area.
@@ -263,27 +261,26 @@ explicitly.
 @subsection Displaying Messages in the Echo Area
 @cindex display message in echo area
 
-  This section describes the functions for explicitly producing echo
-area messages.  Many other Emacs features display messages there, too.
+  This section describes the standard functions for displaying
+messages in the echo area.
 
 @defun message format-string &rest arguments
-This function displays a message in the echo area.  The argument
-@var{format-string} is similar to a C language @code{printf} format
-string.  See @code{format} in @ref{Formatting Strings}, for the details
-on the conversion specifications.  @code{message} returns the
-constructed string.
+This function displays a message in the echo area.
+@var{format-string} is a format string, and @var{arguments} are the
+objects for its format specifications, like in the @code{format}
+function (@pxref{Formatting Strings}).  The resulting formatted string
+is displayed in the echo area; if it contains @code{face} text
+properties, it is displayed with the specified faces (@pxref{Faces}).
+The string is also added to the @samp{*Messages*} buffer, but without
+text properties (@pxref{Logging Messages}).
+
+In batch mode, the message is printed to the standard error stream,
+followed by a newline.
 
-In batch mode, @code{message} prints the message text on the standard
-error stream, followed by a newline.
-
-If @var{format-string}, or strings among the @var{arguments}, have
-@code{face} text properties, these affect the way the message is displayed.
-
-@c Emacs 19 feature
 If @var{format-string} is @code{nil} or the empty string,
 @code{message} clears the echo area; if the echo area has been
-expanded automatically, this brings it back to its normal size.
-If the minibuffer is active, this brings the minibuffer contents back
+expanded automatically, this brings it back to its normal size.  If
+the minibuffer is active, this brings the minibuffer contents back
 onto the screen immediately.
 
 @example
@@ -559,13 +556,13 @@ If the value is zero, then command input is not echoed.
 Normally, displaying a long message resizes the echo area to display
 the entire message.  But if the variable @code{message-truncate-lines}
 is non-@code{nil}, the echo area does not resize, and the message is
-truncated to fit it, as in Emacs 20 and before.
+truncated to fit it.
 @end defvar
 
   The variable @code{max-mini-window-height}, which specifies the
 maximum height for resizing minibuffer windows, also applies to the
-echo area (which is really a special use of the minibuffer window.
-@xref{Minibuffer Misc}.).
+echo area (which is really a special use of the minibuffer window;
+@pxref{Minibuffer Misc}).
 
 @node Warnings
 @section Reporting Warnings
@@ -762,10 +759,11 @@ that warning is not logged.
 @cindex invisible text
 You can make characters @dfn{invisible}, so that they do not appear on
 the screen, with the @code{invisible} property.  This can be either a
-text property (@pxref{Text Properties}) or a property of an overlay
+text property (@pxref{Text Properties}) or an overlay property
 (@pxref{Overlays}).  Cursor motion also partly ignores these
-characters; if the command loop finds point within them, it moves
-point to the other side of them.
+characters; if the command loop finds that point is inside a range of
+invisible text after a command, it relocates point to the other side
+of the text.
 
 In the simplest case, any non-@code{nil} @code{invisible} property makes
 a character invisible.  This is the default case---if you don't alter
@@ -805,13 +803,15 @@ the character is invisible.  The list can have two kinds of elements:
 
 @table @code
 @item @var{atom}
-A character is invisible if its @code{invisible} property value
-is @var{atom} or if it is a list with @var{atom} as a member.
+A character is invisible if its @code{invisible} property value is
+@var{atom} or if it is a list with @var{atom} as a member; comparison
+is done with @code{eq}.
 
 @item (@var{atom} . t)
 A character is invisible if its @code{invisible} property value is
-@var{atom} or if it is a list with @var{atom} as a member.  Moreover,
-a sequence of such characters displays as an ellipsis.
+@var{atom} or if it is a list with @var{atom} as a member; comparison
+is done with @code{eq}.  Moreover, a sequence of such characters
+displays as an ellipsis.
 @end table
 @end table
 @end defvar
@@ -846,7 +846,7 @@ major mode should use the mode's own name as an element of
 (overlay-put (make-overlay beginning end)
              'invisible 'my-symbol)
 
-;; @r{When done with the overlays:}
+;; @r{When done with the invisibility:}
 (remove-from-invisibility-spec '(my-symbol . t))
 ;; @r{Or respectively:}
 (remove-from-invisibility-spec 'my-symbol)
@@ -872,15 +872,16 @@ ignore invisible newlines if @code{line-move-ignore-invisible} is
 non-@code{nil} (the default), but only because they are explicitly
 programmed to do so.
 
-  However, if a command ends with point inside or at the boundary of invisible
-text, the main editing loop moves point to one of the two ends of the invisible
-text.  Which end to move to is chosen based on the following factors: make sure
-that the overall movement of the command is still in the same direction, and
-prefer a position where an inserted char would not inherit the @code{invisible}
-property.  Additionally, if the text is not replaced by an ellipsis and the
-command only moved within the invisible text, then point is moved one extra
-character so as to try and reflect the command's movement by a visible movement
-of the cursor.
+  However, if a command ends with point inside or at the boundary of
+invisible text, the main editing loop relocates point to one of the
+two ends of the invisible text.  Emacs chooses the direction of
+relocation so that it is the same as the overall movement direction of
+the command; if in doubt, it prefers a position where an inserted char
+would not inherit the @code{invisible} property.  Additionally, if the
+text is not replaced by an ellipsis and the command only moved within
+the invisible text, then point is moved one extra character so as to
+try and reflect the command's movement by a visible movement of the
+cursor.
 
   Thus, if the command moved point back to an invisible range (with the usual
 stickiness), Emacs moves point back to the beginning of that range.  If the
@@ -1666,8 +1667,11 @@ check the width of a character.  @xref{Primitive Indent}, and
 @ref{Screen Lines}, for related functions.
 
 @defun char-width char
-This function returns the width in columns of the character @var{char},
-if it were displayed in the current buffer and the selected window.
+This function returns the width in columns of the character
+@var{char}, if it were displayed in the current buffer (i.e.@: taking
+into account the buffer's display table, if any; @pxref{Display
+Tables}).  The width of a tab character is usually @code{tab-width}
+(@pxref{Usual Display}).
 @end defun
 
 @defun string-width string
@@ -1813,26 +1817,27 @@ height.
 @section Faces
 @cindex faces
 
-  A @dfn{face} is a collection of graphical attributes for displaying
-text: font, foreground color, background color, optional underlining,
-and so on.  Faces control how buffer text is displayed, and how some
-parts of the frame, such as the mode-line, are displayed.
+  A @dfn{face} is a collection of graphical @dfn{attributes} for
+displaying text: font, foreground color, background color, optional
+underlining, and so on.  Faces control how Emacs displays text in
+buffers, as well as other parts of the frame such as the mode line.
 @xref{Standard Faces,,, emacs, The GNU Emacs Manual}, for the list of
 faces Emacs normally comes with.
 
 @cindex face id
   For most purposes, you refer to a face in Lisp programs using its
-@dfn{face name}.  This is either a string or (equivalently) a Lisp
-symbol whose name is equal to that string.
+@dfn{face name}, which is usually a Lisp symbol.  For backward
+compatibility, a face name can also be a string, which is equivalent
+to a Lisp symbol of the same name.
 
 @defun facep object
 This function returns a non-@code{nil} value if @var{object} is a Lisp
 symbol or string that names a face.  Otherwise, it returns @code{nil}.
 @end defun
 
-  Each face name is meaningful for all frames, and by default it has
-the same meaning in all frames.  But you can arrange to give a
-particular face name a special meaning in one frame if you wish.
+  By default, each face name corresponds to the same set of attributes
+in all frames.  But you can also assign a face name a special set of
+attributes in one frame (@pxref{Attribute Functions}).
 
 @menu
 * Defining Faces::      How to define a face with @code{defface}.
@@ -1855,9 +1860,8 @@ particular face name a special meaning in one frame if you wish.
 @subsection Defining Faces
 
   The way to define a new face is with @code{defface}.  This creates a
-kind of customization item (@pxref{Customization}) which the user can
-customize using the Customization buffer (@pxref{Easy Customization,,,
-emacs, The GNU Emacs Manual}).
+kind of customization item which the user can customize using the
+Customization buffer (@pxref{Customization}).
 
   People are sometimes tempted to create variables whose values specify
 which faces to use (for example, Font-Lock does this).  In the vast
@@ -1883,14 +1887,16 @@ exactly what the @code{defface} says.
 
 The purpose of @var{spec} is to specify how the face should appear on
 different kinds of terminals.  It should be an alist whose elements
-have the form @code{(@var{display} @var{atts})}.  Each element's
-@sc{car}, @var{display}, specifies a class of terminals.  (The first
-element, if its @sc{car} is @code{default}, is special---it specifies
-defaults for the remaining elements).  The element's @sc{cadr},
-@var{atts}, is a list of face attributes and their values; it
-specifies what the face should look like on that kind of terminal.
-The possible attributes are defined in the value of
-@code{custom-face-attributes}.
+have the form @code{(@var{display} @var{atts})}.  @var{display}
+specifies a class of terminals (see below), while @var{atts} is a
+property list of face attributes and their values, specifying the
+appearance of the face on matching terminals
+@iftex
+(see the next section for details about face attributes).
+@end iftex
+@ifnottex
+(@pxref{Face Attributes}, for details about face attributes).
+@end ifnottex
 
 The @var{display} part of an element of @var{spec} determines which
 frames the element matches.  If more than one element of @var{spec}
@@ -1952,29 +1958,23 @@ frame must match one of the @var{value}s specified for it in
 @end table
 @end defmac
 
-  Here's how the standard face @code{region} is defined:
+  Here's how the standard face @code{highlight} is defined:
 
 @example
-@group
-(defface region
-  '((((class color) (min-colors 88) (background dark))
-     :background "blue3")
-@end group
-    (((class color) (min-colors 88) (background light))
-     :background "lightgoldenrod2")
-    (((class color) (min-colors 16) (background dark))
-     :background "blue3")
+(defface highlight
+  '((((class color) (min-colors 88) (background light))
+     :background "darkseagreen2")
+    (((class color) (min-colors 88) (background dark))
+     :background "darkolivegreen")
     (((class color) (min-colors 16) (background light))
-     :background "lightgoldenrod2")
+     :background "darkseagreen2")
+    (((class color) (min-colors 16) (background dark))
+     :background "darkolivegreen")
     (((class color) (min-colors 8))
-     :background "blue" :foreground "white")
-    (((type tty) (class mono))
-     :inverse-video t)
-    (t :background "gray"))
-@group
-  "Basic face for highlighting the region."
+     :background "green" :foreground "black")
+    (t :inverse-video t))
+  "Basic face for highlighting."
   :group 'basic-faces)
-@end group
 @end example
 
   Internally, @code{defface} uses the symbol property
@@ -2010,8 +2010,8 @@ doesn't specify that attribute.  In face merging, when the first face
 fails to specify a particular attribute, the next face gets a chance.
 However, the @code{default} face must specify all attributes.
 
-  Some of these font attributes are meaningful only on certain kinds
-of displays.  If your display cannot handle a certain attribute, the
+  Some of these attributes are meaningful only on certain kinds of
+displays.  If your display cannot handle a certain attribute, the
 attribute is ignored.
 
 @table @code
@@ -2216,20 +2216,18 @@ This function sets one or more attributes of @var{face} for
 the @code{defface} says.
 
 The extra arguments @var{arguments} specify the attributes to set, and
-the values for them.  They should consist of alternating attribute names
-(such as @code{:family} or @code{:underline}) and corresponding values.
-Thus,
+the values for them.  They should consist of alternating attribute
+names (such as @code{:family} or @code{:underline}) and values.  Thus,
 
 @example
 (set-face-attribute 'foo nil
                     :width 'extended
-                    :weight 'bold
-                    :underline "red")
+                    :weight 'bold)
 @end example
 
 @noindent
-sets the attributes @code{:width}, @code{:weight} and @code{:underline}
-to the corresponding values.
+sets the attribute @code{:width} to @code{extended} and the attribute
+@code{:weight} to @code{bold}.
 
 If @var{frame} is @code{t}, this function sets the default attributes
 for new frames.  Default attribute values specified this way override
@@ -2306,54 +2304,51 @@ If @var{value1} is a relative value for the face attribute
 face attribute @var{attribute}, returns @var{value1} unchanged.
 @end defun
 
-  The following functions provide compatibility with Emacs 20 and
-below.  They work by calling @code{set-face-attribute}.  Values of
-@code{t} and @code{nil} for their @var{frame} argument are handled
-just like @code{set-face-attribute} and @code{face-attribute}.
+  The following commands and functions mostly provide compatibility
+with old versions of Emacs.  They work by calling
+@code{set-face-attribute}.  Values of @code{t} and @code{nil} for
+their @var{frame} argument are handled just like
+@code{set-face-attribute} and @code{face-attribute}.  The commands
+read their arguments using the minibuffer, if called interactively.
 
-@defun set-face-foreground face color &optional frame
-@defunx set-face-background face color &optional frame
-These functions set the @code{:foreground} attribute (or
-@code{:background} attribute, respectively) of @var{face} to
-@var{color}.
-@end defun
+@deffn Command set-face-foreground face color &optional frame
+@deffnx Command set-face-background face color &optional frame
+These set the @code{:foreground} attribute (or @code{:background}
+attribute, respectively) of @var{face} to @var{color}.
+@end deffn
 
-@defun set-face-stipple face pattern &optional frame
-This function sets the @code{:stipple} attribute of @var{face} to
+@deffn Command set-face-stipple face pattern &optional frame
+This sets the @code{:stipple} attribute of @var{face} to
 @var{pattern}.
-@end defun
+@end deffn
 
-@defun set-face-font face font &optional frame
-This function sets the @code{:font} attribute of @var{face} to
-@var{font}.
-@end defun
+@deffn Command set-face-font face font &optional frame
+This sets the @code{:font} attribute of @var{face} to @var{font}.
+@end deffn
 
 @defun set-face-bold-p face bold-p &optional frame
-This function sets the @code{:weight} attribute of @var{face} to
-@var{normal} if @var{bold-p} is @code{nil}, and to @var{bold}
-otherwise.
+This sets the @code{:weight} attribute of @var{face} to @var{normal}
+if @var{bold-p} is @code{nil}, and to @var{bold} otherwise.
 @end defun
 
 @defun set-face-italic-p face italic-p &optional frame
-This function sets the @code{:slant} attribute of @var{face} to
-@var{normal} if @var{italic-p} is @code{nil}, and to @var{italic}
-otherwise.
+This sets the @code{:slant} attribute of @var{face} to @var{normal} if
+@var{italic-p} is @code{nil}, and to @var{italic} otherwise.
 @end defun
 
 @defun set-face-underline-p face underline &optional frame
-This function sets the @code{:underline} attribute of @var{face} to
+This sets the @code{:underline} attribute of @var{face} to
 @var{underline}.
 @end defun
 
 @defun set-face-inverse-video-p face inverse-video-p &optional frame
-This function sets the @code{:inverse-video} attribute of @var{face}
-to @var{inverse-video-p}.
+This sets the @code{:inverse-video} attribute of @var{face} to
+@var{inverse-video-p}.
 @end defun
 
-@defun invert-face face &optional frame
-This function swaps the foreground and background colors of face
-@var{face}.
-@end defun
+@deffn Command invert-face face &optional frame
+This swaps the foreground and background colors of face @var{face}.
+@end deffn
 
   The following functions examine the attributes of a face.  If you
 don't specify @var{frame}, they refer to the selected frame; @code{t}
@@ -2459,27 +2454,26 @@ steps, Emacs applies the attribute of the @code{default} face.
   If these various sources together specify more than one face for a
 particular character, Emacs merges the attributes of the various faces
 specified.  For each attribute, Emacs tries using the above order
-(i.e., first the face of any special glyph; then the face for region
-highlighting, if appropriate; then faces specified by overlays, then
-faces specified by text properties, then the @code{mode-line} or
-@code{mode-line-inactive} or @code{header-line} face, if appropriate,
-and finally the @code{default} face).
+(i.e.@: first the face of any special glyph; then the face for region
+highlighting, if appropriate; and so on).
 
 @node Face Remapping
 @subsection Face Remapping
 
   The variable @code{face-remapping-alist} is used for buffer-local or
-global changes in the appearance of a face.  For instance, it can be
-used to make the @code{default} face a variable-pitch face within a
-particular buffer.
+global changes in the appearance of a face.  For instance, it is used
+to implement the @code{text-scale-adjust} command (@pxref{Text
+Scale,,, emacs, The GNU Emacs Manual}).
 
 @defvar face-remapping-alist
-An alist whose elements have the form @code{(@var{face}
-@var{remapping...})}.  This causes Emacs to display text using the
-face @var{face} using @var{remapping...} instead of @var{face}'s
-ordinary definition.  @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.  @xref{Special Properties}.
+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}).
 
 If @code{face-remapping-alist} is buffer-local, its local value takes
 effect only within that buffer.
@@ -2488,17 +2482,15 @@ Two points bear emphasizing:
 
 @enumerate
 @item
-The new definition @var{remapping...} is the complete
-specification of how to display @var{face}---it entirely replaces,
-rather than augmenting or modifying, the normal definition of that
-face.
+@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...} recursively references the same face name
-@var{face}, either directly remapping entry, or via the
-@code{:inherit} attribute of some other face in @var{remapping...},
-then that reference uses the normal definition of @var{face} in the
-selected frame, instead of the ``remapped'' definition.
+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.
 
 For instance, if the @code{mode-line} face is remapped using this
 entry in @code{face-remapping-alist}:
@@ -2512,82 +2504,72 @@ then the new definition of the @code{mode-line} face inherits from the
 @end enumerate
 @end defvar
 
-  A typical use of the @code{face-remapping-alist} is to change a
-buffer's @code{default} face; for example, the following changes a
-buffer's @code{default} face to use the @code{variable-pitch} face,
-with the height doubled:
-
-@example
-(set (make-local-variable 'face-remapping-alist)
-     '((default variable-pitch :height 2.0)))
-@end example
-
   The following functions implement a higher-level interface to
-@code{face-remapping-alist}, making it easier to use
-``cooperatively''.  They are mainly intended for buffer-local use, and
-so all make @code{face-remapping-alist} variable buffer-local as a
-side-effect.  They use entries in @code{face-remapping-alist} which
-have the general form:
+@code{face-remapping-alist}.  Most Lisp code should use these
+functions instead of setting @code{face-remapping-alist} directly, to
+avoid trampling on remappings applied elsewhere.  These functions are
+intended for buffer-local remappings, so they all make
+@code{face-remapping-alist} buffer-local as a side-effect. They manage
+@code{face-remapping-alist} entries of the form
 
 @example
-  (@var{face} @var{relative_specs_1} @var{relative_specs_2} @var{...} @var{base_specs})
+  (@var{face} @var{relative-spec-1} @var{relative-spec-2} @var{...} @var{base-spec})
 @end example
 
-Everything except @var{face} is a ``face spec'': a list of face names
-or face attribute-value pairs.  All face specs are merged together,
-with earlier values taking precedence.
-
-The @var{relative_specs_}n values are ``relative specs'', and are
-added by @code{face-remap-add-relative} (and removed by
-@code{face-remap-remove-relative}.  These are intended for face
-modifications (such as increasing the size).  Typical users of these
-relative specs would be minor modes.
-
-@var{base_specs} is the lowest-priority value, and by default is just the
-face name, which causes the global definition of that face to be used.
-
-A non-default value of @var{base_specs} may also be set using
-@code{face-remap-set-base}.  Because this @emph{overwrites} the
-default base-spec value (which inherits the global face definition),
-it is up to the caller of @code{face-remap-set-base} to add such
-inheritance if it is desired.  A typical use of
-@code{face-remap-set-base} would be a major mode adding a face
-remappings, e.g., of the default face.
-
+@noindent
+where, as explained above, each of the @var{relative-spec-N} and
+@var{base-spec} is either a face name, or a property list of
+attribute/value pairs.  Each of the @dfn{relative remapping} entries,
+@var{relative-spec-N}, is managed by the
+@code{face-remap-add-relative} and @code{face-remap-remove-relative}
+functions; these are intended for simple modifications like changing
+the text size.  The @dfn{base remapping} entry, @var{base-spec}, has
+the lowest priority and is managed by the @code{face-remap-set-base}
+and @code{face-remap-reset-base} functions; it is intended for major
+modes to remap faces in the buffers they control.
 
 @defun face-remap-add-relative face &rest specs
-This functions adds a face remapping entry of @var{face} to @var{specs}
-in the current buffer.
+This functions adds the face specifications in @var{specs} as relative
+remappings for face @var{face} in the current buffer.  The remaining
+arguments, @var{specs}, should form either a list of face names, or a
+property list of attribute/value pairs.
+
+The return value is a Lisp object that serves as a ``cookie''; you can
+pass this object as an argument to @code{face-remap-remove-relative}
+if you need to remove the remapping later.
 
-It returns a ``cookie'' which can be used to later delete the remapping with
-@code{face-remap-remove-relative}.
+@example
+;; Remap the `escape-glyph' face into a combination
+;; of the `highlight' and `italic' faces:
+(face-remap-add-relative 'escape-glyph 'highlight 'italic)
 
-@var{specs} can be any value suitable for the @code{face} text
-property, including a face name, a list of face names, or a
-face-attribute property list.  The attributes given by @var{specs}
-will be merged with any other currently active face remappings of
-@var{face}, and with the global definition of @var{face} (by default;
-this may be changed using @code{face-remap-set-base}), with the most
-recently added relative remapping taking precedence.
+;; Increase the size of the `default' face by 50%:
+(face-remap-add-relative 'default :height 1.5)
+@end example
 @end defun
 
 @defun face-remap-remove-relative cookie
-This function removes a face remapping previously added by
-@code{face-remap-add-relative}.  @var{cookie} should be a return value
-from that function.
+This function removes a relative remapping previously added by
+@code{face-remap-add-relative}.  @var{cookie} should be the Lisp
+object returned by @code{face-remap-add-relative} when the remapping
+was added.
 @end defun
 
 @defun face-remap-set-base face &rest specs
-This function sets the ``base remapping'' of @var{face} in the current
+This function sets the base remapping of @var{face} in the current
 buffer to @var{specs}.  If @var{specs} is empty, the default base
-remapping is restored, which inherits from the global definition of
-@var{face}; note that this is different from @var{specs} containing a
+remapping is restored, similar to calling @code{face-remap-reset-base}
+(see below); note that this is different from @var{specs} containing a
 single value @code{nil}, which has the opposite result (the global
 definition of @var{face} is ignored).
+
+This overwrites the default @var{base-spec}, which inherits the global
+face definition, so it is up to the caller to add such inheritance if
+so desired.
 @end defun
 
 @defun face-remap-reset-base face
-This function sets the ``base remapping'' of @var{face} to its default
+This function sets the base remapping of @var{face} to its default
 value, which inherits from @var{face}'s global definition.
 @end defun
 
@@ -2596,29 +2578,8 @@ value, which inherits from @var{face}'s global definition.
 
   Here are additional functions for creating and working with faces.
 
-@defun make-face name
-This function defines a new face named @var{name}, initially with all
-attributes @code{nil}.  It does nothing if there is already a face named
-@var{name}.
-@end defun
-
 @defun face-list
-This function returns a list of all defined faces.
-@end defun
-
-@defun copy-face old-face new-name &optional frame new-frame
-This function defines a face named @var{new-name} as a copy of the existing
-face named @var{old-face}.  It creates the face @var{new-name} if that
-doesn't already exist.
-
-If the optional argument @var{frame} is given, this function applies
-only to that frame.  Otherwise it applies to each frame individually,
-copying attributes from @var{old-face} in each frame to @var{new-face}
-in the same frame.
-
-If the optional argument @var{new-frame} is given, then @code{copy-face}
-copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
-in @var{new-frame}.
+This function returns a list of all defined face names.
 @end defun
 
 @defun face-id face
@@ -2752,7 +2713,7 @@ these are used for messages in @samp{*Compilation*} buffers.
 @node Font Selection
 @subsection Font Selection
 
-  Before Emacs can draw a character on a particular display, it must
+  Before Emacs can draw a character on a graphical display, it must
 select a @dfn{font} for that character@footnote{In this context, the
 term @dfn{font} has nothing to do with Font Lock (@pxref{Font Lock
 Mode}).}.  @xref{Fonts,,, emacs, The GNU Emacs Manual}.  Normally,
diff --git a/etc/NEWS b/etc/NEWS
index 78b306f057e..de5b865a54b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -123,6 +123,8 @@ and pops down the *Completions* buffer accordingly.
 *** Completion style can be set per-category `completion-category-overrides'.
 +++
 *** Completion of buffers now uses substring completion by default.
+---
+*** The `widget-complete-field' option has been removed.
 
 ** Mail changes
 
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 3699bb0f5bd..ea7d81bb969 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,9 @@
+2012-03-21  Chong Yidong  <cyd@gnu.org>
+
+        * faces.el (make-face, make-empty-face, copy-face):
+        * face-remap.el (face-remap-add-relative, face-remap-set-base):
+        Doc fixes.
+
 2012-03-21  Stefan Monnier  <monnier@iro.umontreal.ca>
 
         * wid-edit.el (widget-complete-field): Remove (bug#11051).
diff --git a/lisp/face-remap.el b/lisp/face-remap.el
index 3af9e31a6f7..ca7a28328f9 100644
--- a/lisp/face-remap.el
+++ b/lisp/face-remap.el
@@ -106,21 +106,20 @@ The list structure of ENTRY may be destructively modified."
 ;;;###autoload
 (defun face-remap-add-relative (face &rest specs)
   "Add a face remapping entry of FACE to SPECS in the current buffer.
-
-Return a cookie which can be used to delete the remapping with
+Return a cookie which can be used to delete this remapping with
 `face-remap-remove-relative'.
 
-SPECS can be any value suitable for the `face' text property,
-including a face name, a list of face names, or a face-attribute
-property list.  The attributes given by SPECS will be merged with
-any other currently active face remappings of FACE, and with the
-global definition of FACE.  An attempt is made to sort multiple
-entries so that entries with relative face-attributes are applied
-after entries with absolute face-attributes.
-
-The base (lowest priority) remapping may be set to a specific
-value, instead of the default of the global face definition,
-using `face-remap-set-base'."
+The remaining arguments, SPECS, should be either a list of face
+names, or a property list of face attribute/value pairs.  The
+remapping specified by SPECS takes effect alongside the
+remappings from other calls to `face-remap-add-relative', as well
+as the normal definition of FACE (at lowest priority).  This
+function tries to sort multiple remappings for the same face, so
+that remappings specifying relative face attributes are applied
+after remappings specifying absolute face attributes.
+
+The base (lowest priority) remapping may be set to something
+other than the normal definition of FACE via `face-remap-set-base'."
   (while (and (consp specs) (null (cdr specs)))
     (setq specs (car specs)))
   (make-local-variable 'face-remapping-alist)
@@ -148,7 +147,9 @@ COOKIE should be the return value from that function."
 
 ;;;###autoload
 (defun face-remap-reset-base (face)
-  "Set the base remapping of FACE to inherit from FACE's global definition."
+  "Set the base remapping of FACE to the normal definition of FACE.
+This causes the remappings specified by `face-remap-add-relative'
+to apply on top of the normal definition of FACE."
   (let ((entry (assq face face-remapping-alist)))
     (when entry
       ;; If there's nothing except a base remapping, we simply remove
@@ -163,10 +164,15 @@ COOKIE should be the return value from that function."
 ;;;###autoload
 (defun face-remap-set-base (face &rest specs)
   "Set the base remapping of FACE in the current buffer to SPECS.
-If SPECS is empty, the default base remapping is restored, which
-inherits from the global definition of FACE; note that this is
-different from SPECS containing a single value `nil', which does
-not inherit from the global definition of FACE."
+This causes the remappings specified by `face-remap-add-relative'
+to apply on top of the face specification given by SPECS.  SPECS
+should be either a list of face names, or a property list of face
+attribute/value pairs.
+
+If SPECS is empty, call `face-remap-reset-base' to use the normal
+definition of FACE as the base remapping; note that this is
+different from SPECS containing a single value `nil', which means
+not to inherit from the global definition of FACE at all."
   (while (and (consp specs) (not (null (car specs))) (null (cdr specs)))
     (setq specs (car specs)))
   (if (or (null specs)
diff --git a/lisp/faces.el b/lisp/faces.el
index 34fad66ce27..0256f8d951a 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -122,15 +122,13 @@ REGISTRY, ALTERNATIVE1, ALTERNATIVE2, and etc."
   "Return a list of all defined faces."
   (mapcar #'car face-new-frame-defaults))
 
-
-;;; ### If not frame-local initialize by what X resources?
-
 (defun make-face (face &optional no-init-from-resources)
   "Define a new face with name FACE, a symbol.
-NO-INIT-FROM-RESOURCES non-nil means don't initialize frame-local
-variants of FACE from X resources.  (X resources recognized are found
-in the global variable `face-x-resources'.)  If FACE is already known
-as a face, leave it unmodified.  Value is FACE."
+Do not call this directly from Lisp code; use `defface' instead.
+
+If NO-INIT-FROM-RESOURCES is non-nil, don't initialize face
+attributes from X resources.  If FACE is already known as a face,
+leave it unmodified.  Return FACE."
   (interactive (list (read-from-minibuffer
                       "Make face: " nil nil t 'face-name-history)))
   (unless (facep face)
@@ -145,31 +143,30 @@ as a face, leave it unmodified.  Value is FACE."
       (make-face-x-resource-internal face)))
   face)
 
-
 (defun make-empty-face (face)
   "Define a new, empty face with name FACE.
-If the face already exists, it is left unmodified.  Value is FACE."
+Do not call this directly from Lisp code; use `defface' instead."
   (interactive (list (read-from-minibuffer
                       "Make empty face: " nil nil t 'face-name-history)))
   (make-face face 'no-init-from-resources))
 
-
 (defun copy-face (old-face new-face &optional frame new-frame)
-  "Define a face just like OLD-FACE, with name NEW-FACE.
-
-If NEW-FACE already exists as a face, it is modified to be like
-OLD-FACE.  If it doesn't already exist, it is created.
-
-If the optional argument FRAME is given as a frame, NEW-FACE is
-changed on FRAME only.
-If FRAME is t, the frame-independent default specification for OLD-FACE
-is copied to NEW-FACE.
-If FRAME is nil, copying is done for the frame-independent defaults
-and for each existing frame.
-
-If the optional fourth argument NEW-FRAME is given,
-copy the information from face OLD-FACE on frame FRAME
-to NEW-FACE on frame NEW-FRAME.  In this case, FRAME may not be nil."
+  "Define a face named NEW-FACE, which is a copy of OLD-FACE.
+This function does not copy face customization data, so NEW-FACE
+will not be made customizable.  Most Lisp code should not call
+this function; use `defface' with :inherit instead.
+
+If NEW-FACE already exists as a face, modify it to be like
+OLD-FACE.  If NEW-FACE doesn't already exist, create it.
+
+If the optional argument FRAME is a frame, change NEW-FACE on
+FRAME only.  If FRAME is t, copy the frame-independent default
+specification for OLD-FACE to NEW-FACE.  If FRAME is nil, copy
+the defaults as well as the faces on each existing frame.
+
+If the optional fourth argument NEW-FRAME is given, copy the
+information from face OLD-FACE on frame FRAME to NEW-FACE on
+frame NEW-FRAME.  In this case, FRAME must not be nil."
   (let ((inhibit-quit t))
     (if (null frame)
         (progn
diff --git a/src/ChangeLog b/src/ChangeLog
index 4f32309562b..7a97859ba63 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,7 @@
+2012-03-21  Chong Yidong  <cyd@gnu.org>
+
+        * xfaces.c (Vface_remapping_alist): Doc fix.
+
 2012-03-20  Eli Zaretskii  <eliz@gnu.org>
 
         * w32proc.c (Fw32_set_console_codepage)
diff --git a/src/xfaces.c b/src/xfaces.c
index bcb04188aeb..476fb1e0366 100644
--- a/src/xfaces.c
+++ b/src/xfaces.c
@@ -6599,20 +6599,22 @@ ignore.  */);
                doc: /* Alist of face remappings.
 Each element is of the form:
 
-   (FACE REPLACEMENT...),
+   (FACE . REPLACEMENT),
 
-which causes display of the face FACE to use REPLACEMENT... instead.
-REPLACEMENT... is interpreted the same way as the value of a `face'
-text property: it may be (1) A face name, (2) A list of face names,
-(3) A property-list of face attribute/value pairs, or (4) A list of
-face names or lists containing face attribute/value pairs.
+which causes display of the face FACE to use REPLACEMENT instead.
+REPLACEMENT is a face specification, i.e. one of the following:
 
-Multiple entries in REPLACEMENT... are merged together to form the final
-result, with faces or attributes earlier in the list taking precedence
-over those that are later.
+  (1) a face name
+  (2) a property list of attribute/value pairs, or
+  (3) a list in which each element has the form of (1) or (2).
 
-Face-name remapping cycles are suppressed; recursive references use the
-underlying face instead of the remapped face.  So a remapping of the form:
+List values for REPLACEMENT are merged to form the final face
+specification, with earlier entries taking precedence, in the same as
+as in the `face' text property.
+
+Face-name remapping cycles are suppressed; recursive references use
+the underlying face instead of the remapped face.  So a remapping of
+the form:
 
    (FACE EXTRA-FACE... FACE)
 
@@ -6620,13 +6622,13 @@ or:
 
    (FACE (FACE-ATTR VAL ...) FACE)
 
-will cause EXTRA-FACE... or (FACE-ATTR VAL ...) to be _merged_ with the
-existing definition of FACE.  Note that for the default face, this isn't
-necessary, as every face inherits from the default face.
+causes EXTRA-FACE... or (FACE-ATTR VAL ...) to be _merged_ with the
+existing definition of FACE.  Note that this isn't necessary for the
+default face, since every face inherits from the default face.
 
-Making this variable buffer-local is a good way to allow buffer-specific
-face definitions.  For instance, the mode my-mode could define a face
-`my-mode-default', and then in the mode setup function, do:
+If this variable is made buffer-local, the face remapping takes effect
+only in that buffer.  For instance, the mode my-mode could define a
+face `my-mode-default', and then in the mode setup function, do:
 
    (set (make-local-variable 'face-remapping-alist)
         '((default my-mode-default)))).