Doc fixes for defface and friends.

* lisp/cus-edit.el (custom-unlispify-remove-prefixes): Add warning.

* lisp/custom.el (defface): Doc fix.

* doc/lispref/customize.texi (Customization): Define customization more
carefully.
(Common Keywords): Add xref to Constant Variables.

* doc/lispref/display.texi (Faces): Discuss anonymous faces.
(Face Attributes): Tweak intro.
(Defining Faces): Move after the Face Attributes node.  Copyedits.
(Displaying Faces): Describe role of inheritance.

* doc/lispref/variables.texi (Defining Variables): Link to defcustom's node
instead of the higher-level Customization chapter.

Fixes: debbugs:11440

9 files changed, 331 insertions, 269 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index ce99c81a912..329c194f45a 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,17 @@
+2012-09-18  Chong Yidong  <cyd@gnu.org>
+
+        * display.texi (Faces): Discuss anonymous faces.
+        (Face Attributes): Tweak intro.
+        (Defining Faces): Move after the Face Attributes node.  Copyedits.
+        (Displaying Faces): Describe role of inheritance.
+
+        * customize.texi (Customization): Define customization more
+        carefully (Bug#11440).
+        (Common Keywords): Add xref to Constant Variables.
+
+        * variables.texi (Defining Variables): Link to defcustom's node
+        instead of the higher-level Customization chapter.
+
 2012-09-11  Paul Eggert  <eggert@cs.ucla.edu>
 
         Simplify, document, and port floating-point (Bug#12381).
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 38dfc949264..c9d22851ed2 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -6,13 +6,30 @@
 @chapter Customization Settings
 
 @cindex customization item
-  This chapter describes how to declare customizable variables and
-customization groups for classifying them.  We use the term
-@dfn{customization item} to include customizable variables,
-customization groups, as well as faces.
-
-  @xref{Defining Faces}, for the @code{defface} macro, which is used
-for declaring customizable faces.
+  Users of Emacs can customize variables and faces without writing
+Lisp code, by using the Customize interface.  @xref{Easy
+Customization,,, emacs, The GNU Emacs Manual}.  This chapter describes
+how to define @dfn{customization items} that users can interact with
+through the Customize interface.
+
+  Customization items include customizable variables, which are
+defined with the
+@ifinfo
+@code{defcustom} macro (@pxref{Variable Definitions});
+@end ifinfo
+@ifnotinfo
+@code{defcustom} macro;
+@end ifnotinfo
+customizable faces, which are defined with @code{defface} (described
+separately in @ref{Defining Faces}); and @dfn{customization groups},
+defined with
+@ifinfo
+@code{defgroup} (@pxref{Group Definitions}),
+@end ifinfo
+@ifnotinfo
+@code{defgroup},
+@end ifnotinfo
+which act as containers for groups of related customization items.
 
 @menu
 * Common Keywords::         Common keyword arguments for all kinds of
@@ -29,9 +46,10 @@ for declaring customizable faces.
 
 @cindex customization keywords
   The customization declarations that we will describe in the next few
-sections (@code{defcustom}, @code{defgroup}, etc.) all accept keyword
-arguments for specifying various information.  This section describes
-keywords that apply to all types of customization declarations.
+sections---@code{defcustom}, @code{defgroup}, etc.---all accept
+keyword arguments (@pxref{Constant Variables}) for specifying various
+information.  This section describes keywords that apply to all types
+of customization declarations.
 
   All of these keywords, except @code{:tag}, can be used more than once
 in a given item.  Each use of the keyword has an independent effect.
@@ -188,14 +206,14 @@ choice is the official name of the package, such as MH-E or Gnus.
 @cindex define customization group
 @cindex customization groups, defining
 
-  Each Emacs Lisp package should have one main customization group which
-contains all the options, faces and other groups in the package.  If the
-package has a small number of options and faces, use just one group and
-put everything in it.  When there are more than twelve or so options and
-faces, then you should structure them into subgroups, and put the
-subgroups under the package's main customization group.  It is OK to
-put some of the options and faces in the package's main group alongside
-the subgroups.
+  Each Emacs Lisp package should have one main customization group
+which contains all the options, faces and other groups in the package.
+If the package has a small number of options and faces, use just one
+group and put everything in it.  When there are more than twenty or so
+options and faces, then you should structure them into subgroups, and
+put the subgroups under the package's main customization group.  It is
+OK to put some of the options and faces in the package's main group
+alongside the subgroups.
 
   The package's main or only group should be a member of one or more of
 the standard customization groups.  (To display the full list of them,
@@ -251,7 +269,17 @@ confusing names for options and faces.
 @node Variable Definitions
 @section Defining Customization Variables
 @cindex define customization options
-@cindex customization variables, how to define
+@cindex customizable variables, how to define
+@cindex user options, how to define
+
+  @dfn{Customizable variables}, also called @dfn{user options}, are
+global Lisp variables whose values can be set through the Customize
+interface.  Unlike other global variables, which are defined with
+@code{defvar} (@pxref{Defining Variables}), customizable variables are
+defined using the @code{defcustom} macro.  In addition to calling
+@code{defvar} as a subroutine, @code{defcustom} states how the
+variable should be displayed in the Customize interface, the values it
+is allowed to take, etc.
 
 @defmac defcustom option standard doc [keyword value]@dots{}
 This macro declares @var{option} as a user option (i.e.@: a
@@ -291,13 +319,14 @@ has not been assigned the right value yet.  In that case, use
 standard value after Emacs starts up.
 @end defmac
 
-  @code{defcustom} accepts the following additional keywords:
+  In addition to the keywords listed in @ref{Common Keywords}, this
+macro accepts the following keywords:
 
 @table @code
 @item :type @var{type}
 Use @var{type} as the data type for this option.  It specifies which
-values are legitimate, and how to display the value.
-@xref{Customization Types}, for more information.
+values are legitimate, and how to display the value
+(@pxref{Customization Types}).
 
 @item :options @var{value-list}
 @kindex options@r{, @code{defcustom} keyword}
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 64aa891e56b..11a86f3c1c5 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1863,20 +1863,36 @@ height.
 
   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}, 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.
+underlining, etc.  Faces control how Emacs displays text in buffers,
+as well as other parts of the frame such as the mode line.
+
+@cindex anonymous face
+  One way to represent a face is as a property list of attributes,
+like @code{(:foreground "red" :weight bold)}.  For example, you can
+assign such an @dfn{anonymous face} as the value of the @code{face}
+text property; this causes Emacs to display the underlying text with
+the specified attributes.  @xref{Special Properties}.
+
+@cindex face name
+  More commonly, a face is referred to via a @dfn{face name}: a Lisp
+symbol which is associated with a set of face attributes.  Named faces
+are defined using the @code{defface} macro (@pxref{Defining Faces}).
+Emacs defines several standard named faces; @xref{Standard Faces,,,
+emacs, The GNU Emacs Manual}.
+
+  Many parts of Emacs require named faces, and do not accept anonymous
+faces.  These include the functions documented in @ref{Attribute
+Functions}, and the variable @code{font-lock-keywords}
+(@pxref{Search-based Fontification}).  Unless otherwise stated, we
+will use the term @dfn{face} to refer only to named faces.
+
+  For backward compatibility, you can also use a string to specify a
+face name; that is equivalent to a Lisp symbol with 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}.
+This function returns a non-@code{nil} value if @var{object} is a
+named face: a Lisp symbol or string which serves as a face name.
+Otherwise, it returns @code{nil}.
 @end defun
 
   By default, each face name corresponds to the same set of attributes
@@ -1884,8 +1900,8 @@ 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.
 * Face Attributes::     What is in a face?
+* Defining Faces::      How to define a face.
 * Attribute Functions::  Functions to examine and set face attributes.
 * Displaying Faces::     How Emacs combines the faces specified for a character.
 * Face Remapping::      Remapping faces to alternative definitions.
@@ -1900,161 +1916,21 @@ attributes in one frame (@pxref{Attribute Functions}).
 * Low-Level Font::      Lisp representation for character display fonts.
 @end menu
 
-@node Defining Faces
-@subsection Defining Faces
-
-  The @code{defface} macro defines a face and specifies its default
-appearance.  The user can subsequently customize the face using the
-Customize interface (@pxref{Customization}).
-
-@defmac defface face spec doc [keyword value]@dots{}
-This macro declares @var{face} as a customizable face whose default
-attributes are given by @var{spec}.  You should not quote the symbol
-@var{face}, and it should not end in @samp{-face} (that would be
-redundant).  The argument @var{doc} is a documentation string for the
-face.  The additional @var{keyword} arguments have the same meanings
-as in @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
-
-When @code{defface} executes, it defines the face according to
-@var{spec}, then uses any customizations that were read from the
-init file (@pxref{Init File}) to override that specification.
-
-When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs
-Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun}
-overrides any customizations of the face.  This way, the face reflects
-exactly what the @code{defface} says.
-
-@cindex face specification
-The @var{spec} argument is a @dfn{face specification}, which states
-how the face should appear on different kinds of terminals.  It should
-be an alist whose elements each have the form
-
-@example
-(@var{display} . @var{plist})
-@end example
-
-@noindent
-@var{display} specifies a class of terminals (see below), while
-@var{plist} is a property list of face attributes and their values,
-specifying how the face appears on such 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}
-matches a given frame, the first element that matches is the one used
-for that frame.  There are three possibilities for @var{display}:
-
-@table @asis
-@item @code{default}
-This element of @var{spec} doesn't match any frames; instead, it
-specifies defaults that apply to all frames.  This element, if used,
-must be the first element of @var{spec}.  Each of the following
-elements can override any or all of these defaults.
-
-@item @code{t}
-This element of @var{spec} matches all frames.  Therefore, any
-subsequent elements of @var{spec} are never used.  Normally
-@code{t} is used in the last (or only) element of @var{spec}.
-
-@item a list
-If @var{display} is a list, each element should have the form
-@code{(@var{characteristic} @var{value}@dots{})}.  Here
-@var{characteristic} specifies a way of classifying frames, and the
-@var{value}s are possible classifications which @var{display} should
-apply to.  Here are the possible values of @var{characteristic}:
-
-@table @code
-@item type
-The kind of window system the frame uses---either @code{graphic} (any
-graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console),
-@code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty} 
-(a non-graphics-capable display).
-@xref{Window Systems, window-system}.
-
-@item class
-What kinds of colors the frame supports---either @code{color},
-@code{grayscale}, or @code{mono}.
-
-@item background
-The kind of background---either @code{light} or @code{dark}.
-
-@item min-colors
-An integer that represents the minimum number of colors the frame
-should support.  This matches a frame if its
-@code{display-color-cells} value is at least the specified integer.
-
-@item supports
-Whether or not the frame can display the face attributes given in
-@var{value}@dots{} (@pxref{Face Attributes}).  @xref{Display Face
-Attribute Testing}, for more information on exactly how this testing
-is done.
-@end table
-
-If an element of @var{display} specifies more than one @var{value} for a
-given @var{characteristic}, any of those values is acceptable.  If
-@var{display} has more than one element, each element should specify a
-different @var{characteristic}; then @emph{each} characteristic of the
-frame must match one of the @var{value}s specified for it in
-@var{display}.
-@end table
-@end defmac
-
-  Here's how the standard face @code{highlight} is defined:
-
-@example
-(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 "darkseagreen2")
-    (((class color) (min-colors 16) (background dark))
-     :background "darkolivegreen")
-    (((class color) (min-colors 8))
-     :background "green" :foreground "black")
-    (t :inverse-video t))
-  "Basic face for highlighting."
-  :group 'basic-faces)
-@end example
-
-  Internally, Emacs stores the face's default specification in its
-@code{face-defface-spec} symbol property (@pxref{Property Lists}).
-The @code{saved-face} property stores the face specification saved by
-the user, using the customization buffer; the @code{customized-face}
-property stores the face specification customized for the current
-session, but not saved; and the @code{theme-face} property stores an
-alist associating the active customization settings and Custom themes
-with their specifications for that face.  The face's documentation
-string is stored in the @code{face-documentation} property.  But
-normally you should not try to set any of these properties directly.
-@xref{Applying Customizations}, for the @code{custom-set-faces}
-function, which is used to apply customized face settings.
-
-  People are sometimes tempted to create variables whose values
-specify a face to use.  In the vast majority of cases, this is not
-necessary; it is preferable to simply use faces directly.
-
 @node Face Attributes
 @subsection Face Attributes
 @cindex face attributes
 
-  The effect of using a face is determined by a fixed set of @dfn{face
-attributes}.  This table lists all the face attributes, their possible
-values, and their effects.  You can specify more than one face for a
-given piece of text; Emacs merges the attributes of all the faces to
-determine how to display the text.  @xref{Displaying Faces}.
+  @dfn{Face attributes} determine the visual appearance of a face.
+The following table lists all the face attributes, their possible
+values, and their effects.
 
-  In addition to the values given below, each face attribute can also
-have the value @code{unspecified}.  This special value means the face
-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.
+  Apart from the values given below, each face attribute can have the
+value @code{unspecified}.  This special value means that the face
+doesn't specify that attribute directly.  An @code{unspecified}
+attribute tells Emacs to refer instead to a parent face (see the
+description @code{:inherit} attribute below); or, failing that, to an
+underlying face (@pxref{Displaying Faces}).  The @code{default} face
+must specify all attributes.
 
   Some of these attributes are meaningful only on certain kinds of
 displays.  If your display cannot handle a certain attribute, the
@@ -2063,7 +1939,7 @@ attribute is ignored.
 @table @code
 @item :family
 Font family or fontset (a string).  @xref{Fonts,,, emacs, The GNU
-Emacs Manual}, for more information about font families; the function
+Emacs Manual}, for more information about font families.  The function
 @code{font-family-list} (see below) returns a list of available family
 names.  @xref{Fontsets}, for information about fontsets.
 
@@ -2083,9 +1959,8 @@ The height of the font.  In the simplest case, this is an integer in
 units of 1/10 point.
 
 The value can also be a floating point number or a function, which
-specifies the height relative to an @dfn{underlying face} (i.e., a
-face that has a lower priority in the list described in
-@ref{Displaying Faces}).  If the value is a floating point number,
+specifies the height relative to an @dfn{underlying face}
+(@pxref{Displaying Faces}).  If the value is a floating point number,
 that specifies the amount by which to scale the height of the
 underlying face.  If the value is a function, that function is called
 with one argument, the height of the underlying face, and returns the
@@ -2261,11 +2136,147 @@ suitable for use with @code{:stipple} (see above).  It returns
 @code{nil} otherwise.
 @end defun
 
+@node Defining Faces
+@subsection Defining Faces
+
+  The usual way to define a face is through the @code{defface} macro.
+This macro defines a face name, and associates that name with a set of
+face attributes.  It also sets up the face so that the user can
+customize it via the Customize interface (@pxref{Customization}).
+
+@defmac defface face spec doc [keyword value]@dots{}
+This macro declares @var{face} as a customizable face whose default
+attributes are given by @var{spec}.  You should not quote the symbol
+@var{face}, and it should not end in @samp{-face} (that would be
+redundant).  The argument @var{doc} is a documentation string for the
+face.  The additional @var{keyword} arguments have the same meanings
+as in @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
+
+When @code{defface} executes, it defines the face according to
+@var{spec}, then uses any customizations that were read from the
+init file (@pxref{Init File}) to override that specification.
+
+When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs
+Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun}
+overrides any customizations of the face.  This way, the face reflects
+exactly what the @code{defface} says.
+
+@cindex face specification
+The @var{spec} argument is a @dfn{face specification}, which states
+how the face should appear on different kinds of terminals.  It should
+be an alist whose elements each have the form
+
+@example
+(@var{display} . @var{plist})
+@end example
+
+@noindent
+@var{display} specifies a class of terminals (see below).  @var{plist}
+is a property list of face attributes and their values, specifying how
+the face appears on such terminals.  For backward compatibility, you
+can also write an element as @code{(@var{display} @var{plist})}.
+
+The @var{display} part of an element of @var{spec} determines which
+terminals the element matches.  If more than one element of @var{spec}
+matches a given terminal, the first element that matches is the one
+used for that terminal.  There are three possibilities for
+@var{display}:
+
+@table @asis
+@item @code{default}
+This element of @var{spec} doesn't match any terminal; instead, it
+specifies defaults that apply to all terminals.  This element, if
+used, must be the first element of @var{spec}.  Each of the following
+elements can override any or all of these defaults.
+
+@item @code{t}
+This element of @var{spec} matches all terminals.  Therefore, any
+subsequent elements of @var{spec} are never used.  Normally @code{t}
+is used in the last (or only) element of @var{spec}.
+
+@item a list
+If @var{display} is a list, each element should have the form
+@code{(@var{characteristic} @var{value}@dots{})}.  Here
+@var{characteristic} specifies a way of classifying terminals, and the
+@var{value}s are possible classifications which @var{display} should
+apply to.  Here are the possible values of @var{characteristic}:
+
+@table @code
+@item type
+The kind of window system the terminal uses---either @code{graphic}
+(any graphics-capable display), @code{x}, @code{pc} (for the MS-DOS
+console), @code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty} (a
+non-graphics-capable display).  @xref{Window Systems, window-system}.
+
+@item class
+What kinds of colors the terminal supports---either @code{color},
+@code{grayscale}, or @code{mono}.
+
+@item background
+The kind of background---either @code{light} or @code{dark}.
+
+@item min-colors
+An integer that represents the minimum number of colors the terminal
+should support.  This matches a terminal if its
+@code{display-color-cells} value is at least the specified integer.
+
+@item supports
+Whether or not the terminal can display the face attributes given in
+@var{value}@dots{} (@pxref{Face Attributes}).  @xref{Display Face
+Attribute Testing}, for more information on exactly how this testing
+is done.
+@end table
+
+If an element of @var{display} specifies more than one @var{value} for
+a given @var{characteristic}, any of those values is acceptable.  If
+@var{display} has more than one element, each element should specify a
+different @var{characteristic}; then @emph{each} characteristic of the
+terminal must match one of the @var{value}s specified for it in
+@var{display}.
+@end table
+@end defmac
+
+  Here's how the standard face @code{highlight} is defined:
+
+@example
+(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 "darkseagreen2")
+    (((class color) (min-colors 16) (background dark))
+     :background "darkolivegreen")
+    (((class color) (min-colors 8))
+     :background "green" :foreground "black")
+    (t :inverse-video t))
+  "Basic face for highlighting."
+  :group 'basic-faces)
+@end example
+
+  Internally, Emacs stores the face's default specification in its
+@code{face-defface-spec} symbol property (@pxref{Property Lists}).
+The @code{saved-face} property stores the face specification saved by
+the user, using the customization buffer; the @code{customized-face}
+property stores the face specification customized for the current
+session, but not saved; and the @code{theme-face} property stores an
+alist associating the active customization settings and Custom themes
+with their specifications for that face.  The face's documentation
+string is stored in the @code{face-documentation} property.  But
+normally you should not try to set any of these properties directly.
+@xref{Applying Customizations}, for the @code{custom-set-faces}
+function, which is used to apply customized face settings.
+
+  People are sometimes tempted to create variables whose values
+specify a face to use.  In the vast majority of cases, this is not
+necessary; it is preferable to simply use faces directly.
+
 @node Attribute Functions
 @subsection Face Attribute Functions
 
   This section describes the functions for accessing and modifying the
-attributes of an existing face.
+attributes of an existing named face.
 
 @defun set-face-attribute face frame &rest arguments
 This function sets one or more attributes of @var{face} for
@@ -2467,8 +2478,12 @@ This function returns the @code{:inverse-video} attribute of face @var{face}.
 @node Displaying Faces
 @subsection Displaying Faces
 
-  Here is how Emacs determines the face to use for displaying any
-given piece of text:
+  When Emacs displays a given piece of text, the visual appearance of
+the text may be determined by faces drawn from different sources.  If
+these various sources together specify more than one face for a
+particular character, Emacs merges the attributes of the various
+faces.  Here is the order in which Emacs merges the faces, from
+highest to lowest priority:
 
 @itemize @bullet
 @item
@@ -2482,11 +2497,11 @@ Manual}.
 
 @item
 If the text lies within an overlay with a non-@code{nil} @code{face}
-property, Emacs applies the face or face attributes specified by that
-property.  If the overlay has a @code{mouse-face} property and the
-mouse is ``near enough'' to the overlay, Emacs applies the face or
-face attributes specified by the @code{mouse-face} property instead.
-@xref{Overlay Properties}.
+property, Emacs applies the face(s) specified by that property.  If
+the overlay has a @code{mouse-face} property and the mouse is ``near
+enough'' to the overlay, Emacs applies the face or face attributes
+specified by the @code{mouse-face} property instead.  @xref{Overlay
+Properties}.
 
 When multiple overlays cover one character, an overlay with higher
 priority overrides those with lower priority.  @xref{Overlays}.
@@ -2508,11 +2523,12 @@ If any given attribute has not been specified during the preceding
 steps, Emacs applies the attribute of the @code{default} face.
 @end itemize
 
-  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; and so on).
+  At each stage, if a face has a valid @code{:inherit} attribute,
+Emacs treats any attribute with an @code{unspecified} value as having
+the corresponding value drawn from the parent face(s).  @pxref{Face
+Attributes}.  Note that the parent face(s) may also leave the
+attribute unspecified; in that case, the attribute remains unspecified
+at the next level of face merging.
 
 @node Face Remapping
 @subsection Face Remapping
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index caa5185dec3..db770616820 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1366,8 +1366,8 @@ Overlays
 
 Faces
 
-* Defining Faces::          How to define a face.
 * Face Attributes::         What is in a face?
+* Defining Faces::          How to define a face.
 * Attribute Functions::     Functions to examine and set face attributes.
 * Displaying Faces::        How Emacs combines the faces specified for
                               a character.
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index fe7f24e42cd..a5910ea921b 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -2999,12 +2999,11 @@ can be the following:
 A face name (a symbol or string).
 
 @item
-A property list of face attributes.  This has the
-form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
-face attribute name and @var{value} is a meaningful value for that
-attribute.  With this feature, you do not need to create a face each
-time you want to specify a particular attribute for certain text.
-@xref{Face Attributes}.
+A property list of face attributes.  This has the form (@var{keyword}
+@var{value} @dots{}), where each @var{keyword} is a face attribute
+name and @var{value} is a meaningful value for that attribute.  With
+this feature, you do not need to create a face each time you want to
+specify a particular attribute for certain text.
 
 @item
 A list of faces.  This specifies a face which is an aggregate of the
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index c5b66757ace..1c0abcb8e66 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -403,7 +403,8 @@ unconditionally initializes the variable, whereas @code{defvar}
 initializes it only if it is originally void.
 
   To define a customizable variable, you should use @code{defcustom}
-(which calls @code{defvar} as a subroutine).  @xref{Customization}.
+(which calls @code{defvar} as a subroutine).  @xref{Variable
+Definitions}.
 
 @defspec defvar symbol [value [doc-string]]
 This special form defines @var{symbol} as a variable.  Note that
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index c1c9e5ee1c8..7ed5f6af14b 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,9 @@
+2012-09-18  Chong Yidong  <cyd@gnu.org>
+
+        * custom.el (defface): Doc fix.
+
+        * cus-edit.el (custom-unlispify-remove-prefixes): Add warning.
+
 2012-09-18  Martin Blais  <blais@furius.ca>  (tiny change)
 
         * progmodes/compile.el (compilation-start): Use compilation-always-kill
diff --git a/lisp/cus-edit.el b/lisp/cus-edit.el
index 86a19131569..2e6f2b14625 100644
--- a/lisp/cus-edit.el
+++ b/lisp/cus-edit.el
@@ -526,7 +526,10 @@ WIDGET is the widget to apply the filter entries of MENU on."
   :type 'boolean)
 
 (defcustom custom-unlispify-remove-prefixes nil
-  "Non-nil means remove group prefixes from option names in buffer."
+  "Non-nil means remove group prefixes from option names in buffer.
+Discarding prefixes often leads to confusing names for options
+and faces in Customize buffers, so do not set this to a non-nil
+value unless you are sure you know what it does."
   :group 'custom-menu
   :group 'custom-buffer
   :type 'boolean)
diff --git a/lisp/custom.el b/lisp/custom.el
index 01b0e6d1650..dfc8e631152 100644
--- a/lisp/custom.el
+++ b/lisp/custom.el
@@ -350,68 +350,62 @@ FACE does not need to be quoted.
 
 Third argument DOC is the face documentation.
 
-If FACE has been set with `custom-set-faces', set the face attributes
-as specified by that function, otherwise set the face attributes
-according to SPEC.
-
-The remaining arguments should have the form
-
-   [KEYWORD VALUE]...
+If FACE has been set with `custom-set-faces', set the face
+attributes as specified by that function, otherwise set the face
+attributes according to SPEC.
 
+The remaining arguments should have the form [KEYWORD VALUE]...
 For a list of valid keywords, see the common keywords listed in
 `defcustom'.
 
-SPEC should be an alist of the form ((DISPLAY ATTS)...).
-
-In the first element, DISPLAY can be `default'.  The ATTS in that
-element then act as defaults for all the following elements.
-
-Aside from that, DISPLAY specifies conditions to match some or
-all frames.  For each frame, the first element of SPEC where the
-DISPLAY conditions are satisfied is the one that applies to that
-frame.  The ATTRs in this element take effect, and the following
-elements are ignored, on that frame.
-
-In the last element, DISPLAY can be t.  That element applies to a
-frame if none of the previous elements (except the `default' if
-any) did.
-
-ATTS is a list of face attributes followed by their values:
-  (ATTR VALUE ATTR VALUE...)
-
-The possible attributes are `:family', `:width', `:height', `:weight',
-`:slant', `:underline', `:overline', `:strike-through', `:box',
-`:foreground', `:background', `:stipple', `:inverse-video', and `:inherit'.
-
-DISPLAY can be `default' (only in the first element), the symbol
-t (only in the last element) to match all frames, or an alist of
-conditions of the form \(REQ ITEM...).  For such an alist to
-match a frame, each of the conditions must be satisfied, meaning
-that the REQ property of the frame must match one of the
-corresponding ITEMs.  These are the defined REQ values:
-
-`type' (the value of `window-system')
-  Under X, in addition to the values `window-system' can take,
-  `motif', `lucid', `gtk' and `x-toolkit' are allowed, and match when
-  the Motif toolkit, Lucid toolkit, GTK toolkit or any X toolkit is in use.
-
-`class' (the frame's color support)
-  Should be one of `color', `grayscale', or `mono'.
-
-`background' (what color is used for the background text)
-  Should be one of `light' or `dark'.
-
-`min-colors' (the minimum number of colors the frame should support)
-  Should be an integer, it is compared with the result of
-  `display-color-cells'.
-
-`supports' (only match frames that support the specified face attributes)
-  Should be a list of face attributes.  See the documentation for
-  the function `display-supports-face-attributes-p' for more
-  information on exactly how testing is done.
-
-See Info node `(elisp) Customization' in the Emacs Lisp manual
-for more information."
+SPEC should be an alist of the form
+
+   ((DISPLAY . ATTS)...)
+
+where DISPLAY is a form specifying conditions to match certain
+terminals and ATTS is a property list (ATTR VALUE ATTR VALUE...)
+specifying face attributes and values for frames on those
+terminals.  On each terminal, the first element with a matching
+DISPLAY specification takes effect, and the remaining elements in
+SPEC are disregarded.
+
+As a special exception, in the first element of SPEC, DISPLAY can
+be the special value `default'.  Then the ATTS in that element
+act as defaults for all the following elements.
+
+For backward compatibility, elements of SPEC can be written
+as (DISPLAY ATTS) instead of (DISPLAY . ATTS).
+
+Each DISPLAY can have the following values:
+ - `default' (only in the first element).
+ - The symbol t, which matches all terminals.
+ - An alist of conditions.  Each alist element must have the form
+   (REQ ITEM...).  A matching terminal must satisfy each
+   specified condition by matching one of its ITEMs.  Each REQ
+   must be one of the following:
+   - `type' (the terminal type).
+     Each ITEM must be one of the values returned by
+     `window-system'.  Under X, additional allowed values are
+     `motif', `lucid', `gtk' and `x-toolkit'.
+   - `class' (the terminal's color support).
+     Each ITEM should be one of `color', `grayscale', or `mono'.
+   - `background' (what color is used for the background text)
+     Each ITEM should be one of `light' or `dark'.
+   - `min-colors' (the minimum number of supported colors)
+     Each ITEM should be an integer, which is compared with the
+     result of `display-color-cells'.
+   - `supports' (match terminals supporting certain attributes).
+     Each ITEM should be a list of face attributes.  See
+     `display-supports-face-attributes-p' for more information on
+     exactly how testing is done.
+
+In the ATTS property list, possible attributes are `:family',
+`:width', `:height', `:weight', `:slant', `:underline',
+`:overline', `:strike-through', `:box', `:foreground',
+`:background', `:stipple', `:inverse-video', and `:inherit'.
+
+See Info node `(elisp) Faces' in the Emacs Lisp manual for more
+information."
   (declare (doc-string 3))
   ;; It is better not to use backquote in this file,
   ;; because that makes a bootstrapping problem