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.

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 54fe43758a58caa79744fe2be7e112acb93cb921..e2a38b6930a264ce52ceb42b6c7a61ef39494016 100644 (file)
--- 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