[Emacs-diffs] Changes to emacs/doc/lispref/display.texi,v

[Miles Bader]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Miles Bader <miles>     08/06/03 11:05:53

Index: doc/lispref/display.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/doc/lispref/display.texi,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -b -r1.13 -r1.14
--- doc/lispref/display.texi    1 Jun 2008 05:04:24 -0000       1.13
+++ doc/lispref/display.texi    3 Jun 2008 11:05:52 -0000       1.14
@@ -2420,6 +2420,78 @@
 
 @end defvar
 
address@hidden
+The following functions implement a somewhat higher-level interface to
address@hidden, making it easier to use
+``cooperatively''.  They are mainly intended for buffer-local use, and
+so all make @code{face-remapping-alist} variable buffer-local as a
+side-effect.
+
+These functions use entries in @code{face-remapping-alist} which have
+the general form:
+
address@hidden
+  (@var{face} @var{relative_specs_1} @var{relative_specs_2} @var{...} 
@var{base_specs})
address@hidden example
+
+Everything except the @var{face} is a ``face spec'', a list of face
+names or face attribute-value pairs.  All face specs are merged
+together, with earlier values taking precedence.
+
+The @var{relative_specs_}n values are ``relative specs'', and are
+added by @code{add-relative-face-remapping} (and removed by
address@hidden  These are intended for face
+modifications (such as increasing the size).  Typical users of these
+relative specs would be minor modes.
+
address@hidden is the lowest-priority value, and by default is just the
+face name, which causes the global definition of that face to be used.
+
+A non-default value of @var{base_specs} may also be set using
address@hidden  Because this @emph{overwrites} the
+default base-spec value (which inherits the global face definition),
+it is up to the caller of @code{set-base-face-remapping} to add such
+inheritance if it is desired.  A typical use of
address@hidden would be a major mode adding a face
+remappings, e.g., of the default face.
+
+
address@hidden add-relative-face-remapping face &rest specs
+This functions adds a face remapping entry of @var{face} to @var{specs}
+in the current buffer.
+
+It returns a ``cookie'' which can be used to later delete the remapping with
address@hidden
+
address@hidden can be any value suitable for the @code{face} text
+property, including a face name, a list of face names, or a
+face-attribute property list.  The attributes given by @var{specs}
+will be merged with any other currently active face remappings of
address@hidden, and with the global definition of @var{face} (by default;
+this may be changed using @code{set-base-face-remapping}),
+with the most recently added relative remapping taking precedence.
address@hidden defun
+
address@hidden remove-relative-face-remapping cookie
+This function removes a face remapping previously added by
address@hidden  @var{cookie} should be a return
+value from that function.
address@hidden defun
+
address@hidden set-base-face-remapping face &rest specs
+This function sets the ``base remapping'' of @var{face} in the current
+buffer to @var{specs}.  If @var{specs} is empty, the default base
+remapping is restored, which inherits from the global definition of
address@hidden; note that this is different from @var{specs} containing a
+single value @code{nil}, which has the opposite result (the global
+definition of @var{face} is ignored).
address@hidden defun
+
address@hidden set-default-base-face-remapping face
+This function sets the ``base remapping'' of @var{face} to its default
+value, which inherits from @var{face}'s global definition.
address@hidden defun
+
 @node Font Selection
 @subsection Font Selection