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. Fixes: debbugs:11440
This commit is contained in:
Chong Yidong
parent
a11035b8cd
commit
ed1f0bd388
9 changed files with 322 additions and 260 deletions
|
|
@ -1,3 +1,17 @@
|
|||
2012-09-18 Chong Yidong <cyd@gnu.org>
|
||||
|
||||
* 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 <eggert@cs.ucla.edu>
|
||||
|
||||
Simplify, document, and port floating-point (Bug#12381).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
@dfn{customization 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
|
||||
@ifinfo
|
||||
@code{defcustom} macro (@pxref{Variable Definitions});
|
||||
@end ifinfo
|
||||
@ifnotinfo
|
||||
@code{defcustom} macro;
|
||||
@end ifnotinfo
|
||||
customizable faces, which are defined with @code{defface} (described
|
||||
separately in @ref{Defining Faces}); and @dfn{customization groups},
|
||||
defined with
|
||||
@ifinfo
|
||||
@code{defgroup} (@pxref{Group Definitions}),
|
||||
@end ifinfo
|
||||
@ifnotinfo
|
||||
@code{defgroup},
|
||||
@end 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 @@ for declaring customizable faces.
|
|||
|
||||
@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.
|
||||
sections---@code{defcustom}, @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 @@ choice is the official name of the package, such as MH-E or Gnus.
|
|||
@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 @@ confusing names for options and faces.
|
|||
@node Variable Definitions
|
||||
@section Defining Customization Variables
|
||||
@cindex define customization options
|
||||
@cindex customization variables, how to define
|
||||
@cindex customizable variables, how to define
|
||||
@cindex 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
|
||||
@code{defvar} (@pxref{Defining Variables}), customizable variables are
|
||||
defined using the @code{defcustom} macro. In addition to calling
|
||||
@code{defvar} 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 value]@dots{}
|
||||
This macro declares @var{option} as a user option (i.e.@: a
|
||||
|
|
@ -291,13 +319,14 @@ has not been assigned the right value yet. In that case, use
|
|||
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.
|
||||
@xref{Customization Types}, for more information.
|
||||
values are legitimate, and how to display the value
|
||||
(@pxref{Customization Types}).
|
||||
|
||||
@item :options @var{value-list}
|
||||
@kindex options@r{, @code{defcustom} keyword}
|
||||
|
|
|
|||
|
|
@ -1863,20 +1863,36 @@ height.
|
|||
|
||||
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.
|
||||
@xref{Standard Faces,,, emacs, The GNU Emacs Manual}, for the list of
|
||||
faces Emacs normally comes with.
|
||||
underlining, etc. Faces control how Emacs displays text in buffers,
|
||||
as well as other parts of the frame such as the mode line.
|
||||
|
||||
@cindex face id
|
||||
For most purposes, you refer to a face in Lisp programs using its
|
||||
@dfn{face 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.
|
||||
@cindex 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}.
|
||||
|
||||
@cindex 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 non-@code{nil} value if @var{object} is a Lisp
|
||||
symbol or string that names a face. Otherwise, it returns @code{nil}.
|
||||
This function returns a non-@code{nil} 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 @@ in all frames. But you can also assign a face name a special set of
|
|||
attributes in one frame (@pxref{Attribute Functions}).
|
||||
|
||||
@menu
|
||||
* Defining Faces:: How to define a face.
|
||||
* Face Attributes:: What is in a face?
|
||||
* Defining Faces:: How to define 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 @@ attributes in one frame (@pxref{Attribute Functions}).
|
|||
* Low-Level Font:: Lisp representation for character display fonts.
|
||||
@end menu
|
||||
|
||||
@node Defining Faces
|
||||
@subsection 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}).
|
||||
|
||||
@defmac defface face spec doc [keyword value]@dots{}
|
||||
This macro declares @var{face} as a customizable face whose default
|
||||
attributes are given by @var{spec}. You should not quote the symbol
|
||||
@var{face}, 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
|
||||
@var{spec}, 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.
|
||||
|
||||
@cindex 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
|
||||
|
||||
@example
|
||||
(@var{display} . @var{plist})
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
@var{display} specifies a class of terminals (see below), while
|
||||
@var{plist} is a property list of face attributes and their values,
|
||||
specifying how the face appears on such terminals
|
||||
@iftex
|
||||
(see the next section for details about face attributes).
|
||||
@end iftex
|
||||
@ifnottex
|
||||
(@pxref{Face Attributes}, for details about face attributes).
|
||||
@end 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}:
|
||||
|
||||
@table @asis
|
||||
@item @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.
|
||||
|
||||
@item @code{t}
|
||||
This element of @var{spec} matches all frames. Therefore, any
|
||||
subsequent elements of @var{spec} are never used. Normally
|
||||
@code{t} is used in the last (or only) element of @var{spec}.
|
||||
|
||||
@item a list
|
||||
If @var{display} is a list, each element should have the form
|
||||
@code{(@var{characteristic} @var{value}@dots{})}. Here
|
||||
@var{characteristic} specifies a way of classifying frames, and the
|
||||
@var{value}s are possible classifications which @var{display} should
|
||||
apply to. Here are the possible values of @var{characteristic}:
|
||||
|
||||
@table @code
|
||||
@item 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),
|
||||
@code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty}
|
||||
(a non-graphics-capable display).
|
||||
@xref{Window Systems, window-system}.
|
||||
|
||||
@item class
|
||||
What kinds of colors the frame supports---either @code{color},
|
||||
@code{grayscale}, or @code{mono}.
|
||||
|
||||
@item background
|
||||
The kind of background---either @code{light} or @code{dark}.
|
||||
|
||||
@item min-colors
|
||||
An integer that represents the minimum number of colors the frame
|
||||
should support. This matches a frame if its
|
||||
@code{display-color-cells} value is at least the specified integer.
|
||||
|
||||
@item supports
|
||||
Whether or not the frame can display the face attributes given in
|
||||
@var{value}@dots{} (@pxref{Face Attributes}). @xref{Display Face
|
||||
Attribute Testing}, for more information on exactly how this testing
|
||||
is done.
|
||||
@end 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
|
||||
@var{display} 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
|
||||
@var{display}.
|
||||
@end table
|
||||
@end defmac
|
||||
|
||||
Here's how the standard face @code{highlight} is defined:
|
||||
|
||||
@example
|
||||
(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)
|
||||
@end example
|
||||
|
||||
Internally, Emacs stores the face's default specification in its
|
||||
@code{face-defface-spec} 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.
|
||||
@xref{Applying 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 @@ attribute is ignored.
|
|||
@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 @@ The height of the font. In the simplest case, this is an integer in
|
|||
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
|
||||
@ref{Displaying 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 @@ suitable for use with @code{:stipple} (see above). It returns
|
|||
@code{nil} otherwise.
|
||||
@end defun
|
||||
|
||||
@node Defining Faces
|
||||
@subsection 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}).
|
||||
|
||||
@defmac defface face spec doc [keyword value]@dots{}
|
||||
This macro declares @var{face} as a customizable face whose default
|
||||
attributes are given by @var{spec}. You should not quote the symbol
|
||||
@var{face}, 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
|
||||
@var{spec}, 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.
|
||||
|
||||
@cindex 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
|
||||
|
||||
@example
|
||||
(@var{display} . @var{plist})
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
@var{display} 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
|
||||
@var{display}:
|
||||
|
||||
@table @asis
|
||||
@item @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.
|
||||
|
||||
@item @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}.
|
||||
|
||||
@item a list
|
||||
If @var{display} is a list, each element should have the form
|
||||
@code{(@var{characteristic} @var{value}@dots{})}. Here
|
||||
@var{characteristic} specifies a way of classifying terminals, and the
|
||||
@var{value}s are possible classifications which @var{display} should
|
||||
apply to. Here are the possible values of @var{characteristic}:
|
||||
|
||||
@table @code
|
||||
@item 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}.
|
||||
|
||||
@item class
|
||||
What kinds of colors the terminal supports---either @code{color},
|
||||
@code{grayscale}, or @code{mono}.
|
||||
|
||||
@item background
|
||||
The kind of background---either @code{light} or @code{dark}.
|
||||
|
||||
@item min-colors
|
||||
An integer that represents the minimum number of colors the terminal
|
||||
should support. This matches a terminal if its
|
||||
@code{display-color-cells} value is at least the specified integer.
|
||||
|
||||
@item supports
|
||||
Whether or not the terminal can display the face attributes given in
|
||||
@var{value}@dots{} (@pxref{Face Attributes}). @xref{Display Face
|
||||
Attribute Testing}, for more information on exactly how this testing
|
||||
is done.
|
||||
@end 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
|
||||
@var{display} 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
|
||||
@var{display}.
|
||||
@end table
|
||||
@end defmac
|
||||
|
||||
Here's how the standard face @code{highlight} is defined:
|
||||
|
||||
@example
|
||||
(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)
|
||||
@end example
|
||||
|
||||
Internally, Emacs stores the face's default specification in its
|
||||
@code{face-defface-spec} 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.
|
||||
@xref{Applying 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 @@ This function returns the @code{:inverse-video} attribute of face @var{face}.
|
|||
@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 @@ Manual}.
|
|||
|
||||
@item
|
||||
If the text lies within an overlay with a non-@code{nil} @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.
|
||||
@xref{Overlay 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 @@ If any given attribute has not been specified during the preceding
|
|||
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
|
||||
|
|
|
|||
|
|
@ -1366,8 +1366,8 @@ Overlays
|
|||
|
||||
Faces
|
||||
|
||||
* Defining Faces:: How to define a face.
|
||||
* Face Attributes:: What is in a face?
|
||||
* Defining Faces:: How to define a face.
|
||||
* Attribute Functions:: Functions to examine and set face attributes.
|
||||
* Displaying Faces:: How Emacs combines the faces specified for
|
||||
a character.
|
||||
|
|
|
|||
|
|
@ -2999,12 +2999,11 @@ can be the following:
|
|||
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.
|
||||
@xref{Face Attributes}.
|
||||
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.
|
||||
|
||||
@item
|
||||
A list of faces. This specifies a face which is an aggregate of the
|
||||
|
|
|
|||
|
|
@ -403,7 +403,8 @@ unconditionally initializes the variable, whereas @code{defvar}
|
|||
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
|
||||
|
|
|
|||
|
|
@ -1,3 +1,9 @@
|
|||
2012-09-18 Chong Yidong <cyd@gnu.org>
|
||||
|
||||
* custom.el (defface): Doc fix.
|
||||
|
||||
* cus-edit.el (custom-unlispify-remove-prefixes): Add warning.
|
||||
|
||||
2012-09-18 Martin Blais <blais@furius.ca> (tiny change)
|
||||
|
||||
* progmodes/compile.el (compilation-start): Use compilation-always-kill
|
||||
|
|
|
|||
|
|
@ -526,7 +526,10 @@ WIDGET is the widget to apply the filter entries of MENU on."
|
|||
: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)
|
||||
|
|
|
|||
|
|
@ -350,68 +350,62 @@ FACE does not need to be quoted.
|
|||
|
||||
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)...).
|
||||
SPEC should be an alist of the form
|
||||
|
||||
In the first element, DISPLAY can be `default'. The ATTS in that
|
||||
element then act as defaults for all the following elements.
|
||||
((DISPLAY . ATTS)...)
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
ATTS is a list of face attributes followed by their values:
|
||||
(ATTR VALUE ATTR VALUE...)
|
||||
For backward compatibility, elements of SPEC can be written
|
||||
as (DISPLAY ATTS) instead of (DISPLAY . ATTS).
|
||||
|
||||
The possible attributes are `:family', `:width', `:height', `:weight',
|
||||
`:slant', `:underline', `:overline', `:strike-through', `:box',
|
||||
`:foreground', `:background', `:stipple', `:inverse-video', and `:inherit'.
|
||||
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.
|
||||
|
||||
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:
|
||||
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'.
|
||||
|
||||
`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."
|
||||
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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue