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: Sun, 01 Jan 2023 12:51:40 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> What about the manual?
> >> (elisp) 41.6 Invisible Text
> >
> > I don't think this obscure issue needs to be mentioned in the manual.
> > It is quite clear to me that the overlay in question cannot be
> > deleted, I actually raised a brow when you asked for this to be
> > explicitly mentioned.
> 
> I think I need to explain the context a bit.
> 
> In org-fold, we want isearch matched to be not just revealed according
> to the full overlays they are hidden in. We want to rearrange the
> overlays in such a way that outline structure above the match is
> revealed:
> 
> * Folded heading
> ** Folded sub-heading
> Some unrelated text.
> :FOLDED-DRAWER:
> isearch-match
> :END:
> 
> which will look like
> 
> * Folded heading...
> 
> When we do isearch, the aim is
> 
> * Folded heading
> ** Folded sub-heading...
> isearch-match
> ...
> 
> which requires re-creating overlays used for folding.
> 
> In the process, 'isearch-open-invisible-temporary may affect more than
> the overlay used as its argument. In particular, other overlays at point
> may be affected.
> 
> The 'isearch-open-invisible-temporary takes care about proper saving and
> restoring the necessary overlays. However, isearch gets broken.
> 
> In this setup, it is not that obvious that isearch will still try to do
> something with overlays that got deleted during the call to
> 'isearch-open-invisible-temporary.

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.

> I am not even sure how to achieve the desired custom behavior using the
> current isearch implementation.

It's an obscure feature indeed.