bug#13592: 24.2.92; C-s prompts with "Multi I-search:" today

[Juri Linkov <juri@jurta.org>]

>  . Why is it a good idea to show this Multi thing at the very
>    beginning of the search, when there's no evidence whatsoever that
>    the search is in danger of crossing into the next file in the
>    series?  It's confusing to see this, because _I_ didn't ask for
>    multi-file or multibuffer isearch.  It took me by surprise and
>    forced me to go looking for the reason (tried in other versions of
>    Emacs and in other buffers, before it dawned on me that it is
>    something specific to add-log mode).  You want to be nice to me?
>    fine: then show this to me when I type C-s that will cross into the
>    next file, but not before that.

When you type C-s that will cross into the next file,
it appends this text to the isearch message:

  [repeat for next buffer]

>    _Then_ I might appreciate the service.  But when I type my first C-s,
>    please give me just what I asked for.

Multi-file isearch is a special kind of search, so the prefix "Multi"
informs the user that the search will go through a set of files.
This is like the prefix "Regexp" informing the user that the search
is regexp-based, and other informative prefixes as well.

>  . This should at least be documented in the manual.  When I saw this
>    prompt, I tried to figure out what it meant (did someone really
>    think that "Multi" explains it all?), but it seems not to be
>    mentioned anywhere in the docs.  Even the NEWS entry for Emacs
>    23.1, which does say that isearch is automatically multi-file in
>    ChangeLog files, doesn't mention this prompt.  I needed to wade
>    through isearch.el to find what it meant, only to find out that the
>    facility used to trigger it -- multi-search-next-buffer-function --
>    is not documented in the Elisp manual, either, which sounds weird
>    if we consider such features useful in other modes.

It could be documented in (info "(emacs) Other Repeating Search")
where `multi-isearch-buffers' is already described.