Subject: 23.1; doc of misearch-* commands (commands?)
From: "Drew Adams" <[email-masked]>
To: <[email-masked]>
Date: Wed, 14 Oct 2009 13:49:52 -0700

emacs -Q
 
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.
Or else change the NEWS item.
 
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.
 
I would even say that it should be documented how to use the
multi-isearch framework to set up multiple buffers etc. for
searching. It's not obvious (1) that you can do that or (2) how to do
that.  There is no reason not to let Emacs-Lisp programmers know about
this. This is provided out of the box as part of Isearch, and it
should be well documented.

 
In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600)
 of 2009-07-29 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4)'