Emacs manual nodes about text replacement

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?".]

Re: Emacs manual nodes about text replacement

[Juri Linkov]

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

I can't find none of the text that you are referring to.  What version do
you use?  Recently Yidong rewrote many parts of the documentation, so
please refer to a newer version.

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

RE: Emacs manual nodes about text replacement

[Drew Adams]

> I can't find none of the text that you are referring to.  
> What version do you use?

GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600)
 of 2008-11-08 on LENNART-69DE564
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --no-opt --cflags -Ic:/g/include
-fno-crossjumping'

> Recently Yidong rewrote many parts of the documentation, so
> please refer to a newer version.

Looking at the CVS version today, it seems to reflect the same structure. Here
is the Replace node's menu:

* Unconditional Replace::	Replacing all matches for a string.
* Regexp Replace::		Replacing all matches for a regexp.
* Replacement and Case::	How replacements preserve case of letters.
* Query Replace::		How to use querying.

IOW, it starts out with unconditional replace etc., as I said.

What part of what I wrote is unclear to you?

Re: Emacs manual nodes about text replacement

[Chong Yidong]

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

>> Recently Yidong rewrote many parts of the documentation, so
>> please refer to a newer version.
>
> Looking at the CVS version today, it seems to reflect the same
> structure.
>
> What part of what I wrote is unclear to you?

Your opening statement

  The main node, Replace, starts by saying that you don't use global
  search-and-replace that much in Emacs.

is not true, in the latest version of the manual anyway.

RE: Emacs manual nodes about text replacement

[Drew Adams]

> >> Recently Yidong rewrote many parts of the documentation, so
> >> please refer to a newer version.
> >
> > Looking at the CVS version today, it seems to reflect the same
> > structure.
> 
> Your opening statement
>   The main node, Replace, starts by saying that you don't use global
>   search-and-replace that much in Emacs.
> is not true, in the latest version of the manual anyway.

Yes, this opening sentence:

 Global search-and-replace operations are not needed
 often in Emacs, but they are available.

was changed to this in Emacs 23 (good):

 Emacs provides several commands for performing
 search-and-replace operations.

So you can skip that first statement I made. AFAICT, the rest of my message is
still pertinent.

The main points: The presentation is backward and misleading. Emphasize
query-replace, not unconditional replace. Present the information top-down, not
bottom up. Give an overview of what you can do before the details about how to
do it. Make it clear that all of the fancy stuff applies to query-replace too,
not just to unconditional replace.

Please see the original message for details.