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

From: Drew Adams <[email-masked]>
Date: Mon, 25 Sep 2017 08:13:09 -0700 (PDT)

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