[Emacs-diffs] /srv/bzr/emacs/emacs-23 r100319: Fallout from fixing bug #7587.

[Eli Zaretskii]

------------------------------------------------------------
revno: 100319
committer: Eli Zaretskii <address@hidden>
branch nick: emacs-23
timestamp: Sat 2010-12-18 10:53:28 +0200
message:
  Fallout from fixing bug #7587.
  
   doc/lispref/modes.texi (Emulating Mode Line): Update documentation of
   format-mode-line according to changes that fixed bug #7587.
  
   etc/NEWS: Mention the incompatible change in format-mode-line wrt its
   FACE argument.
modified:
  doc/lispref/ChangeLog
  doc/lispref/modes.texi
  etc/NEWS

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2010-12-11 18:45:53 +0000
+++ b/doc/lispref/ChangeLog     2010-12-18 08:53:28 +0000
@@ -1,3 +1,8 @@
+2010-12-18  Eli Zaretskii  <address@hidden>
+
+       * modes.texi (Emulating Mode Line): Update documentation of
+       format-mode-line according to changes that fixed bug #7587.
+
 2010-12-11  Eli Zaretskii  <address@hidden>
 
        * processes.texi (Shell Arguments):

=== modified file 'doc/lispref/modes.texi'
--- a/doc/lispref/modes.texi    2010-12-07 19:44:38 +0000
+++ b/doc/lispref/modes.texi    2010-12-18 08:53:28 +0000
@@ -2111,29 +2111,43 @@
 based on a certain mode-line specification.
 
 @defun format-mode-line format &optional face window buffer
-This function formats a line of text according to @var{format} as if
-it were generating the mode line for @var{window}, but instead of
-displaying the text in the mode line or the header line, it returns
-the text as a string.  The argument @var{window} defaults to the
-selected window.  If @var{buffer} is address@hidden, all the
-information used is taken from @var{buffer}; by default, it comes from
address@hidden's buffer.
+This function formats a line of text according to @var{format} as if it
+were generating the mode line for @var{window}, but it also returns the
+text as a string.  The argument @var{window} defaults to the selected
+window.  If @var{buffer} is address@hidden, all the information used is
+taken from @var{buffer}; by default, it comes from @var{window}'s
+buffer.
 
 The value string normally has text properties that correspond to the
 faces, keymaps, etc., that the mode line would have.  And any character
-for which no @code{face} property is specified gets a default
-value which is usually @var{face}.  (If @var{face} is @code{t},
-that stands for either @code{mode-line} if @var{window} is selected,
-otherwise @code{mode-line-inactive}.  If @var{face} is @code{nil} or
-omitted, that stands for no face property.)
+for which no @code{face} property is specified gets a default value
+determined by @var{face}.  If @var{face} is @code{t}, that stands for
+either @code{mode-line} if @var{window} is selected, otherwise
address@hidden  If @var{face} is @code{nil} or omitted, that
+stands for no face property.
 
 However, if @var{face} is an integer, the value has no text properties.
 
+You can also specify other valid faces as the value of @var{face}.
+If the value is a @dfn{basic face}, one of @code{default}, @code{mode-line},
address@hidden, @code{header-line}, or @code{tool-bar}, that
+face provides the @code{face} property for characters whose face is not
+specified by @var{format}.  Any other face is treated as @code{default},
+but you can remap one of the basic faces (@pxref{Face Remapping}) to get
+the same effect as with non-basic faces.
+
+Note that using @code{mode-line}, @code{mode-line-inactive}, or
address@hidden as @var{face} will actually redisplay the mode line
+or the header line, respectively, using the current definitions of the
+corresponding face, in addition to returning the formatted string.
+(Other faces do not cause redisplay.)
+
 For example, @code{(format-mode-line header-line-format)} returns the
 text that would appear in the selected window's header line (@code{""}
 if it has no header line).  @code{(format-mode-line header-line-format
 'header-line)} returns the same text, with each character
-carrying the face that it will have in the header line itself.
+carrying the face that it will have in the header line itself, and also
+redraws the header line.
 @end defun
 
 @node Imenu

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2010-11-21 18:07:47 +0000
+++ b/etc/NEWS  2010-12-18 08:53:28 +0000
@@ -1845,6 +1845,11 @@
 ** `mode-name' is no longer guaranteed to be a string.
 Use `(format-mode-line mode-name)' to ensure a string value.
 
+** `format-mode-line' now supports only a few basic faces as its FACE argument.
+The FACE argument to `format-mode-line' should be one of `default',
+`mode-line', `mode-line-inactive', `header-line', or `tool-bar'.  Any
+other face is treated as `default'.
+
 ** The function x-font-family-list has been removed.
 Use the new function font-family-list (see Lisp Changes, below).