From c0f5a3b3352b748a276cf420b834d677f3d0a671 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Mon, 20 Apr 2015 18:46:11 +0300 Subject: [PATCH] Describe and index "empty overlays". * doc/lispref/display.texi (Overlays): Improve indexing. (Managing Overlays): Describe "empty" overlays. (Overlay Properties, Finding Overlays): Add cross-reference to where empty overlays are described. --- doc/lispref/display.texi | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 54fe43758a5..e2a38b6930a 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1310,6 +1310,7 @@ beginning and end. It also has properties that you can examine and set; these affect the display of the text within the overlay. @cindex scalability of overlays +@cindex overlays, scalability The visual effect of an overlay is the same as of the corresponding text property (@pxref{Text Properties}). However, due to a different implementation, overlays generally don't scale well (many operations @@ -1351,6 +1352,15 @@ and @var{end} must specify buffer positions; they may be integers or markers. If @var{buffer} is omitted, the overlay is created in the current buffer. +@cindex empty overlay +@cindex overlay, empty +An overlay whose @var{start} and @var{end} specify the same buffer +position is known as @dfn{empty}. A non-empty overlay can become +empty if the text between its @var{start} and @var{end} is deleted. +When that happens, the overlay is by default not deleted, but you can +cause it to be deleted by giving it the @samp{evaporate} property +(@pxref{Overlay Properties, evaporate property}). + The arguments @var{front-advance} and @var{rear-advance} specify the marker insertion type for the start of the overlay and for the end of the overlay, respectively. @xref{Marker Insertion Types}. If they @@ -1720,8 +1730,11 @@ line at display-time. @xref{Truncation}. @kindex evaporate @r{(overlay property)} If this property is non-@code{nil}, the overlay is deleted automatically if it becomes empty (i.e., if its length becomes zero). If you give -an empty overlay a non-@code{nil} @code{evaporate} property, that deletes -it immediately. +an empty overlay (@pxref{Managing Overlays, empty overlay}) a +non-@code{nil} @code{evaporate} property, that deletes it immediately. +Note that, unless an overlay has this property, it will not be deleted +when the text between its starting and ending positions is deleted +from the buffer. @item keymap @cindex keymap of character (and overlays) @@ -1777,10 +1790,10 @@ overlays that specify property @var{prop} for the character at point: This function returns a list of the overlays that overlap the region @var{beg} through @var{end}. ``Overlap'' means that at least one character is contained within the overlay and also contained within the -specified region; however, empty overlays are included in the result if -they are located at @var{beg}, strictly between @var{beg} and @var{end}, -or at @var{end} when @var{end} denotes the position at the end of the -buffer. +specified region; however, empty overlays (@pxref{Managing Overlays, +empty overlay}) are included in the result if they are located at +@var{beg}, strictly between @var{beg} and @var{end}, or at @var{end} +when @var{end} denotes the position at the end of the buffer. @end defun @defun next-overlay-change pos -- 2.39.5