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
@defun remove-overlays &optional start end name value
This function removes all the overlays between @var{start} and
@var{end} whose property @var{name} has the specified @var{value}. It
can move the endpoints of the overlays in the region, or split them.
This function clears the text in the region between @var{start} and
@var{end} of any overlays whose property named @var{name} has the
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
the specified region. If @var{start} and/or @var{end} are omitted or
@code{nil}, that means the beginning and end of the buffer respectively.
Therefore, @code{(remove-overlays)} removes all the overlays in the
current buffer.
@itemize @bullet
@item
Overlays that start at or after @var{start} and end before @var{end}
will be removed completely.
@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
@defun copy-overlay overlay