(Image Cache): Document image-refresh.

1 files changed, 36 insertions, 12 deletions

diff --git a/lispref/display.texi b/lispref/display.texi
index f644a02c2eb..81da9f8d6e9 100644
--- a/lispref/display.texi
+++ b/lispref/display.texi
@@ -4276,13 +4276,43 @@ cache, it can always be displayed, even if the value of
 @subsection Image Cache
 @cindex image cache
 
-  Emacs stores images in an image cache when it displays them, so it can
-display them again more efficiently.  It removes an image from the cache
-when it hasn't been displayed for a specified period of time.
+  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.
+
+  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}.
+
+@defun image-refresh spec &optional frame
+This function refreshes any images having 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 all image with image specifications matching
+@var{spec} from the image cache.  Thus, the next time the image is
+displayed, Emacs will load the image again.
+@end defun
+
+@defun clear-image-cache &optional frame
+This function clears the entire image cache.  If @var{frame} is
+non-@code{nil}, only the cache for that frame is cleared.  Otherwise,
+all frames' caches are cleared.
+@end defun
 
-When an image is looked up in the cache, its specification is compared
-with cached image specifications using @code{equal}.  This means that
-all images with equal specifications share the same image in the cache.
+If an image in the image cache has not been displayed for a specified
+period of time, Emacs removes it from the cache and frees the
+associated memory.
 
 @defvar image-cache-eviction-delay
 This variable specifies the number of seconds an image can remain in the
@@ -4294,12 +4324,6 @@ except when you explicitly clear it.  This mode can be useful for
 debugging.
 @end defvar
 
-@defun clear-image-cache &optional frame
-This function clears the image cache.  If @var{frame} is non-@code{nil},
-only the cache for that frame is cleared.  Otherwise all frames' caches
-are cleared.
-@end defun
-
 @node Buttons
 @section Buttons
 @cindex buttons in buffers