From: Chong Yidong Date: Sat, 9 Jun 2012 06:26:46 +0000 (+0800) Subject: Doc improvements for face remapping. X-Git-Tag: emacs-24.2.90~1199^2~474^2~79 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=6175e34b61bb75d18a91d4774c629fb6fb28ab32;p=emacs.git Doc improvements for face remapping. * face-remap.el (face-remap-add-relative, face-remap-set-base) (buffer-face-set, buffer-face-toggle, buffer-face-mode-invoke): Doc fixes. * doc/lispref/display.texi (Face Remapping): Minor clarification. * doc/lispref/text.texi (Special Properties): Clarify the meaning of a list of faces in the `face' property. Fixes: debbugs:11225 --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 3c9f26d6a24..cbe081ca6b4 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,10 @@ +2012-06-09 Chong Yidong + + * text.texi (Special Properties): Clarify the meaning of a list of + faces in the `face' property. + + * display.texi (Face Remapping): Minor clarification. + 2012-06-08 Chong Yidong * display.texi (Face Attributes): Font family does not accept diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 53e800bfbf0..3725b6fd820 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -2511,39 +2511,34 @@ Scale,,, emacs, The GNU Emacs Manual}). The value of this variable is an alist whose elements have the form @code{(@var{face} . @var{remapping})}. This causes Emacs to display 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 name, or a property list of attribute/value pairs, or a list in -which each element is either a face name or a property list -(@pxref{Special Properties}). +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. If @code{face-remapping-alist} is buffer-local, its local value takes effect only within that buffer. -Two points bear emphasizing: - -@enumerate -@item -@var{remapping} serves as the complete specification for the remapped -face---it replaces the normal definition of @var{face}, instead of -modifying it. - -@item -If @var{remapping} references the same face name @var{face}, either -directly or via the @code{:inherit} attribute of some other face in -@var{remapping}, that reference uses the normal definition of -@var{face}. In other words, the remapping cannot be recursive. +Note: face remapping is non-recursive. If @var{remapping} references +the same face name @var{face}, either directly or via the +@code{:inherit} attribute of some other face in @var{remapping}, that +reference uses the normal definition of @var{face}. For instance, if +the @code{mode-line} face is remapped using this entry in +@code{face-remapping-alist}: -For instance, if the @code{mode-line} face is remapped using this -entry in @code{face-remapping-alist}: @example (mode-line italic mode-line) @end example + @noindent then the new definition of the @code{mode-line} face inherits from the @code{italic} face, and the @emph{normal} (non-remapped) definition of @code{mode-line} face. -@end enumerate @end defvar The following functions implement a higher-level interface to diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index e2bdc707c5b..63a6d2cbab3 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -3004,7 +3004,11 @@ time you want to specify a particular attribute for certain text. @xref{Face Attributes}. @item -A list, where each element uses one of the two forms listed above. +A list of faces. 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). @end itemize Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 72a9cb352a5..d75a1d52799 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,9 @@ +2012-06-09 Chong Yidong + + * face-remap.el (face-remap-add-relative, face-remap-set-base) + (buffer-face-set, buffer-face-toggle, buffer-face-mode-invoke): + Doc fixes (Bug#11225). + 2012-06-09 Stefan Monnier * emacs-lisp/macroexp.el (macroexp--expand-all): Only autoload diff --git a/lisp/face-remap.el b/lisp/face-remap.el index 46dad0fca3a..be2207a993f 100644 --- a/lisp/face-remap.el +++ b/lisp/face-remap.el @@ -109,14 +109,19 @@ The list structure of ENTRY may be destructively modified." Return a cookie which can be used to delete this remapping with `face-remap-remove-relative'. -The remaining arguments, SPECS, should be either a list of face -names, or a property list of face attribute/value pairs. The -remapping specified by SPECS takes effect alongside the -remappings from other calls to `face-remap-add-relative', as well -as the normal definition of FACE (at lowest priority). This -function tries to sort multiple remappings for the same face, so -that remappings specifying relative face attributes are applied -after remappings specifying absolute face attributes. +The remaining arguments, SPECS, should form a list of faces. +Each list element should be either a face name or a property list +of face attribute/value pairs. If more than one face is listed, +that specifies an aggregate face, in the same way as in a `face' +text property, except for possible priority changes noted below. + +The face remapping specified by SPECS takes effect alongside the +remappings from other calls to `face-remap-add-relative' for the +same FACE, as well as the normal definition of FACE (at lowest +priority). This function tries to sort multiple remappings for +the same face, so that remappings specifying relative face +attributes are applied after remappings specifying absolute face +attributes. The base (lowest priority) remapping may be set to something other than the normal definition of FACE via `face-remap-set-base'." @@ -165,9 +170,11 @@ to apply on top of the normal definition of FACE." (defun face-remap-set-base (face &rest specs) "Set the base remapping of FACE in the current buffer to SPECS. This causes the remappings specified by `face-remap-add-relative' -to apply on top of the face specification given by SPECS. SPECS -should be either a list of face names, or a property list of face -attribute/value pairs. +to apply on top of the face specification given by SPECS. + +The remaining arguments, SPECS, should form a list of faces. +Each list element should be either a face name or a property list +of face attribute/value pairs, like in a `face' text property. If SPECS is empty, call `face-remap-reset-base' to use the normal definition of FACE as the base remapping; note that this is @@ -361,12 +368,14 @@ variable `buffer-face-mode-face' is used to display the buffer text." ;;;###autoload (defun buffer-face-set (&rest specs) "Enable `buffer-face-mode', using face specs SPECS. -SPECS can be any value suitable for the `face' text property, -including a face name, a list of face names, or a face-attribute -If SPECS is nil, then `buffer-face-mode' is disabled. - -This function will make the variable `buffer-face-mode-face' -buffer local, and set it to FACE." +Each argument in SPECS should be a face, i.e. either a face name +or a property list of face attributes and values. If more than +one face is listed, that specifies an aggregate face, like in a +`face' text property. If SPECS is nil or omitted, disable +`buffer-face-mode'. + +This function makes the variable `buffer-face-mode-face' buffer +local, and sets it to FACE." (interactive (list (read-face-name "Set buffer face"))) (while (and (consp specs) (null (cdr specs))) (setq specs (car specs))) @@ -378,8 +387,10 @@ buffer local, and set it to FACE." ;;;###autoload (defun buffer-face-toggle (&rest specs) "Toggle `buffer-face-mode', using face specs SPECS. -SPECS can be any value suitable for the `face' text property, -including a face name, a list of face names, or a face-attribute +Each argument in SPECS should be a face, i.e. either a face name +or a property list of face attributes and values. If more than +one face is listed, that specifies an aggregate face, like in a +`face' text property. If `buffer-face-mode' is already enabled, and is currently using the face specs SPECS, then it is disabled; if buffer-face-mode is @@ -402,10 +413,12 @@ buffer local, and set it to SPECS." ARG controls whether the mode is enabled or disabled, and is interpreted in the usual manner for minor-mode commands. -SPECS can be any value suitable for the `face' text property, -including a face name, a list of face names, or a face-attribute +SPECS can be any value suitable for a `face' text property, +including a face name, a plist of face attributes and values, or +a list of faces. -If INTERACTIVE is non-nil, a message will be displayed describing the result. +If INTERACTIVE is non-nil, display a message describing the +result. This is a wrapper function which calls `buffer-face-set' or `buffer-face-toggle' (depending on ARG), and prints a status