Add lisp/face-remap.el and associated documentation

Revision: emacs@sv.gnu.org/emacs--devo--0--patch-1200

4 files changed, 118 insertions, 0 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 1520c26f1e8..314c42d4dff 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,7 @@
+2008-06-03  Miles Bader  <miles@gnu.org>
+
+	* display.texi (Temporary Face Changes): New node.
+
 2008-05-31  Eli Zaretskii  <eliz@gnu.org>
 
 	* msdog.texi (Windows Keyboard): Fix text added on 2008-05-29.
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index b48d6bbab7d..9cf8c986d4a 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -31,6 +31,7 @@ their values only make a difference at the time of redisplay.
 * Cursor Display::         Features for displaying the cursor.
 * Line Truncation::        Truncating lines to fit the screen width instead
                              of continuing them to multiple screen lines.
+* Temporary Face Changes:: Commands to temporarily modify the default text face
 * Display Custom::         Information on variables for customizing display.
 @end menu
 
@@ -1171,6 +1172,41 @@ truncate a line which is exactly as wide as the window.  Instead, the
 newline overflows into the right fringe, and the cursor appears in the
 fringe when positioned on that newline.
 
+@node Temporary Face Changes
+@section Temporary Face Changes
+
+These are commands which temporarily change the default face used to
+display text in a buffer.
+
+@cindex increase buffer face height
+@findex increase-buffer-face-height
+@cindex decrease buffer face height
+@findex decrease-buffer-face-height
+@findex text-scale-mode
+To increase the size of the font used to display text in the current
+buffer, type @kbd{C-=} or @kbd{C-+}
+(@code{increase-buffer-face-height}).  With a numeric prefix argument,
+the size will be increased by that many steps (the default is 1 step);
+each step scales the font height by the value of the variable
+@code{text-scale-mode-step}.  If repeated, this command has a
+cumulative effect.  As a special case, a prefix argument of 0 will
+remove any scaling currently active.
+
+To decrease the size of the text, type @kbd{C--}
+(@code{decrease-buffer-face-height}).  The behavior is similar to that
+of @code{increase-buffer-face-height}, but in reverse.
+
+These commands automatically enable or disable the
+@code{text-scale-mode} minor-mode, depending on whether the current
+font scaling is other than 1 or not.
+
+@cindex variable pitch mode
+@findex variable-pitch-mode
+To temporarily change the display face in the current buffer to a
+variable-pitch (``proportional'') font, use the command @kbd{M-x
+variable-pitch-mode} to enable or disable the Variable Pitch minor
+mode.
+
 @node Display Custom
 @section Customization of Display
 
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 943504fce04..92d49d94a62 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2008-06-03  Miles Bader  <miles@gnu.org>
+
+	* display.texi (Displaying Faces): Add
+	add-relative-face-remapping, remove-relative-face-remapping,
+	set-base-face-remapping, and set-default-base-face-remapping.
+
 2008-06-01  Miles Bader  <miles@gnu.org>
 
 	* display.texi (Displaying Faces): Add face-remapping-alist.
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index bc57cfea26d..ef8f5bc4e5c 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2420,6 +2420,78 @@ with the height doubled:
 
 @end defvar
 
+@noindent
+The following functions implement a somewhat higher-level interface to
+@code{face-remapping-alist}, 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:
+
+@example
+  (@var{face} @var{relative_specs_1} @var{relative_specs_2} @var{...} @var{base_specs})
+@end 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
+@code{remove-relative-face-remapping}.  These are intended for face
+modifications (such as increasing the size).  Typical users of these
+relative specs would be minor modes.
+
+@var{base_specs} 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
+@code{set-base-face-remapping}.  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
+@code{set-base-face-remapping} would be a major mode adding a face
+remappings, e.g., of the default face.
+
+
+@defun 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
+@code{remove-relative-face-remapping}.
+
+@var{specs} 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
+@var{face}, 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.
+@end defun
+
+@defun remove-relative-face-remapping cookie
+This function removes a face remapping previously added by
+@code{add-relative-face-remapping}.  @var{cookie} should be a return
+value from that function.
+@end defun
+
+@defun 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
+@var{face}; 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).
+@end defun
+
+@defun 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.
+@end defun
+
 @node Font Selection
 @subsection Font Selection