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

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

[Drew Adams]

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)'
 

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

[Juri Linkov]

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

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.

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

[Juri Linkov]

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

`multi-isearch' was designed to be similar to `multi-occur'.
Currently we have a set of commands:

  isearch-forward
      search for a string in the current buffer

  isearch-forward-regexp
      search for a regexp in the current buffer

  occur
      search for a regexp in the current buffer

  multi-occur
      search for a regexp through multiple buffers
      where the user specifies the buffer names one by one

  multi-occur-in-matching-buffers
      search for a regexp through multiple buffers
      where the user specifies the buffers to search by a regexp

What is missing now and candidates to be implemented are
8 analogous commands:

  multi-isearch-buffers
      search for a string through multiple buffers
      where the user specifies the buffer names one by one

  multi-isearch-buffers-regexp
      search for a regexp through multiple buffers
      where the user specifies the buffer names one by one

  multi-isearch-buffers-matching
      search for a string through multiple buffers
      where the user specifies the buffers to search by a regexp

  multi-isearch-buffers-regexp-matching
      search for a regexp through multiple buffers
      where the user specifies the buffers to search by a regexp

  multi-isearch-files
      search for a string through multiple files
      where the user specifies the file names one by one

  multi-isearch-files-regexp
      search for a regexp through multiple files
      where the user specifies the file names one by one

  multi-isearch-files-matching
      search for a string through multiple files
      where the user specifies the files to search by a regexp

  multi-isearch-files-regexp-matching
      search for a regexp through multiple files
      where the user specifies the files to search by a regexp

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

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

[Drew Adams]

> > 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").
> 
> `multi-isearch' was designed to be similar to `multi-occur'.
> Currently we have a set of commands:
> 
>   isearch-forward
>   isearch-forward-regexp
>   occur
>   multi-occur
>   multi-occur-in-matching-buffers
> 
> What is missing now and candidates to be implemented are
> 8 analogous commands:
> 
>   multi-isearch-buffers
>   multi-isearch-buffers-regexp
>   multi-isearch-buffers-matching
>   multi-isearch-buffers-regexp-matching
>   multi-isearch-files
>   multi-isearch-files-regexp
>   multi-isearch-files-matching
>   multi-isearch-files-regexp-matching

Hi Juri,

It's your call, I guess, but that sounds like a lot, for what it's worth.

I'd suggest having just simple commands that let you enter buffer/file names, as
I said above.

If the list variable is already populated, then that would be used, without the
user inputting any names. That also lets users populate the variable in other
ways (e.g. by regexp matching). You might want one separate command that lets
you populate the variable by entering a regexp to match (against buffer or file
names).

Anyway, do whatever you want in this regard. I agree that it's good for users to
be able to both (a) choose files/buffers by name individually, and (b) choose
them by regexp matching.

There are of course many possibilities for defining a set of such names. One
that exists already for files is filesets. That too could be leveraged as one
way to specify the file names you want.

It's a bit of a shame to have zillions of commands, each of which differs by (a)
the type of object chosen, (b) whether matching is literal or regexp, and
possibly (c) whether the objects are chosen explicitly or by pattern matching.

We could also try combining a few at a time in the same command, using a prefix
arg to distinguish (e.g. file vs buffer or regexp vs literal or both). That's
probably a question of preference - I'd usually sooner have a single command to
do this kind of thing, and then consult the doc string if I forget the different
prefix-arg possibilities. I get lost in a sea of similar seeming command names.

Again, though, please do whatever you like here - it's OK by me.

HTH - Drew

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

[Emacs bug Tracking System]

[-- Attachment #1: Type: text/plain, Size: 885 bytes --]

Your message dated Mon, 30 Nov 2009 21:44:18 +0200
with message-id <87r5rflrvx.fsf@mail.jurta.org>
and subject line Re: bug#4725: 23.1; doc of misearch-* commands (commands?)
has caused the Emacs bug report #4725,
regarding 23.1; doc of misearch-* commands (commands?)
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact owner@emacsbugs.donarmstrong.com
immediately.)


-- 
4725: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=4725
Emacs Bug Tracking System
Contact owner@emacsbugs.donarmstrong.com with problems

[-- Attachment #2: Type: message/rfc822, Size: 4758 bytes --]

From: "Drew Adams" <drew.adams@oracle.com>
To: <bug-gnu-emacs@gnu.org>
Subject: 23.1; doc of misearch-* commands (commands?)
Date: Wed, 14 Oct 2009 13:49:52 -0700
Message-ID: <18FECACAE8904F2A9A26016A02CCA5F0@us.oracle.com>

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)'
 




[-- Attachment #3: Type: message/rfc822, Size: 3119 bytes --]

From: Juri Linkov <juri@jurta.org>
To: "Drew Adams" <drew.adams@oracle.com>
Cc: 4725-done@emacsbugs.donarmstrong.com
Subject: Re: bug#4725: 23.1; doc of misearch-* commands (commands?)
Date: Mon, 30 Nov 2009 21:44:18 +0200
Message-ID: <87r5rflrvx.fsf@mail.jurta.org>

>> What is missing now and candidates to be implemented are
>> 8 analogous commands:
>>
>>   multi-isearch-buffers
>>   multi-isearch-buffers-regexp
>>   multi-isearch-buffers-matching
>>   multi-isearch-buffers-regexp-matching
>>   multi-isearch-files
>>   multi-isearch-files-regexp
>>   multi-isearch-files-matching
>>   multi-isearch-files-regexp-matching
>
> I'd suggest having just simple commands that let you enter buffer/file names, as
> I said above.
>
> Anyway, do whatever you want in this regard. I agree that it's good for users to
> be able to both (a) choose files/buffers by name individually, and (b) choose
> them by regexp matching.

I agree 8 commands is too much.  So I left the number of commands unchanged.
Now interactively `multi-isearch-buffers' and `multi-isearch-buffers-regexp'
read buffer names to search, one by one, ended with RET.  With a prefix
argument, they ask for a regexp, and search in buffers whose names match
the specified regexp.  Interactively `multi-isearch-files' and
`multi-isearch-files-regexp' read file names to search, one by one,
ended with RET.  With a prefix argument, they ask for a wildcard, and
search in file buffers whose file names match the specified wildcard.

(PS: Some new reading functions duplicate some code from other existing
functions with subtle differences, and I see no way to use existing
functions as is, so I added comments that point to original code).

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