Commit 35137ed3 authored by Chong Yidong's avatar Chong Yidong
Browse files

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.
parent b1a4f8e1
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.
......
......@@ -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
......
......@@ -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.
......
......@@ -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
......
......@@ -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.
......
......@@ -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.
......
......@@ -239,6 +239,7 @@ theme when Emacs is built with GTK.
*** 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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment