procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation of 'remove-overlays' in ELisp manual

Browse source 
* doc/lispref/display.texi (Managing Overlays): Update
documentation of 'remove-overlays'.  (Bug#57534)  (Bug#13648)
This commit is contained in:
Eli Zaretskii 2024-06-28 14:52:05 +03:00
parent 73c1252bb6
commit df0eb5be1e
1 changed files with 40 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

48
doc/lispref/display.texi
View file

@ -1659,15 +1659,47 @@ overlay.
@end defun @end defun
@defun remove-overlays &optional start end name value @defun remove-overlays &optional start end name value
This function removes all the overlays between @var{start} and This function clears the text in the region between @var{start} and
@var{end} whose property @var{name} has the specified @var{value}. It @var{end} of any overlays whose property named @var{name} has the
can move the endpoints of the overlays in the region, or split them. specified @var{value}, such that no such overlay will affect the text in
the region. To do this, the function can remove overlays in the region,
or move their endpoints, or split them, or do some combination of these.
Specifically:
If @var{name} is omitted or @code{nil}, it means to delete all overlays in @itemize @bullet
the specified region. If @var{start} and/or @var{end} are omitted or @item
@code{nil}, that means the beginning and end of the buffer respectively. Overlays that start at or after @var{start} and end before @var{end}
Therefore, @code{(remove-overlays)} removes all the overlays in the will be removed completely.
current buffer.
@item
Overlays that start before @var{start} and end after @var{start}, but
before @var{end}, will be altered so that they end at @var{start}.
@item
Overlays that start at or after @var{start} and end after @var{end} will
be altered so that they start at @var{end}.
@item
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}.
@end itemize
If @var{name} is omitted or @code{nil}, it means to delete/modify all
overlays that affect text in the specified region. If @var{start}
and/or @var{end} are omitted or @code{nil}, they default to the
beginning and end of the buffer, respectively. Therefore,
@code{(remove-overlays)} removes all the overlays in the current buffer.
Values of the named overlay property are compared using @code{eq}, which
is important if the values are anything but symbols or fixnums
(@pxref{Equality Predicates}). It means the values passed to the
function must be the same values used to set the overlay property, not
their copies; objects which are different will not compare equal even if
they have identical contents.
The optional arguments @var{name} and @var{value} should either both be
passed and non-@code{nil}, or both omitted or @code{nil}.
@end defun @end defun
@defun copy-overlay overlay @defun copy-overlay overlay