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

1 files changed, 12 insertions, 4 deletions

diff --git a/lispref/modes.texi b/lispref/modes.texi
index 299579a10af..ebedbc520b8 100644
--- a/lispref/modes.texi
+++ b/lispref/modes.texi
@@ -1736,7 +1736,7 @@ It is normally @code{nil}, so that ordinary buffers have no header line.
 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 @@ 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.  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