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

[Drew Adams]

> > 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.

I guess your question is about how to interactively populate the buffer/file
list?

If so, I'd say keep it simple:

If the list variable is already populated, then use that value. This lets users
populate the variable ahead of time and then still use these commands
interactively.

If the list variable is null, then just have a simple loop for users to enter a
buffer/file name (e.g. with completion), and end with an empty string. IOW, foo
RET bar RET RET to give ("foo" "bar").

Obviously, users can also wrap these functions with a `let' that binds the list
variable and define a new command that is appropriate to some particular list
that is constructed in some particular way. The point here is just to have a
couple rudimentary commands as a basis - IOW, to just turn these functions into
commands in a simple way.

> > 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.

I meant _at least_ #1 AND #2.

I think this is an important part of Isearch - at least as important as word
search, for instance. There's no reason not to document it in the Emacs manual -
the description would be short.

The implementation is factored into misearch.el and isearch.el, but the feature
should be mentioned (also) in the Commentary of isearch.el, just as other search
features are mentioned. That Commentary is the overall description of Isearch,
from an implementation point of view. It's OK to also say "see misearch.el for
details about multi-search" etc.