From 0d017fc7ce83006eee93402ba0619b5d21906672 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 28 Feb 2026 15:36:07 +0200 Subject: [PATCH] ; Fix the documentation of 'overlays-in' etc. * src/buffer.c (Foverlays_in): * lisp/subr.el (remove-overlays): * doc/lispref/display.texi (Finding Overlays, Managing Overlays): * etc/NEWS: Improve the documentation of recent changes in behavior of 'overlays-in' and 'remove-overlays'. (Bug#80242) --- doc/lispref/display.texi | 11 ++++++++++- etc/NEWS | 15 +++++++++------ lisp/subr.el | 4 ++++ src/buffer.c | 4 +++- 4 files changed, 26 insertions(+), 8 deletions(-) diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index f2e468e4a60..cded3ecd8d0 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1710,6 +1710,12 @@ be altered so that they start at @var{end}. Overlays that start before @var{start} and end after @var{end} will be split into two overlays: one that ends at @var{start} and the other that begins at @var{end}. + +@item +Empty overlays (@pxref{empty overlays}) will be removed if they are +either at @var{start}, or strictly between @var{start} and @var{end} +excluding @var{end}, or at @var{end} when @var{end} denotes the position +at the end of the buffer. @end itemize If @var{name} is omitted or @code{nil}, it means to delete/modify all @@ -2145,7 +2151,10 @@ strictly between @var{beg} and @var{end} excluding @var{end}, or at @var{end} when @var{end} denotes the position at the end of the buffer. (The special handling of empty overlays at end of buffer is to allow such overlays to be found and processed. For any other value of -@var{end} you could increment the @var{end} position instead.) +@var{end} you could increment the @var{end} position instead.) Note +that if @var{beg} and @var{end} are the same position, an empty overlay +that is at @var{beg} is also at @var{end}, so this case is somewhat +similar to an empty overlay at the end of the buffer. The order in which the overlays appear in the returned list is unpredictable. diff --git a/etc/NEWS b/etc/NEWS index 4efd1c9142a..04bf92aa78b 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -3936,12 +3936,15 @@ display time or even cause Emacs to hang trying to display such a face. Affected APIs include 'defface', 'set-face-attribute', their callers, and other similar functions. -+++ -Original behavior of 'overlays-in' and 'overlays-at' has been restored. -Before Emacs 29.1, the list of overlays returned by these two functions -included overlays outside of the current narrowing of the buffer. This -behavior has been restored. As result, 'remove-overlays' can now again -remove overlays outside of the narrowing, as it did before Emacs 29.1. ++++ Original behavior of 'overlays-in' and 'overlays-at' has been +restored. Before Emacs 28.1, the list of overlays returned by these two +functions included overlays outside of the current narrowing of the +buffer, and there wasn't a special exception for including empty +overlays at end of accessible portion of the buffer. This behavior has +been restored, and the special behavior for empty overlays is again +reserved only to the actual end of buffer, disregarding the narrowing. +As result, 'remove-overlays' can now again remove overlays outside of +the narrowing, as it did before Emacs 28.1. --- ** 'help-setup-xref' now re-enables the major mode of the Help buffer. diff --git a/lisp/subr.el b/lisp/subr.el index 4cae2845d96..466b4791c06 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -4451,6 +4451,10 @@ at BEG. Likewise, if the targeted overlays end after END, they will be altered so that they start at END. Overlays that start at or after BEG and end before END will be removed completely. +Empty overlays will be removed if they are at BEG, between BEG +and END, or at END provided END denotes the position at the end +of the buffer. + BEG and END default respectively to the beginning and end of the buffer. Values are compared with `eq'. diff --git a/src/buffer.c b/src/buffer.c index b554cf41874..ec26ff82c78 100644 --- a/src/buffer.c +++ b/src/buffer.c @@ -3927,7 +3927,9 @@ END. Empty overlays do not contain any characters, so they are included in the result if they are located at BEG, between BEG and END, or at END provided -END denotes the position at the end of the buffer. +END denotes the position at the end of the buffer. (If BEG and END are the +same buffer position, an empty overlay at BEG will also be at END, but it +still qualifies because it's at BEG.) The resulting list of overlays is in an arbitrary unpredictable order.