1 files changed, 31 insertions, 17 deletions
diff --git a/man/display.texi b/man/display.texi
index 6422cbf4eaa..58e69ad4e60 100644
--- a/man/display.texi
+++ b/man/display.texi
@@ -104,14 +104,18 @@ future Emacs versions.
   To see what faces are currently defined, and what they look like,
 type @kbd{M-x list-faces-display}.  It's possible for a given face to
 look different in different frames; this command shows the appearance
-in the frame in which you type it.  Here are the standard faces
-for specifying text appearance:
+in the frame in which you type it.
+
+Here are the standard faces for specifying text appearance.  You can
+use them on specific text, when you want the effects they produce.
 
 @table @code
 @item default
 This face is used for ordinary text that doesn't specify any other face.
 @item bold
 This face uses a bold variant of the default font, if it has one.
+It's up to you to choose a default font that has a bold variant,
+if you want to use one.
 @item italic
 This face uses an italic variant of the default font, if it has one.
 @item bold-italic
@@ -119,9 +123,15 @@ This face uses a bold italic variant of the default font, if it has one.
 @item underline
 This face underlines text.
 @item fixed-pitch
-The basic fixed-pitch face.
+This face forces use of a particular fixed-width font.
 @item variable-pitch
-The basic variable-pitch face.
+This face forces use of a particular variable-width font.  It's
+reasonable to customize this to use a different variable-width font,
+if you like, but you should not make it a fixed-width font.
+@item shadow
+This face is used for making the text less noticeable than the surrounding
+ordinary text.  Usually this can be achieved by using shades of gray in
+contrast with either black or white default foreground color.
 @end table
 
   Here's an incomplete list of faces used to highlight parts of the
@@ -146,19 +156,15 @@ mode is enabled---see below).
 This face is used for displaying a secondary X selection (@pxref{Secondary
 Selection}).
 @item trailing-whitespace
-The face for highlighting trailing whitespace when
-@code{show-trailing-whitespace} is non-@code{nil}; see @ref{Useless
-Whitespace}.
+The face for highlighting excess spaces and tabs at the end of a line
+when @code{show-trailing-whitespace} is non-@code{nil}; see
+@ref{Useless Whitespace}.
 @item nobreak-space
 The face for displaying the character ``nobreak space''.
 @item escape-glyph
 The face for highlighting the @samp{\} or @samp{^} that indicates
 a control character.  It's also used when @samp{\} indicates a
 nobreak space or nobreak (soft) hyphen.
-@item shadow
-The basic face for making the text less noticeable than the surrounding
-ordinary text.  Usually this is achieved by using shades of grey in
-contrast with either black or white default foreground color.
 @end table
 
 @cindex @code{region} face
@@ -175,10 +181,13 @@ appearance of these parts of the frame.
 
 @table @code
 @item mode-line
-This face is used for the mode line of the currently selected window.
-By default, it's drawn with shadows for a ``raised'' effect on window
-systems, and drawn as the inverse of the default face on non-windowed
-terminals.
+@itemx modeline
+This face is used for the mode line of the currently selected window,
+and for menu bars when toolkit menus are not used.  By default, it's
+drawn with shadows for a ``raised'' effect on window systems, and
+drawn as the inverse of the default face on non-windowed terminals.
+@code{modeline} is an alias for the @code{mode-line} face, for
+compatibility with old Emacs versions.
 @item mode-line-inactive
 Like @code{mode-line}, but used for mode lines of the windows other
 than the selected one (if @code{mode-line-in-non-selected-windows} is
@@ -186,7 +195,7 @@ non-@code{nil}).  This face inherits from @code{mode-line}, so changes
 in that face affect mode lines in all windows.
 @item header-line
 Similar to @code{mode-line} for a window's header line.  Most modes
-don't use the header line, but the Info mode does.
+don't use the header line, but some special modes, such the Info mode, do.
 @item vertical-border
 This face is used for the vertical divider between windows.
 By default this face inherits from the @code{mode-line-inactive} face
@@ -194,9 +203,14 @@ on character terminals.  On window systems the foreground color of
 this face is used for the vertical line between windows without
 scrollbars.
 @item minibuffer-prompt
+@cindex @code{minibuffer-prompt} face
+@vindex minibuffer-prompt-properties
 This face is used for the prompt strings displayed in the minibuffer.
+By default, Emacs automatically adds this face to the value of
+@code{minibuffer-prompt-properties}, which is a list of text
+properties used to display the prompt text.
 @item fringe
-@cindex fringe
+@cindex @code{fringe} face
 The face for the fringes to the left and right of windows on graphic
 displays.  (The fringes are the narrow portions of the Emacs frame
 between the text area and the window's right and left borders.)