bug#28584: 24.5; Emacs manual: add index entries for `multi-isearch-*' commands

bug#28584: 24.5; Emacs manual: add index entries for `multi-isearch-*' commands

[Drew Adams]

In the Emacs manual, if you use `i multi' then, even if you have a way
to substring-match index entries, you see nothing about using Isearch
across multiple files or buffers.

There are these index entries, for example:

  `multiple-file search and replace'
  `search and replace in multiple files'

But those just take you to node `Tags Search'.

Please consider doc changes, to (1) include more doc for Isearching
across multiple files and buffers, (2) index that doc, and (3)
cross-reference between that doc and node `Tags Search'.

The existing index entries mentioned above no doubt need to be changed,
to distinguish tags-based searching from Isearching.

For #1: Please document the `multi-isearch-*' commands more thoroughly.
Currently, `multi-isearch-files', and `multi-isearch-files-regexp' are
not mentioned.


In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

bug#28584: 24.5; Emacs manual: add index entries for `multi-isearch-*' commands

[John Wiegley]

>>>>> "DA" == Drew Adams <drew.adams@oracle.com> writes:

DA> In the Emacs manual, if you use `i multi' then, even if you have a way to
DA> substring-match index entries, you see nothing about using Isearch across
DA> multiple files or buffers.

DA> There are these index entries, for example:

DA>   `multiple-file search and replace'
DA>   `search and replace in multiple files'

Maybe I'm misunderstanding, but isn't the second index entries just what you
wanted to find?

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

bug#28584: 24.5; Emacs manual: add index entries for `multi-isearch-*' commands

[Drew Adams]

> DA> In the Emacs manual, if you use `i multi' then, even
> DA> if you have a way to substring-match index entries,
> DA> you see nothing about using Isearch across multiple
> DA> files or buffers.
> 
> DA> There are these index entries, for example:
> DA>   `multiple-file search and replace'
> DA>   `search and replace in multiple files'
> 
> Maybe I'm misunderstanding, but isn't the second index
> entries just what you wanted to find?

Not sure what you mean by "the second index entries".
Both of the index entries I mentioned go to the same
place - doc about tags search (only).

This is the point: The only index entries that have to do
with searching multiple files are entries for tags search.
There are none for Isearch across multiple files.

For some time now, Isearch has also been able to search
multiple files (and multiple non-file buffers).  But
there are no index entries in the manual for doc about
this feature.  There should be.  Tags search is not the
only way now to search multiple files (and buffers).

The text of both of the index entries I mentioned would
_seem_ to cover both tags search and Isearch.  There
should be separate entries for these very different ways
of searching multiple files.

Fixing that by adding index entries would take care of what
I wrote in the bug Subject line.  But the bug report
mentioned more than that.

My bug report was for Emacs 24.5.  The other part of the
report, beyond adding index entries, was to add doc for the
`multi-isearch-files(-regexp)' commands.  They were not
covered in Emacs 24.5.  Only `multi-isearch-buffers(-regexp)'
were covered (in node `Other Repeating Search').

Trying with Emacs 25.2, I see `multi-isearch-files(-regexp)'
are now covered, so the part of the bug that asks for that
can be ignored.

But in Emacs 25.2 only the same `multi' index entries are
available, and they still take you to doc that says nothing
about Isearch.  Instead of taking you to node `Tags Search'
they now take you to node `Identifier Search' (which is its
replacement).

That changes nothing really for this bug - that node is still
all about (only) tags or xref.  It says nothing about Isearch
across multiple files or buffers.  The kind of "finding" that
is described in node `Identifier Search' is not Isearch.

We should have `multi' index entries for node `Other
Repeating Search'.  And we should have cross-references
between the nodes that deal with these very different ways
to search across multiple files or buffers.

Index entries for searching across files or buffers should
indicate whether they are about Isearch or "identifier"
search.  That's the first thing.  The second thing is to
add xrefs between the nodes that cover these very different
kinds of search.

bug#28584: 24.5; Emacs manual: add index entries for `multi-isearch-*' commands

[John Wiegley]

>>>>> Drew Adams <drew.adams@oracle.com> writes:

> Not sure what you mean by "the second index entries". Both of the index
> entries I mentioned go to the same place - doc about tags search (only).

I mean the second thing you had listed:

    `search and replace in multiple files'

But now I see that also refers to Tags-based search and replace.

Yes, we should have an index entry for Isearching across files.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

bug#28584: 24.5; Emacs manual: add index entries for `multi-isearch-*' commands

[Drew Adams]

> > Not sure what you mean by "the second index entries". Both of the index
> > entries I mentioned go to the same place - doc about tags search (only).
> 
> I mean the second thing you had listed:
>     `search and replace in multiple files'
> But now I see that also refers to Tags-based search and replace.
> 
> Yes, we should have an index entry for Isearching across files.

And across (non-file) buffers.

And not just Isearching.  The same node includes `multi-occur*'.

And not just an _addition_ of index entries for this (for both
files and buffers).  The _existing_ index entries I mentioned
are misleading.  They should be changed to specify finding
certain "identifiers" in files (but not non-file buffers, I
imagine).  They are not really about searching, in the general
sense.

IOW, we should have index entries for (1) actually searching
and other index entries for (2) finding identifiers.  (The
former can find text matches of any kind, not just identifiers.)

bug#28584: 24.5; Emacs manual: add index entries for `multi-isearch-*' commands

[John Wiegley]

>>>>> Drew Adams <drew.adams@oracle.com> writes:

> And not just an _addition_ of index entries for this (for both files and
> buffers). The _existing_ index entries I mentioned are misleading. They
> should be changed to specify finding certain "identifiers" in files (but not
> non-file buffers, I imagine). They are not really about searching, in the
> general sense.

But doesn't it also find `M-x tags-query-replace`? In which case, it is a
search.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

bug#28584: 24.5; Emacs manual: add index entries for `multi-isearch-*' commands

[Drew Adams]

> > And not just an _addition_ of index entries for this (for both files and
> > buffers). The _existing_ index entries I mentioned are misleading. They
> > should be changed to specify finding certain "identifiers" in files (but
> > not non-file buffers, I imagine). They are not really about searching,
> > in the general sense.
> 
> But doesn't it also find `M-x tags-query-replace`? In which case,
> it is a search.

Yes, it does.  I was unclear, er, wrong, in saying that.

But as all "search" doc is not in the same place, we need separate
index entries.  Those should characterize, as much as is practical,
the differences.

That is, a given index entry should let you know, by its name (text),
what the target node covers.  Since we will need different entries
for the different nodes that deal with search (differently), the
entry text needs to distinguish the sense.

Equally important to indexing clearly the nodes that deal with
these different kinds of multi-file/buffer search is providing
cross-references between them.  This is all the more important
because they both deal with searching (across files/buffers),
in some sense.

For example, if a user follows an index entry to get to the doc
for finding identifiers, s?he should see there that there are
also other kinds of search, documented in another location.

It would be good if the nodes in question pointed out the
particular kinds of searching (i.e., the difference between
them), where they provide the xref.

Another possibility is to have a general node about searching
and replacing, which describes what's available generally
(pointing out differences) and then dispatches with a menu to
the nodes that currently exist.

Someone new (or old) to Emacs, who is not aware of what is
available for searching, should be offered a high-level
overview of search & replace, which covers, occur/grep-style
searching, find(-dired)-style searching, tags/xref-style
searching, query-replace, and isearch searching (did I leave
anything out?).

I'm occasionally surprised, for example, to see that some
users don't realize (or at least don't think about the fact)
that occur/grep search only single-line contexts.

bug#28584: 24.5; Emacs manual: add index entries for `multi-isearch-*' commands

[John Wiegley]

>>>>> Drew Adams <drew.adams@oracle.com> writes:

> But as all "search" doc is not in the same place, we need separate index
> entries. Those should characterize, as much as is practical, the
> differences.

I think I would like this also; I too use the index quite a bit to find things
in the Elisp/Emacs manuals.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

bug#28584: 24.5; Emacs manual: add index entries for `multi-isearch-*' commands

[Eli Zaretskii]

> Date: Sun, 24 Sep 2017 17:38:13 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 28584@debbugs.gnu.org
> 
> Trying with Emacs 25.2, I see `multi-isearch-files(-regexp)'
> are now covered, so the part of the bug that asks for that
> can be ignored.
> 
> But in Emacs 25.2 only the same `multi' index entries are
> available, and they still take you to doc that says nothing
> about Isearch.  Instead of taking you to node `Tags Search'
> they now take you to node `Identifier Search' (which is its
> replacement).

Thanks, I've now fixed the indexing about these issues.