[Emacs-diffs] /srv/bzr/emacs/trunk r110084: Doc fixes for defface and friends.

[Chong Yidong]

------------------------------------------------------------
revno: 110084
fixes bug: http://debbugs.gnu.org/11440
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Tue 2012-09-18 13:14:42 +0800
message:
  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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/customize.texi
  doc/lispref/display.texi
  doc/lispref/elisp.texi
  doc/lispref/text.texi
  doc/lispref/variables.texi
  lisp/ChangeLog
  lisp/cus-edit.el
  lisp/custom.el

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-09-11 02:28:27 +0000
+++ b/doc/lispref/ChangeLog     2012-09-18 05:14:42 +0000
@@ -1,3 +1,17 @@
+2012-09-18  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        Simplify, document, and port floating-point (Bug#12381).

=== modified file 'doc/lispref/customize.texi'
--- a/doc/lispref/customize.texi        2012-06-17 05:13:40 +0000
+++ b/doc/lispref/customize.texi        2012-09-18 05:14:42 +0000
@@ -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
address@hidden item} to include customizable variables,
-customization groups, as well as 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.
 
-  @xref{Defining Faces}, for the @code{defface} macro, which is used
-for declaring customizable faces.
+  Customization items include customizable variables, which are
+defined with the
address@hidden
address@hidden macro (@pxref{Variable Definitions});
address@hidden ifinfo
address@hidden
address@hidden macro;
address@hidden ifnotinfo
+customizable faces, which are defined with @code{defface} (described
+separately in @ref{Defining Faces}); and @dfn{customization groups},
+defined with
address@hidden
address@hidden (@pxref{Group Definitions}),
address@hidden ifinfo
address@hidden
address@hidden,
address@hidden 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 @@
 
 @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.
address@hidden, @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 @@
 @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 @@
 @node Variable Definitions
 @section Defining Customization Variables
 @cindex define customization options
address@hidden customization variables, how to define
address@hidden customizable variables, how to define
address@hidden 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
address@hidden (@pxref{Defining Variables}), customizable variables are
+defined using the @code{defcustom} macro.  In addition to calling
address@hidden 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 address@hidden
 This macro declares @var{option} as a user option (i.e.@: a
@@ -291,13 +319,14 @@
 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.
address@hidden Types}, for more information.
+values are legitimate, and how to display the value
+(@pxref{Customization Types}).
 
 @item :options @var{value-list}
 @kindex address@hidden, @code{defcustom} keyword}

=== modified file 'doc/lispref/display.texi'
--- a/doc/lispref/display.texi  2012-08-05 09:24:55 +0000
+++ b/doc/lispref/display.texi  2012-09-18 05:14:42 +0000
@@ -1863,20 +1863,36 @@
 
   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.
address@hidden Faces,,, emacs, The GNU Emacs Manual}, for the list of
-faces Emacs normally comes with.
-
address@hidden face id
-  For most purposes, you refer to a face in Lisp programs using its
address@hidden 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.
+
address@hidden 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}.
+
address@hidden 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 address@hidden value if @var{object} is a Lisp
-symbol or string that names a face.  Otherwise, it returns @code{nil}.
+This function returns a address@hidden 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 @@
 attributes in one frame (@pxref{Attribute Functions}).
 
 @menu
+* Face Attributes::     What is in a face?
 * Defining Faces::      How to define a face.
-* Face Attributes::     What is in 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 @@
 * Low-Level Font::      Lisp representation for character display fonts.
 @end menu
 
address@hidden Defining Faces
address@hidden 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}).
-
address@hidden defface face spec doc [keyword address@hidden
-This macro declares @var{face} as a customizable face whose default
-attributes are given by @var{spec}.  You should not quote the symbol
address@hidden, 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
address@hidden, 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.
-
address@hidden 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
-
address@hidden
-(@var{display} . @var{plist})
address@hidden example
-
address@hidden
address@hidden specifies a class of terminals (see below), while
address@hidden is a property list of face attributes and their values,
-specifying how the face appears on such terminals
address@hidden
-(see the next section for details about face attributes).
address@hidden iftex
address@hidden
-(@pxref{Face Attributes}, for details about face attributes).
address@hidden 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}:
-
address@hidden @asis
address@hidden @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.
-
address@hidden @code{t}
-This element of @var{spec} matches all frames.  Therefore, any
-subsequent elements of @var{spec} are never used.  Normally
address@hidden is used in the last (or only) element of @var{spec}.
-
address@hidden a list
-If @var{display} is a list, each element should have the form
address@hidden(@var{characteristic} @address@hidden)}.  Here
address@hidden specifies a way of classifying frames, and the
address@hidden are possible classifications which @var{display} should
-apply to.  Here are the possible values of @var{characteristic}:
-
address@hidden @code
address@hidden 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),
address@hidden (for MS Windows 9X/NT/2K/XP), or @code{tty} 
-(a non-graphics-capable display).
address@hidden Systems, window-system}.
-
address@hidden class
-What kinds of colors the frame supports---either @code{color},
address@hidden, or @code{mono}.
-
address@hidden background
-The kind of background---either @code{light} or @code{dark}.
-
address@hidden min-colors
-An integer that represents the minimum number of colors the frame
-should support.  This matches a frame if its
address@hidden value is at least the specified integer.
-
address@hidden supports
-Whether or not the frame can display the face attributes given in
address@hidden@dots{} (@pxref{Face Attributes}).  @xref{Display Face
-Attribute Testing}, for more information on exactly how this testing
-is done.
address@hidden 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
address@hidden 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
address@hidden
address@hidden table
address@hidden defmac
-
-  Here's how the standard face @code{highlight} is defined:
-
address@hidden
-(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)
address@hidden example
-
-  Internally, Emacs stores the face's default specification in its
address@hidden 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.
address@hidden 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 @@
 @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 @@
 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
address@hidden 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 @@
 @code{nil} otherwise.
 @end defun
 
address@hidden Defining Faces
address@hidden 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}).
+
address@hidden defface face spec doc [keyword address@hidden
+This macro declares @var{face} as a customizable face whose default
+attributes are given by @var{spec}.  You should not quote the symbol
address@hidden, 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
address@hidden, 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.
+
address@hidden 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
+
address@hidden
+(@var{display} . @var{plist})
address@hidden example
+
address@hidden
address@hidden 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
address@hidden:
+
address@hidden @asis
address@hidden @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.
+
address@hidden @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}.
+
address@hidden a list
+If @var{display} is a list, each element should have the form
address@hidden(@var{characteristic} @address@hidden)}.  Here
address@hidden specifies a way of classifying terminals, and the
address@hidden are possible classifications which @var{display} should
+apply to.  Here are the possible values of @var{characteristic}:
+
address@hidden @code
address@hidden 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}.
+
address@hidden class
+What kinds of colors the terminal supports---either @code{color},
address@hidden, or @code{mono}.
+
address@hidden background
+The kind of background---either @code{light} or @code{dark}.
+
address@hidden min-colors
+An integer that represents the minimum number of colors the terminal
+should support.  This matches a terminal if its
address@hidden value is at least the specified integer.
+
address@hidden supports
+Whether or not the terminal can display the face attributes given in
address@hidden@dots{} (@pxref{Face Attributes}).  @xref{Display Face
+Attribute Testing}, for more information on exactly how this testing
+is done.
address@hidden 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
address@hidden 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
address@hidden
address@hidden table
address@hidden defmac
+
+  Here's how the standard face @code{highlight} is defined:
+
address@hidden
+(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)
address@hidden example
+
+  Internally, Emacs stores the face's default specification in its
address@hidden 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.
address@hidden 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 @@
 @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 @@
 
 @item
 If the text lies within an overlay with a address@hidden @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.
address@hidden 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 @@
 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

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2012-08-04 14:33:00 +0000
+++ b/doc/lispref/elisp.texi    2012-09-18 05:14:42 +0000
@@ -1366,8 +1366,8 @@
 
 Faces
 
+* Face Attributes::         What is in a face?
 * Defining Faces::          How to define a face.
-* Face Attributes::         What is in a face?
 * Attribute Functions::     Functions to examine and set face attributes.
 * Displaying Faces::        How Emacs combines the faces specified for
                               a character.

=== modified file 'doc/lispref/text.texi'
--- a/doc/lispref/text.texi     2012-08-04 14:33:00 +0000
+++ b/doc/lispref/text.texi     2012-09-18 05:14:42 +0000
@@ -2999,12 +2999,11 @@
 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.
address@hidden Attributes}.
+A property list of face attributes.  This has the form (@var{keyword}
address@hidden @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

=== modified file 'doc/lispref/variables.texi'
--- a/doc/lispref/variables.texi        2012-09-07 14:15:59 +0000
+++ b/doc/lispref/variables.texi        2012-09-18 05:14:42 +0000
@@ -403,7 +403,8 @@
 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

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-09-18 04:18:36 +0000
+++ b/lisp/ChangeLog    2012-09-18 05:14:42 +0000
@@ -1,3 +1,9 @@
+2012-09-18  Chong Yidong  <address@hidden>
+
+       * custom.el (defface): Doc fix.
+
+       * cus-edit.el (custom-unlispify-remove-prefixes): Add warning.
+
 2012-09-18  Martin Blais  <address@hidden>  (tiny change)
 
        * progmodes/compile.el (compilation-start): Use compilation-always-kill

=== modified file 'lisp/cus-edit.el'
--- a/lisp/cus-edit.el  2012-08-15 16:29:11 +0000
+++ b/lisp/cus-edit.el  2012-09-18 05:14:42 +0000
@@ -526,7 +526,10 @@
   :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)

=== modified file 'lisp/custom.el'
--- a/lisp/custom.el    2012-09-17 05:41:04 +0000
+++ b/lisp/custom.el    2012-09-18 05:14:42 +0000
@@ -350,68 +350,62 @@
 
 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