bug#20092: 24.4.91; False matches with incremental search in Info

[N. Jackson]

I'm having a hard time figuring out the intended behaviour of I-search
when search-invisible has the value `open'. I think the documentation
here could be improved somewhat, especially since this is the default
value. The way the documentation reads now the feature seems less than
completely baked.

I'm guessing that the intended behaviour is roughly that when a search
finds a match in text that is invisible to the user, then, 1) if the
value of search-invisible is nil then the match is ignored; 2) if the
value of search-invisible is t then the match is deemed to be
immediately before the start of the invisible text (This is the rather
confusing behaviour that prompted me to report this bug.); and 3) if the
value of search-invisible is `open' then the chunk of invisible text is
made visible ("opened") temporarilly, and the match shown within it.

The Emacs manual doesn't have "search-invisible" in the index but it is
in the variables index. However the variables index entry doesn't link
to the definition of the variable but rather to the node "Outline
Visibility" where it is only mentioned in passing and the meaning of
`open' is not mentioned at all.

A search of the manual turns up "search-invisible" in two places. The
first is in the node "Query Replace" and reads:

    "The option ‘search-invisible’ determines how ‘query-replace’ treats
    invisible text.  *Note Outline Search."

The link to "Outline Search" here seems to be broken; it goes to
"25.10.3 TeX Printing Commands".

The second place it is found is in "Outline Visibility". This is the
most helpful (perhaps that's whey the Variable Index points here) but,
as I mentioned above, it doesn't discuss `open':

    "When incremental search finds text that is hidden by Outline mode, it
    makes that part of the buffer visible. If you exit the search at that
    position, the text remains visible. To toggle whether or not an active
    incremental search can match hidden text, type ‘M-s i’. To change the
    default for future searches, customize the option ‘search-invisible’.
    (This option also affects how ‘query-replace’ and related functions
    treat hidden text, *note Query Replace.) You can also automatically make
    text visible as you navigate in it by using Reveal mode (‘M-x
    reveal-mode’), a buffer-local minor mode."

The docstring for search-invisible says:

#+BEGIN_SRC emacs-lisp
      "If t incremental search/query-replace can match hidden text.
    A nil value means don't match invisible text.
    When the value is `open', if the text matched is made invisible by
    an overlay having an `invisible' property and that overlay has a property
    `isearch-open-invisible', then incremental search will show the contents.
    \(This applies when using `outline.el' and `hideshow.el'.)

    To temporarily change the value for an active incremental search,
    use \\<isearch-mode-map>\\[isearch-toggle-invisible].

    See also the related option `isearch-hide-immediately'.

    See also `reveal-mode' if you want overlays to automatically be opened
    whenever point is in one of them."
#+END_SRC

The discussion of `open' here seems to describe implementation rather
than behaviour.

It's not clear what one is to make of the sentence "This applies when
using `outline.el' and `hideshow.el'."; this almost suggests the
semantics of `open' are undefined elsewhere.

It seems odd to have a function (isearch-toggle-invisible) to "toggle"
the state of a variable that can have three states; cycling seems more
appropriate. In any case looking at the code, it does actually toggle
(between nil and t), but also changes `open' to nil, and then one can
never "toggle" back to `open'. Of course, this applies to
isearch-invisible not search-invisible, so maybe it is not important.

Sorry to be so nit-picky. However, clarifying this a little bit seems
necessary to decide if this bug is a bug and would also seem to present
an opportunity for improving Emacs's docs.