[Emacs-diffs] /srv/bzr/emacs/trunk r105617: Document new Emacs 24 faces in Lisp manual.

[Chong Yidong]

------------------------------------------------------------
revno: 105617
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Tue 2011-08-30 11:24:07 -0400
message:
  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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/display.texi
  doc/lispref/elisp.texi
  doc/lispref/modes.texi
  doc/lispref/vol1.texi
  doc/lispref/vol2.texi
  etc/NEWS

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2011-08-29 22:02:21 +0000
+++ b/doc/lispref/ChangeLog     2011-08-30 15:24:07 +0000
@@ -1,3 +1,10 @@
+2011-08-30  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * modes.texi (Basic Major Modes): New node.  Callers updated.

=== modified file 'doc/lispref/display.texi'
--- a/doc/lispref/display.texi  2011-08-28 18:49:59 +0000
+++ b/doc/lispref/display.texi  2011-08-30 15:24:07 +0000
@@ -1833,9 +1833,10 @@
 * 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 @@
 usually assign faces to around 400 to 600 characters at each call.
 @end defvar
 
address@hidden Basic Faces
address@hidden 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.
address@hidden for Font Lock}.
+
address@hidden @code
address@hidden 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}).
+
address@hidden bold
address@hidden italic
address@hidden bold-italic
address@hidden underline
address@hidden fixed-pitch
address@hidden 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}).
+
address@hidden 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}).
+
address@hidden link
address@hidden link-visited
+For clickable text buttons that send the user to a different
+buffer or ``location''.
+
address@hidden 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}).
+
address@hidden match
+For text matching a search command.
+
address@hidden error
address@hidden warning
address@hidden success
+For text concerning errors, warnings, or successes.  For example,
+these are used for messages in @samp{*Compilation*} buffers.
address@hidden table
+
 @node Font Selection
 @subsection Font Selection
 

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2011-08-29 22:02:21 +0000
+++ b/doc/lispref/elisp.texi    2011-08-30 15:24:07 +0000
@@ -1308,6 +1308,7 @@
 * 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.

=== modified file 'doc/lispref/modes.texi'
--- a/doc/lispref/modes.texi    2011-08-29 22:02:21 +0000
+++ b/doc/lispref/modes.texi    2011-08-30 15:24:07 +0000
@@ -225,9 +225,9 @@
 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 @@
 
 @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:
-
address@hidden @asis
address@hidden @code{highlight}
-for stretches of text that should temporarily stand out.
-
address@hidden @code{match}
-for text matching a search command.
-
address@hidden @code{link} and @code{link-visited}
-for clickable text buttons that send the user to a different buffer or
-``location''.
-
address@hidden @code{button}
-for clickable text buttons that perform other actions.
-
address@hidden @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.
address@hidden for Font Lock}, for how to assign Font Lock faces.
address@hidden 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 @@
 
   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 @@
 (@xref{Accessing Documentation}.)
 @end deffn
 
address@hidden 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.
address@hidden defvar
-
 @node Derived Modes
 @subsection Defining Derived Modes
 @cindex derived mode

=== modified file 'doc/lispref/vol1.texi'
--- a/doc/lispref/vol1.texi     2011-08-29 22:02:21 +0000
+++ b/doc/lispref/vol1.texi     2011-08-30 15:24:07 +0000
@@ -1329,6 +1329,7 @@
 * 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.

=== modified file 'doc/lispref/vol2.texi'
--- a/doc/lispref/vol2.texi     2011-08-29 22:02:21 +0000
+++ b/doc/lispref/vol2.texi     2011-08-30 15:24:07 +0000
@@ -1328,6 +1328,7 @@
 * 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.

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2011-08-29 22:02:21 +0000
+++ b/etc/NEWS  2011-08-30 15:24:07 +0000
@@ -239,6 +239,7 @@
 *** Emacs uses GTK tooltips by default if built with GTK.  You can turn that
 off by customizing x-gtk-use-system-tooltips.
 
++++
 ** New basic faces `error', `warning', `success' are available to
 highlight strings that indicate failure, caution or successful operation.