[Emacs-diffs] emacs/doc/lispref ChangeLog display.texi

[Chong Yidong]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Chong Yidong <cyd>      09/04/15 03:07:07

Modified files:
        doc/lispref    : ChangeLog display.texi 

Log message:
        * 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.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/ChangeLog?cvsroot=emacs&r1=1.259&r2=1.260
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/display.texi?cvsroot=emacs&r1=1.43&r2=1.44

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/ChangeLog,v
retrieving revision 1.259
retrieving revision 1.260
diff -u -b -r1.259 -r1.260
--- ChangeLog   13 Apr 2009 15:54:17 -0000      1.259
+++ ChangeLog   15 Apr 2009 03:07:06 -0000      1.260
@@ -1,3 +1,13 @@
+2009-04-15  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * display.texi (Refresh Screen): Note that a passage about screen

Index: display.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/display.texi,v
retrieving revision 1.43
retrieving revision 1.44
diff -u -b -r1.43 -r1.44
--- display.texi        13 Apr 2009 15:54:17 -0000      1.43
+++ display.texi        15 Apr 2009 03:07:07 -0000      1.44
@@ -198,26 +198,27 @@
 
 @defvar wrap-prefix
 If this buffer-local variable is address@hidden, 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.
address@hidden Property}.
 
 A wrap-prefix may also be specified for regions of text, using the
address@hidden text property.  This takes precedence over the
-value of the @code{wrap-prefix} variable.  @xref{Special Properties}.
address@hidden 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 address@hidden, 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.
address@hidden 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
address@hidden text property.  This takes precedence over the
-value of the @code{line-prefix} variable.  @xref{Special Properties}.
address@hidden 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 @@
 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 @@
 the overlay.  The string does not appear in the buffer in any
 sense---only on the screen.
 
address@hidden line-prefix
+This property specifies a display spec to prepend to each
+non-continuation line at display-time.  @xref{Truncation}.
+
address@hidden 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 address@hidden, the overlay is deleted automatically
@@ -2151,6 +2160,11 @@
 to be displayed; if it is @code{nil}, the selected frame is used.
 @end defun
 
address@hidden underline-minimum-offset
+This variable specifies the minimum distance between the baseline and
+the underline, in pixels, when displaying underlined text.
address@hidden 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 @@
 @item
 If @var{remapping...} recursively references the same face name
 @var{face}, either directly remapping entry, or via the
address@hidden:inherit} attribute of some other face in
address@hidden, then that reference uses normal frame-wide
-definition of @var{face} instead of the ``remapped'' definition.
address@hidden: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 @@
   (@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 @@
 
   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
address@hidden: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 @@
 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 @@
 @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
address@hidden, 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.
address@hidden, it defaults to the selected frame.  If @var{frame} is
address@hidden, 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
address@hidden, 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