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

[Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

>> But it's very natural that the caller of that
>> `isearch-open-invisible-temporary` may still want to know the boundaries
>> of this overlay after its content is made visible, so as to know when to
>> make it invisible again.
>
> I am not sure why isearch should decide this instead of letting
> `isearch-open-invisible-temporary' decide what to close.

The question is not just what to close but *when*.

Isearch need to tell your code when it thinks you can close.
It's natural to use the overlay's boundaries to decide when to do that,
and it's natural to use that overlay as "the info about what to close"
when i calls you back.

I'm not claiming it's perfect or ideal.  It's just a fairly natural
choice.  Note that in `reveal.el` I use a similar API but with a twist:
after calling `reveal-toggle-invisible`, `reveal.el` checks whether the
points we're interested in have been made visible and if not, we take
the (new) overlays and repeat.  This way, to get the behavior you say
you want for Org (which we get in `outline-mode` with `reveal-mode`) we
just arrange for `reveal-toggle-invisible` to show the headings "one
level down" (and re-hide everything else): if that's not enough,
`reveal.el` then calls `reveal-toggle-invisible` inside one of the
subheadings until we're at the actual leaf.

This addresses a major shortcoming of the
`isearch-open-invisible-temporary' which is that the function is not
told which part of the overlay needs to be opened.  The best the
function can do is presume that `point` is the thing of interest, but
it's not specified anywhere (and in the case of `reveal.el` it's not
sufficient because we may have several points to reveal at the same
time).

>> `reveal-toggle-invisible` works basically the same way as
>> `isearch-open-invisible-temporary` and in
>> `outline-reveal-toggle-invisible` I had the same problem as you do,
>> which I solved with:
>>
>>       (let ((o1 (copy-overlay o)))
>>         (overlay-put o 'invisible nil)  ;Show (most of) the text.
>
> This is a nice trick, which is unfortunately not very useful in my
> situation. Some text should still remain invisible in Org even when
> opening is requested. Your code reveals everything unconditionally.

There's a misunderstanding here: `outline-reveal-toggle-invisible`
reveals only the immediate children.  All it reveals is basically:

                 (outline-show-entry)
                 (outline-show-children)


-- Stefan