* display.texi (Truncation): Overlays can use line-prefix and

wrap-prefix too.
(Overlay Properties): Document wrap-prefix and line-prefix.
(Face Attributes): Document underline-minimum-offset.
(Face Remapping): Copyedits.
(Low-Level Font): Copyedits.
(Image Cache): Note that the image cache is shared between frames.

2 files changed, 75 insertions, 48 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index bac2817b023..073bdc41842 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,13 @@
+2009-04-15  Chong Yidong  <cyd@stupidchicken.com>
+
+        * display.texi (Truncation): Overlays can use line-prefix and
+        wrap-prefix too.
+        (Overlay Properties): Document wrap-prefix and line-prefix.
+        (Face Attributes): Document underline-minimum-offset.
+        (Face Remapping): Copyedits.
+        (Low-Level Font): Copyedits.
+        (Image Cache): Note that the image cache is shared between frames.
+
 2009-04-13  Chong Yidong  <cyd@stupidchicken.com>
 
         * display.texi (Refresh Screen): Note that a passage about screen
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 8fa9a82c6eb..8ef61c31bb5 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -198,26 +198,27 @@ a window, that forces truncation.
 
 @defvar wrap-prefix
 If this buffer-local variable is non-@code{nil}, it defines a
-``prefix'' that is added at display-time to the beginning of every
-continuation line.  (If lines are truncated, the wrap-prefix is never
-used.)  It may be a string, an image, or a stretch-glyph, as used by
-the @code{display} text property.  @xref{Display Property}.
+``prefix'' that is prepended to every continuation line at
+display-time.  (If lines are truncated, the wrap-prefix is never
+used.)  It may be a string, an image, or a stretch-glyph; the value is
+interpreted in the same way as a @code{display} text property.
+@xref{Display Property}.
 
 A wrap-prefix may also be specified for regions of text, using the
-@code{wrap-prefix} text property.  This takes precedence over the
-value of the @code{wrap-prefix} variable.  @xref{Special Properties}.
+@code{wrap-prefix} text or overlay property.  This takes precedence
+over the @code{wrap-prefix} variable.  @xref{Special Properties}.
 @end defvar
 
 @defvar line-prefix
 If this buffer-local variable is non-@code{nil}, it defines a
-``prefix'' that is added at display-time to the beginning of every
-non-continuation line.  It may be a string, an image, or a
-stretch-glyph, as used by the @code{display} text property.
-@xref{Display Property}.
+``prefix'' that is prepended to every non-continuation line at
+display-time.  It may be a string, an image, or a stretch-glyph; the
+value is interpreted in the same way as a @code{display} text
+property.  @xref{Display Property}.
 
 A line-prefix may also be specified for regions of text using the
-@code{line-prefix} text property.  This takes precedence over the
-value of the @code{line-prefix} variable.  @xref{Special Properties}.
+@code{line-prefix} text or overlay property.  This takes precedence
+over the @code{line-prefix} variable.  @xref{Special Properties}.
 @end defvar
 
   If your buffer contains @emph{very} long lines, and you use
@@ -1173,7 +1174,7 @@ text property (@pxref{Text Properties}).  However, due to a different
 implementation, overlays generally don't scale well (many operations
 take a time that is proportional to the number of overlays in the
 buffer).  If you need to affect the visual appearance of many portions
-in the buffer, we recommend to use text properties.
+in the buffer, we recommend using text properties.
 
 An overlay uses markers to record its beginning and end; thus,
 editing the text of the buffer adjusts the beginning and end of each
@@ -1538,6 +1539,14 @@ This property's value is a string to add to the display at the end of
 the overlay.  The string does not appear in the buffer in any
 sense---only on the screen.
 
+@item line-prefix
+This property specifies a display spec to prepend to each
+non-continuation line at display-time.  @xref{Truncation}.
+
+@itemx wrap-prefix
+This property specifies a display spec to prepend to each continuation
+line at display-time.  @xref{Truncation}.
+
 @item evaporate
 @kindex evaporate @r{(overlay property)}
 If this property is non-@code{nil}, the overlay is deleted automatically
@@ -2151,6 +2160,11 @@ optional argument @var{frame} specifies the frame on which the text is
 to be displayed; if it is @code{nil}, the selected frame is used.
 @end defun
 
+@defvar underline-minimum-offset
+This variable specifies the minimum distance between the baseline and
+the underline, in pixels, when displaying underlined text.
+@end defvar
+
 @defvar x-bitmap-file-path
 This variable specifies a list of directories for searching
 for bitmap files, for the @code{:stipple} attribute.
@@ -2454,9 +2468,9 @@ face.
 @item
 If @var{remapping...} recursively references the same face name
 @var{face}, either directly remapping entry, or via the
-@code{:inherit} attribute of some other face in
-@var{remapping...}, then that reference uses normal frame-wide
-definition of @var{face} instead of the ``remapped'' definition.
+@code{:inherit} attribute of some other face in @var{remapping...},
+then that reference uses the normal definition of @var{face} in the
+selected frame, instead of the ``remapped'' definition.
 
 For instance, if the @code{mode-line} face is remapped using this
 entry in @code{face-remapping-alist}:
@@ -2491,9 +2505,9 @@ have the general form:
   (@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.
+Everything except @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{face-remap-add-relative} (and removed by
@@ -2986,11 +3000,7 @@ should be one of @code{font-object}, @code{font-spec}, or
 
   A font object is a Lisp object that represents a font that Emacs has
 @dfn{opened}.  Font objects cannot be modified in Lisp, but they can
-be inspected.  If you call @code{set-face-attribute} and pass a font
-spec, font entity, or font name string as the value of the
-@code{:font} attribute, Emacs opens the best ``matching'' font that is
-available for display.  It then stores the corresponding font object
-as the actual value of the @code{:font} attribute for that face.
+be inspected.
 
 @defun font-at position &optional window string
 Return the font object that is being used to display the character at
@@ -3072,6 +3082,12 @@ entities are sorted in order of decreasing ``closeness'' to that font
 spec.
 @end defun
 
+  If you call @code{set-face-attribute} and pass a font spec, font
+entity, or font name string as the value of the @code{:font}
+attribute, Emacs opens the best ``matching'' font that is available
+for display.  It then stores the corresponding font object as the
+actual value of the @code{:font} attribute for that face.
+
   The following functions can be used to obtain information about a
 font.  For these functions, the @var{font} argument can be a font
 object, a font entity, or a font spec.
@@ -4686,40 +4702,41 @@ cache, it can always be displayed, even if the value of
 @subsection Image Cache
 @cindex image cache
 
-  Emacs stores images in an image cache so that it can display them
-again more efficiently.  When Emacs displays an image, it searches the
-image cache for an existing image specification @code{equal} to the
-desired specification.  If a match is found, the image is displayed
-from the cache; otherwise, Emacs loads the image normally.
+  Emacs caches images so that it can display them again more
+efficiently.  When Emacs displays an image, it searches the image
+cache for an existing image specification @code{equal} to the desired
+specification.  If a match is found, the image is displayed from the
+cache; otherwise, Emacs loads the image normally.
 
   Occasionally, you may need to tell Emacs to refresh the images
 associated with a given image specification.  For example, suppose you
 display an image using a specification that contains a @code{:file}
-property.  The image is loaded from the given file and stored in the
-image cache.  If you later display the image again, using the same
-image specification, the image is displayed from the image cache.
-Normally, this is not a problem.  However, if the image file has
-changed in the meantime, Emacs would be displaying the old version of
-the image.  In such a situation, it is necessary to ``refresh'' the
-image using @code{image-refresh}.
+property.  The image is automatically cached, and subsequent displays
+of that image, with the same image specification, will use the image
+cache.  If the image file changes in the meantime, Emacs would be
+displaying the old version of the image.  In such a situation, you can
+``refresh'' the image by calling @code{image-refresh}.
+
+  In Emacs' current implementation, each graphical terminal possesses
+an image cache, which is shared by all the frames on that terminal
+(@pxref{Multiple Terminals}).  Thus, refreshing an image in one frame
+also refreshes it in all other frames on the same terminal.
 
 @defun image-refresh spec &optional frame
-This function refreshes any images having image specifications
+This function refreshes any images with image specifications
 @code{equal} to @var{spec} on frame @var{frame}.  If @var{frame} is
-@code{nil}, the selected frame is used.  If @var{frame} is @code{t},
-the refresh is applied to all existing frames.
-
-This works by removing from the image cache all the images whose image
-specifications match @var{spec}.  The next time Emacs needs to display
-such an image, it will reload the image anew.
+@code{nil}, it defaults to the selected frame.  If @var{frame} is
+@code{t}, the refresh is applied to all existing frames.
 @end defun
 
 @defun clear-image-cache &optional filter
-This function clears the image cache.  If @var{filter} is
-a frame, only the cache for that frame is cleared.  If omitted or
-@code{nil}, clear the images on the selected frame.  If @code{t},
-all frames' caches are cleared.  Otherwise, @var{filter} is taken as
-a file name and only images that reference this file will be flushed.
+This function clears an image cache, removing all the images stored in
+it.  If @var{filter} is omitted or @code{nil}, it clears the cache for
+the selected frame.  If @var{filter} is a frame, it clears the cache
+for that frame.  If @var{filter} is @code{t}, all image caches are
+cleared.  Otherwise, @var{filter} is taken to be a file name, and all
+images associated with that file name are removed from all image
+caches.
 @end defun
 
 If an image in the image cache has not been displayed for a specified