bug#4725: 23.1; doc of misearch-* commands (commands?)

[Juri Linkov <juri@jurta.org>]

> In NEWS it says:
>
>  ** The package misearch.el has been added.  It allows Isearch to search
>  through multiple buffers.  A variable `multi-isearch-next-buffer-function'
>  defines the function to call to get the next buffer to search in the series
>  of multiple buffers.  Top-level commands `multi-isearch-buffers',
>  `multi-isearch-buffers-regexp', `multi-isearch-files' and
>  `multi-isearch-files-regexp' accept a single argument that specifies
>  a list of buffers/files to search for a string/regexp.
>
> But this is false. The functions `multi-isearch-buffers',
> `multi-isearch-buffers-regexp', `multi-isearch-files' and
> `multi-isearch-files-regexp', defined in misearch.el, are not defined
> as commands.
>
> 1. Shouldn't they be commands? I.e., this is the first bug.

Yes, they should be commands.  These command should allow the user
to select interactively a list of buffers or files to search.
Currently I have no idea about the best UI for this.
Suggestions welcome.

> 2. I find no explanation of using Isearch with multiple buffers or
> files anywhere, including in the Emacs manual. This needs to be
> documented somewhere.
>
> Logically, this should be explained in a new section of the Isearch
> chapter of the Emacs manual. It is even the case that multi-isearch is
> handled, in its essentials, in isearch.el (not in misearch.el). So
> this is really an integral part of Isearch. It needs to be properly
> documented as such. That means at least (1) in the Emacs manual and
> (2) in the file Commentary of isearch.el.

(3) the Emacs Lisp Reference Manual
(4) in the file Commentary of misearch.el

I prefer (4) since it is not a core feature to be documented
in the Info manual.

-- 
Juri Linkov
http://www.jurta.org/emacs/