[Emacs-diffs] master c0f5a3b: Describe and index "empty overlays".

[Eli Zaretskii]

branch: master
commit c0f5a3b3352b748a276cf420b834d677f3d0a671
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    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 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 54fe437..e2a38b6 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
address@hidden 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.
 
address@hidden empty overlay
address@hidden 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 address@hidden, the overlay is deleted automatically
 if it becomes empty (i.e., if its length becomes zero).  If you give
-an empty overlay a address@hidden @code{evaporate} property, that deletes
-it immediately.
+an empty overlay (@pxref{Managing Overlays, empty overlay}) a
address@hidden @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
address@hidden, 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