bug#60399: 30.0.50; Usage of `isearch-open-invisible-temporary' is not documented

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: juri@linkov.net, 60399-done@debbugs.gnu.org
> Date: Mon, 02 Jan 2023 08:57:11 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Thanks, this background was indeed missing.  However, even after
> > reading it, I still don't understand how come you need or want to
> > delete these overlays -- aren't they needed to hide the text to begin
> > with?
> >
> > Or IOW, if you are deleting and recreating the overlays, why do you
> > need to use this isearch feature at all? just delete them when you
> > want to show the text, and reapply them later when you want the text
> > hidden again.
> 
> This is pretty much what is being done: I try to hook into isearch code
> to (1) when isearch is about to display the match, I save the old
> overlays and re-arrange them to display the match as needed; (2) when
> isearch moves to the next match, I restore the old overlays.
> 
> However, because isearch expects the overlays to exist even upon
> revealing the isearch match, I cannot achieve what I want. Even though
> my code would work fine, isearch itself errs in
> `isearch-close-unnecessary-overlays'/`isearch-open-necessary-overlays'
> where it does additional checks involving `overlay-start' and
> `overlay-end' that must be non-nil.

I guess it's a bug in open/close-unnecessary-overlays, then?  I'm not
really sure I understand their role here.  Juri, Stefan, can you help
out?