Document new Emacs 24 faces in Lisp manual.

* doc/lispref/display.texi (Basic Faces): New node.  Document new faces.

* doc/lispref/modes.texi (Major Mode Conventions): Move some text there.
(Mode Help): Remove major-mode var, duplicated in Major Modes.

6 files changed, 74 insertions, 36 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 57dde5ac4cb..37689c16e59 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,10 @@
+2011-08-30  Chong Yidong  <cyd@stupidchicken.com>
+
+	* display.texi (Basic Faces): New node.  Document new faces.
+
+	* modes.texi (Major Mode Conventions): Move some text there.
+	(Mode Help): Remove major-mode var, duplicated in Major Modes.
+
 2011-08-29  Chong Yidong  <cyd@stupidchicken.com>
 
 	* modes.texi (Basic Major Modes): New node.  Callers updated.
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index cfe4b8298fb..68291319ef1 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1833,9 +1833,10 @@ particular face name a special meaning in one frame if you wish.
 * 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.
+* Face Remapping::      Remapping faces to alternative definitions.
 * Face Functions::      How to define and examine faces.
 * Auto Faces::          Hook for automatic face assignment.
+* Basic Faces::         Faces that are defined by default.
 * Font Selection::      Finding the best available font for a face.
 * Font Lookup::         Looking up the names of available fonts
                           and information about them.
@@ -2687,6 +2688,62 @@ For efficiency, we recommend writing these functions so that they
 usually assign faces to around 400 to 600 characters at each call.
 @end defvar
 
+@node Basic Faces
+@subsection Basic Faces
+
+If your Emacs Lisp program needs to assign some faces to text, it is
+often a good idea to use certain existing faces or inherit from them,
+rather than defining entirely new faces.  This way, if other users
+have customized the basic faces to give Emacs a certain look, your
+program will ``fit in'' without additional customization.
+
+  Some of the basic faces defined in Emacs are listed below.  In
+addition to these, you might want to make use of the Font Lock faces
+for syntactic highlighting, if highlighting is not already handled by
+Font Lock mode, or if some Font Lock faces are not in use.
+@xref{Faces for Font Lock}.
+
+@table @code
+@item default
+The default face, whose attributes are all specified.  All other faces
+implicitly inherit from it: any unspecified attribute defaults to the
+attribute on this face (@pxref{Face Attributes}).
+
+@item bold
+@itemx italic
+@itemx bold-italic
+@itemx underline
+@itemx fixed-pitch
+@itemx variable-pitch
+These have the attributes indicated by their names (e.g. @code{bold}
+has a bold @code{:weight} attribute), with all other attributes
+unspecified (and so given by @code{default}).
+
+@item shadow
+For ``dimmed out'' text.  For example, it is used for the ignored
+part of a filename in the minibuffer (@pxref{Minibuffer File,,
+Minibuffers for File Names, emacs, The GNU Emacs Manual}).
+
+@item link
+@itemx link-visited
+For clickable text buttons that send the user to a different
+buffer or ``location''.
+
+@item highlight
+For stretches of text that should temporarily stand out.  For example,
+it is commonly assigned to the @code{mouse-face} property for cursor
+highlighting (@pxref{Special Properties}).
+
+@item match
+For text matching a search command.
+
+@item error
+@itemx warning
+@itemx success
+For text concerning errors, warnings, or successes.  For example,
+these are used for messages in @samp{*Compilation*} buffers.
+@end table
+
 @node Font Selection
 @subsection Font Selection
 
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index a19af903027..bcf6d3318ef 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1308,6 +1308,7 @@ Faces
 * Face Remapping::         Remapping faces to alternative definitions.
 * Face Functions::          How to define and examine faces.
 * Auto Faces::              Hook for automatic face assignment.
+* Basic Faces::         Faces that are defined by default.
 * Font Selection::          Finding the best available font for a face.
 * Font Lookup::             Looking up the names of available fonts
                               and information about them.
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 586fc0bbbfb..eb81ebc4acb 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -225,9 +225,9 @@ several major modes, in files such as @file{text-mode.el},
 study these libraries to see how modes are written.
 
 @defopt major-mode
-The buffer-local value of this variable is a symbol naming the buffer's
-current major mode.  Its default value holds the default major mode for
-new buffers.  The standard default value is @code{fundamental-mode}.
+The buffer-local value of this variable holds the symbol for the current
+major mode.  Its default value holds the default major mode for new
+buffers.  The standard default value is @code{fundamental-mode}.
 
 If the default value is @code{nil}, then whenever Emacs creates a new
 buffer via a command such as @kbd{C-x b} (@code{switch-to-buffer}), the
@@ -403,28 +403,7 @@ setting up a buffer-local value for the variable
 
 @item
 Each face that the mode defines should, if possible, inherit from an
-existing Emacs face.  This reduces the chance of conflicting with a
-user's face customizations.  Useful faces include:
-
-@table @asis
-@item @code{highlight}
-for stretches of text that should temporarily stand out.
-
-@item @code{match}
-for text matching a search command.
-
-@item @code{link} and @code{link-visited}
-for clickable text buttons that send the user to a different buffer or
-``location''.
-
-@item @code{button}
-for clickable text buttons that perform other actions.
-
-@item @asis{Font Lock faces}
-for other kinds of syntactic highlighting, if highlighting is not
-handled by Font Lock mode or some Font Lock faces are not in use.
-@xref{Faces for Font Lock}, for how to assign Font Lock faces.
-@end table
+existing Emacs face.  @xref{Basic Faces}, and @ref{Faces for Font Lock}.
 
 @item
 The mode should specify how Imenu should find the definitions or
@@ -702,8 +681,8 @@ init file.)
 
   The @code{describe-mode} function is provides information about major
 modes.  It is normally bound to @kbd{C-h m}.  It uses the value of the
-variable @code{major-mode} (which is why every major mode command needs
-to set this variable).
+variable @code{major-mode} (@pxref{Major Modes}), which is why every
+major mode command needs to set that variable.
 
 @deffn Command describe-mode
 This function displays the documentation of the current major mode.
@@ -714,14 +693,6 @@ displays the documentation string of the major mode command.
 (@xref{Accessing Documentation}.)
 @end deffn
 
-@defvar major-mode
-This buffer-local variable holds the symbol for the current buffer's
-major mode.  This symbol should have a function definition that is the
-command to switch to that major mode.  The @code{describe-mode}
-function uses the documentation string of the function as the
-documentation of the major mode.
-@end defvar
-
 @node Derived Modes
 @subsection Defining Derived Modes
 @cindex derived mode
diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi
index c192e3bf4b7..1275628cc94 100644
--- a/doc/lispref/vol1.texi
+++ b/doc/lispref/vol1.texi
@@ -1329,6 +1329,7 @@ Faces
 * Face Remapping::         Remapping faces to alternative definitions.
 * Face Functions::          How to define and examine faces.
 * Auto Faces::              Hook for automatic face assignment.
+* Basic Faces::             Faces that are defined by default.
 * Font Selection::          Finding the best available font for a face.
 * Font Lookup::             Looking up the names of available fonts
                               and information about them.
diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi
index 8e78a5fb5ca..3d849fa2dcf 100644
--- a/doc/lispref/vol2.texi
+++ b/doc/lispref/vol2.texi
@@ -1328,6 +1328,7 @@ Faces
 * Face Remapping::         Remapping faces to alternative definitions.
 * Face Functions::          How to define and examine faces.
 * Auto Faces::              Hook for automatic face assignment.
+* Basic Faces::             Faces that are defined by default.
 * Font Selection::          Finding the best available font for a face.
 * Font Lookup::             Looking up the names of available fonts
                               and information about them.