From: Chong Yidong Date: Sat, 6 Apr 2013 07:39:48 +0000 (+0800) Subject: Improve Lisp manual documentation on setting faces. X-Git-Tag: emacs-24.3.90~173^2^2~42^2~45^2~387^2~2026^2~521 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=cd542620197df6fefe2c2bebca1967ec84e8fa7c;p=emacs.git Improve Lisp manual documentation on setting faces. * display.texi (Faces): Minor clarifications. (Defining Faces): Clarify default vs custom face specs. Document face-spec-set. * display.texi (Overlay Properties): * text.texi (Special Properties): Use the "anonymous face" terminology. Describe foreground-color and background-color forms as compatibility-only. --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index dc6ebb4f35c..0bc2b0880b0 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,14 @@ +2013-04-06 Chong Yidong + + * display.texi (Faces): Minor clarifications. + (Defining Faces): Clarify default vs custom face specs. Document + face-spec-set. + + * display.texi (Overlay Properties): + * text.texi (Special Properties): Use the "anonymous face" + terminology. Describe foreground-color and background-color forms + as compatibility-only. + 2013-03-24 Eli Zaretskii * compile.texi (Byte-Code Objects): Add index entry. diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index eae6af9969d..4adcfdf8f4f 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1510,31 +1510,31 @@ of the symbol serve as defaults for the properties of the overlay. @item face @kindex face @r{(overlay property)} -This property controls the way text is displayed---for example, which -font and which colors. @xref{Faces}, for more information. - -In the simplest case, the value is a face name. It can also be a list; -then each element can be any of these possibilities: +This property controls the appearance of the text (@pxref{Faces}). +The value of the property can be the following: @itemize @bullet @item 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}. +An anonymous face: a property list of the form @code{(@var{keyword} +@var{value} @dots{})}, where each @var{keyword} is a face attribute +name and @var{value} is a value for that attribute. @item -A cons cell, of the form @code{(foreground-color . @var{color-name})} -or @code{(background-color . @var{color-name})}. These elements -specify just the foreground color or just the background color. +A list of faces. Each list element should be either a face name or an +anonymous face. This specifies a face which is an aggregate of the +attributes of each of the listed faces. Faces occurring earlier in +the list have higher priority. -@code{(foreground-color . @var{color-name})} has the same effect as -@code{(:foreground @var{color-name})}; likewise for the background. +@item +A cons cell of the form @code{(foreground-color . @var{color-name})} +or @code{(background-color . @var{color-name})}. This specifies the +foreground or background color, similar to @code{(:foreground +@var{color-name})} or @code{(:background @var{color-name})}. This +form is supported for backward compatibility only, and should be +avoided. @end itemize @item mouse-face @@ -1901,44 +1901,39 @@ height. @section Faces @cindex faces - A @dfn{face} is a collection of graphical @dfn{attributes} for -displaying text: font, foreground color, background color, optional -underlining, etc. Faces control how Emacs displays text in buffers, -as well as other parts of the frame such as the mode line. + A @dfn{face} is a collection of graphical attributes for displaying +text: font, foreground color, background color, optional underlining, +etc. Faces control how Emacs displays text in buffers, as well as +other parts of the frame such as the mode line. @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}. +like @code{(:foreground "red" :weight bold)}. Such a list is called +an @dfn{anonymous face}. For example, you can assign an anonymous +face as the value of the @code{face} text property, and Emacs will +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} +symbol associated with a set of face attributes@footnote{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.}. Named faces are +defined using the @code{defface} macro (@pxref{Defining Faces}). +Emacs comes with several standard named faces (@pxref{Basic Faces}). + + Many parts of Emacs required 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 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 -in all frames. But you can also assign a face name a special set of -attributes in one frame (@pxref{Attribute Functions}). - @menu * Face Attributes:: What is in a face? * Defining Faces:: How to define a face. @@ -2178,32 +2173,47 @@ suitable for use with @code{:stipple} (see above). It returns @node Defining Faces @subsection Defining Faces +@cindex face spec 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}). +This macro associates a face name (a symbol) with a default @dfn{face +spec}. A face spec is a construct which specifies what attributes a +face should have on any given terminal; for example, a face spec might +specify one foreground color on high-color terminals, and a different +foreground color on low-color terminals. + + People are sometimes tempted to create a variable whose value is a +face name. In the vast majority of cases, this is not necessary; the +usual procedure is to define a face with @code{defface}, and then use +its name directly. @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 +This macro declares @var{face} as a named face whose default face spec +is 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}). + +If @var{face} already has a default face spec, this macro does +nothing. + +The default face spec determines @var{face}'s appearance when no +customizations are in effect (@pxref{Customization}). If @var{face} +has already been customized (via Custom themes or via customizations +read from the init file), its appearance is determined by the custom +face spec(s), which override the default face spec @var{spec}. +However, if the customizations are subsequently removed, the +appearance of @var{face} will again be determined by its default face +spec. + +As an exception, if 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 custom face specs on the face, +causing the face to reflect exactly what the @code{defface} says. + +The @var{spec} argument is a @dfn{face spec}, 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}) @@ -2275,7 +2285,8 @@ terminal must match one of the @var{value}s specified for it in @end table @end defmac - Here's how the standard face @code{highlight} is defined: + For example, here's the definition of the standard face +@code{highlight}: @example (defface highlight @@ -2294,65 +2305,56 @@ terminal must match one of the @var{value}s specified for it in :group 'basic-faces) @end example - Internally, Emacs stores the face's default specification in its + Internally, Emacs stores each face's default spec in its @code{face-defface-spec} symbol property (@pxref{Symbol Properties}). -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. +The @code{saved-face} property stores any face spec saved by the user +using the customization buffer; the @code{customized-face} property +stores the face spec 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 the face +specs for that face. The face's documentation string is stored in the +@code{face-documentation} property. + + Normally, a face is declared just once, using @code{defface}, and +any further changes to its appearance are applied using the Customize +framework (e.g., via the Customize user interface or via the +@code{custom-set-faces} function; @pxref{Applying Customizations}), or +by face remapping (@pxref{Face Remapping}). In the rare event that +you need to change a face spec directly from Lisp, you can use the +@code{face-spec-set} function. + +@defun face-spec-set face spec &optional spec-type +This function applies @var{spec} as a face spec for @code{face}. +@var{spec} should be a face spec, as described in the above +documentation for @code{defface}. + +@cindex override spec @r{(for a face)} +The argument @var{spec-type} determines which spec to set. If it is +@code{nil} or @code{face-override-spec}, this function sets the +@dfn{override spec}, which overrides over all other face specs on +@var{face}. If it is @code{face-defface-spec}, this function sets the +default face spec (the same one set by @code{defface}). If it is +@code{reset}, this function clears out all customization specs and +override specs from @var{face} (in this case, the value of @var{spec} +is ignored). Any other value of @var{spec-type} is reserved for +internal use. +@end defun @node Attribute Functions @subsection Face Attribute Functions - This section describes the functions for accessing and modifying the -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 -@var{frame}. The attributes you specify this way override whatever -the @code{defface} says. - -The extra arguments @var{arguments} specify the attributes to set, and -the values for them. They should consist of alternating attribute -names (such as @code{:family} or @code{:underline}) and values. Thus, - -@example -(set-face-attribute 'foo nil - :width 'extended - :weight 'bold) -@end example - -@noindent -sets the attribute @code{:width} to @code{extended} and the attribute -@code{:weight} to @code{bold}. - -If @var{frame} is @code{t}, this function sets the default attributes -for new frames. Default attribute values specified this way override -the @code{defface} for newly created frames. - -If @var{frame} is @code{nil}, this function sets the attributes for -all existing frames, and the default for new frames. -@end defun + This section describes functions for directly accessing and +modifying the attributes of a named face. @defun face-attribute face attribute &optional frame inherit -This returns the value of the @var{attribute} attribute of @var{face} -on @var{frame}. If @var{frame} is @code{nil}, that means the selected -frame (@pxref{Input Focus}). +This function returns the value of the @var{attribute} attribute for +@var{face} on @var{frame}. -If @var{frame} is @code{t}, this returns whatever new-frames default -value you previously specified with @code{set-face-attribute} for the -@var{attribute} attribute of @var{face}. If you have not specified -one, it returns @code{nil}. +If @var{frame} is @code{nil}, that means the selected frame +(@pxref{Input Focus}). If @var{frame} is @code{t}, this function +returns the value of the specified attribute for newly-created frames +(this is normally @code{unspecified}, unless you have specified some +value using @code{set-face-attribute}; see below). If @var{inherit} is @code{nil}, only attributes directly defined by @var{face} are considered, so the return value may be @@ -2409,6 +2411,36 @@ If @var{value1} is a relative value for the face attribute @var{attribute}, returns it merged with the underlying value @var{value2}; otherwise, if @var{value1} is an absolute value for the face attribute @var{attribute}, returns @var{value1} unchanged. +@end defun + + Normally, Emacs uses the face specs of each face to automatically +calculate its attributes on each frame (@pxref{Defining Faces}). The +function @code{set-face-attribute} can override this calculation by +directly assigning attributes to a face, either on a specific frame or +for all frames. This function is mostly intended for internal usage. + +@defun set-face-attribute face frame &rest arguments +This function sets one or more attributes of @var{face} for +@var{frame}. The attributes specifies in this way override the face +spec(s) belonging to @var{face}. + +The extra arguments @var{arguments} specify the attributes to set, and +the values for them. They should consist of alternating attribute +names (such as @code{:family} or @code{:underline}) and values. Thus, + +@example +(set-face-attribute 'foo nil :weight 'bold :slant 'italic) +@end example + +@noindent +sets the attribute @code{:weight} to @code{bold} and the attribute +@code{:slant} to @code{italic}. + + +If @var{frame} is @code{t}, this function sets the default attributes +for newly created frames. If @var{frame} is @code{nil}, this function +sets the attributes for all existing frames, as well as for newly +created frames. @end defun The following commands and functions mostly provide compatibility @@ -2457,16 +2489,17 @@ This sets the @code{:inverse-video} attribute of @var{face} to This swaps the foreground and background colors of face @var{face}. @end deffn - The following functions examine the attributes of a face. If you -don't specify @var{frame}, they refer to the selected frame; @code{t} -refers to the default data for new frames. They return the symbol -@code{unspecified} if the face doesn't define any value for that -attribute. If @var{inherit} is @code{nil}, only an attribute directly -defined by the face is returned. If @var{inherit} is non-@code{nil}, -any faces specified by its @code{:inherit} attribute are considered as -well, and if @var{inherit} is a face or a list of faces, then they are -also considered, until a specified attribute is found. To ensure that -the return value is always specified, use a value of @code{default} for + The following functions examine the attributes of a face. They +mostly provide compatibility with old versions of Emacs. If you don't +specify @var{frame}, they refer to the selected frame; @code{t} refers +to the default data for new frames. They return @code{unspecified} if +the face doesn't define any value for that attribute. If +@var{inherit} is @code{nil}, only an attribute directly defined by the +face is returned. If @var{inherit} is non-@code{nil}, any faces +specified by its @code{:inherit} attribute are considered as well, and +if @var{inherit} is a face or a list of faces, then they are also +considered, until a specified attribute is found. To ensure that the +return value is always specified, use a value of @code{default} for @var{inherit}. @defun face-font face &optional frame @@ -2576,13 +2609,13 @@ The value of this variable is an alist whose elements have the form any text having the face @var{face} with @var{remapping}, rather than the ordinary definition of @var{face}. -@var{remapping} may be any face specification suitable for a -@code{face} text property: either a face (i.e., a face name or a -property list of attribute/value pairs), or a list of faces. For -details, see the description of the @code{face} text property in -@ref{Special Properties}. @var{remapping} serves as the complete -specification for the remapped face---it replaces the normal -definition of @var{face}, instead of modifying it. +@var{remapping} may be any face spec suitable for a @code{face} text +property: either a face (i.e., a face name or a property list of +attribute/value pairs), or a list of faces. For details, see the +description of the @code{face} text property in @ref{Special +Properties}. @var{remapping} serves as the complete specification for +the remapped face---it replaces the normal definition of @var{face}, +instead of modifying it. If @code{face-remapping-alist} is buffer-local, its local value takes effect only within that buffer. @@ -2629,7 +2662,7 @@ and @code{face-remap-reset-base} functions; it is intended for major modes to remap faces in the buffers they control. @defun face-remap-add-relative face &rest specs -This functions adds the face specifications in @var{specs} as relative +This functions adds the face spec in @var{specs} as relative remappings for face @var{face} in the current buffer. The remaining arguments, @var{specs}, should form either a list of face names, or a property list of attribute/value pairs. diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index c6cbfa5b3f8..6d5a39d887a 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -3008,27 +3008,31 @@ character. @item face @cindex face codes of text @kindex face @r{(text property)} -The @code{face} property controls the appearance of the character, -such as its font and color. @xref{Faces}. The value of the property -can be the following: +The @code{face} property controls the appearance of the character +(@pxref{Faces}). The value of the property can be the following: @itemize @bullet @item 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. +An anonymous face: a property list of the form @code{(@var{keyword} +@var{value} @dots{})}, where each @var{keyword} is a face attribute +name and @var{value} is a value for that attribute. @item -A list of faces. This specifies a face which is an aggregate of the +A list of faces. Each list element should be either a face name or an +anonymous face. This specifies a face which is an aggregate of the attributes of each of the listed faces. Faces occurring earlier in -the list have higher priority. Each list element must have one of the -two above forms (i.e., either a face name or a property list of face -attributes). +the list have higher priority. + +@item +A cons cell of the form @code{(foreground-color . @var{color-name})} +or @code{(background-color . @var{color-name})}. This specifies the +foreground or background color, similar to @code{(:foreground +@var{color-name})} or @code{(:background @var{color-name})}. This +form is supported for backward compatibility only, and should be +avoided. @end itemize Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by