changeset 59492:8732f8552b7d

(Emulating Mode Line): Doc FACE arg in format-header-line.

--- a/lispref/modes.texi	Wed Jan 12 05:06:46 2005 +0000
+++ b/lispref/modes.texi	Wed Jan 12 05:11:05 2005 +0000
@@ -1736,7 +1736,7 @@
 the text that would appear in a mode line or header line
 based on certain mode-line specification.
 
-@defun format-mode-line format &optional window no-props buffer
+@defun format-mode-line format &optional window no-props buffer face
 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
@@ -1746,12 +1746,20 @@
 @var{window}'s buffer.
 
 The value string normally has text properties that correspond to the
-faces, keymaps, etc., that the mode line would have.  If
-@var{no-props} is non-@code{nil}, the value has no text properties.
+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}.)
+
+However, if @var{no-props} is non-@code{nil}, the value has no text
+properties.
 
 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).
+if it has no header line).  @code{(format-mode-line header-line-format
+nil nil nil 'header-line)} returns the same text, with each character
+carrying the face that it will have in the header line itself.
 @end defun
 
 @node Imenu