Manual fixes for frame-background-mode.

* doc/custom.texi (Face Customization): Move discussion of face
inheritance here, from Faces section.

* doc/display.texi (Faces): Document frame-background-mode.

* doc/lispref/display.texi (Defining Faces): Move documentation of
frame-background-mode to the Emacs manual (Bug#7774).

5 files changed, 34 insertions, 19 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index c753ab5a1a2..3f3592e64c9 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,10 @@
+2012-08-05  Chong Yidong  <cyd@gnu.org>
+
+	* display.texi (Faces): Document frame-background-mode (Bug#7774).
+
+	* custom.texi (Face Customization): Move discussion of face
+	inheritance here, from Faces section.
+
 2012-07-21  Eli Zaretskii  <eliz@gnu.org>
 
 	* frames.texi (Mouse Commands): Fix the description of mouse-2.
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 2da70227c29..68219d7890f 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -450,11 +450,14 @@ attribute; an empty checkbox, @samp{[ ]}, means that the face does not
 specify any special value for the attribute.  You can activate a
 checkbox to specify or unspecify its attribute.
 
-  Most faces only specify a few attributes (in the above example,
-@code{font-lock-comment-face} only specifies the foreground color).
-Emacs has a special face, @code{default}, whose attributes are all
-specified; it determines the attributes left unspecified by other
-faces.
+  A face does not have to specify every single attribute; in fact,
+most faces only specify a few attributes.  In the above example,
+@code{font-lock-comment-face} only specifies the foreground color.
+Any unspecified attribute is taken from the special face named
+@code{default}, whose attributes are all specified.  The
+@code{default} face is the face used to display any text that does not
+have an explicitly-assigned face; furthermore, its background color
+attribute serves as the background color of the frame.
 
   The @samp{Hide Unused Attributes} button, at the end of the
 attribute list, hides the unspecified attributes of the face.  When
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index 2fa71127298..2238570eaa9 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -475,18 +475,26 @@ type @kbd{M-x list-faces-display}.  With a prefix argument, this
 prompts for a regular expression, and displays only faces with names
 matching that regular expression (@pxref{Regexps}).
 
+@vindex frame-background-mode
   It's possible for a given face to look different in different
 frames.  For instance, some text terminals do not support all face
 attributes, particularly font, height, and width, and some support a
-limited range of colors.
+limited range of colors.  In addition, most Emacs faces are defined so
+that their attributes are different on light and dark frame
+backgrounds, for reasons of legibility.  By default, Emacs
+automatically chooses which set of face attributes to display on each
+frame, based on the frame's current background color.  However, you
+can override this by giving the variable @code{frame-background-mode}
+a non-@code{nil} value.  A value of @code{dark} makes Emacs treat all
+frames as if they have a dark background, whereas a value of
+@code{light} makes it treat all frames as if they have a light
+background.
 
 @cindex background color
 @cindex default face
-  You can customize a face to alter its appearance, and save those
-changes for future Emacs sessions.  @xref{Face Customization}.  A face
-does not have to specify every single attribute; often it inherits
-most attributes from another face.  Any ultimately unspecified
-attribute is taken from the face named @code{default}.
+  You can customize a face to alter its attributes, and save those
+customizations for future Emacs sessions.  @xref{Face Customization},
+for details.
 
   The @code{default} face is the default for displaying text, and all
 of its attributes are specified.  Its background color is also used as
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 52007d3493f..c262cecb02c 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2012-08-05  Chong Yidong  <cyd@gnu.org>
+
+	* display.texi (Defining Faces): Move documentation of
+	frame-background-mode to the Emacs manual (Bug#7774).
+
 2012-08-04  Chong Yidong  <cyd@gnu.org>
 
 	* syntax.texi (Syntax Basics): Rearrange the text for clarity.
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 01d177feb87..64aa891e56b 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2040,14 +2040,6 @@ function, which is used to apply customized face settings.
 specify a face to use.  In the vast majority of cases, this is not
 necessary; it is preferable to simply use faces directly.
 
-@defopt frame-background-mode
-This option, if non-@code{nil}, specifies the background type to use for
-interpreting face definitions.  If it is @code{dark}, then Emacs treats
-all frames as if they had a dark background, regardless of their actual
-background colors.  If it is @code{light}, then Emacs treats all frames
-as if they had a light background.
-@end defopt
-
 @node Face Attributes
 @subsection Face Attributes
 @cindex face attributes