Emacs manual nodes about text replacement

[Drew Adams]

The presentation and order of the manual nodes describing text replacement could
be improved. I don't have a concrete proposal, but here are some problems I see.

The main node, Replace, starts by saying that you don't use global
search-and-replace that much in Emacs. That's true in the batch (unconditional)
sense, but query-replacement is commonly used. This could be made clearer:
Unconditional global replacement is not needed that often. Most of the time you
use conditional, interactive replacement - called query-replacement.

The subnode order then describes first precisely what we just said is not needed
that much. First comes batch string replace, then batch regexp replace, then
case considerations during (batch) replacement.

The nitty gritty of replacement types and mechanisms is presented in the context
of batch replacement (only), which gives the impression that these do not apply
also to query-replacement (which has not even been introduced yet!). This, in
spite of the fact that users will, most of the time, use that information for
query-replacment, not for batch replacement.

It is not until after all of this (which includes some pretty heavy
Lisp-oriented details about expression regexp replacement) that we get to node
Query Replace, which tells you that you can query-replace. In a sense, the
existing node order is bottom-up, presenting details about replacement before
presenting how to replace in general.

It would be better to guide users by presenting first and foremost
query-replacement. For the details about which replacements are possible and how
they are made (things such as case considerations and regexp and evalled
expression replacement), users could then read the nodes that follow. 

IOW, give a top-down explanation of how Emacs users typically replace text.
Start with query-replace and let readers drill down as needed. Make it clear
that all of the replacement possibilities and mechanisms apply to both
query-replacement and to (the lesser used) batch replacement. Point out
exceptions, if there are any.

As it stands now, query-replacement seems to be almost an afterthought (after
we're all done explaining replacement in all its glory), and for only simple,
lightweight replacements. In fact, query-replacement is the main entry point for
all kinds of replacements. This fact is lost, IMO.

Batch replacement, not query-replacement, should be presented as almost an
afterthought: BTW, you can also replace unconditionally - but if you do that
interactively then it is usually better to use query-replacement and, after you
are sure of what the replacement does, hit `!'.

The fact that advanced replacement is possible when you query-replace needs to
be made clear. The problem is not only the node order. It is not obvious when
reading the Query Replace node, for example, that you can do evalled
Lisp-expression replacement. You really have to read carefully and somewhat
between the lines to catch that. This passage is the only clue I could find:

 "`C-M-%' performs regexp search and replace
  (`query-replace-regexp'). It works like `replace-regexp'
                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  except that it queries like `query-replace'."

It's only the phrase "it works like `replace-regexp'" that hints that you might
be able to use things like \, in the replace string when query-replacing. This
is not enough to guide the user.

Yes, things such as \, are advanced uses, but they are also interactive uses,
and powerful ones. Such functionality merits clear documentation in the Emacs
manual, which is our user guide. Programmers can now use query-replacement to do
things interactively that they might have done previously only via script or
Lisp code. They need to be made aware of these possibilities.

In sum, the overall presentation should take users through what's available in a
top-down way, and it should emphasize query-replacing throughout. In particular,
it should help users see that advanced, sophisticated replacement (regexp,
expressions, lists) is available for query-replacement.

It's OK to present the advanced features and the details in subsequent nodes,
but the advanced replacement features should at least be called out at the
higher level, when introducing query-replacement. They should not be buried, and
they should not appear to be available only for batch replacement.

In general, present first the features available: _what_ you can do with Emacs
(query-)replacement, before presenting all of the details of _how_ to do it:
`C-w' to delete and then recurse, etc.

[See also my mail of today, subject "general perform-replace REPLACEMENTS arg
for regexp query-replacement?".]