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

[Ihor Radchenko <yantar92@posteo.net>]

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.

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

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>