bug#27896: 25.2; `C-M-%' with `rectangle-mark-mode'

[Drew Adams <drew.adams@oracle.com>]

Clearly the current design of using a rectangular region to
limit replacing does not limit search for the replacement
commands in the same sense that the (normal) region limits
search.

The (normal) region limits the text that replacement search
tries to match, by bounding it.  The rectangular region keeps
the ordinary region as the domain of text that search tries
to match, and it filters the matches against that domain to
remove any matches that are not wholly within the limits of
the rectangle.

That's the design, and it's OK.  But it is misleading in
that we don't distinguish the two "region" behaviors.  It is
all too easy to expect that the rectangular region bounds
search in the same way that the ordinary region does.

To provide a different design, where the rectangular region
really limits the domain of text that we try to search,
would require some work.  It's OK that we stick to what we
have, at least for now, since it is anyway useful.

But I do think that users should be told what to expect (e.g.,
wrt regexp searching, in particular).  Currently there seems
to be NO doc about replacement over the rectangular region.

The code for this feature seems to have been added without
also providing doc and, as bug #27897 points out, it was
apparently only half-added.  Arg REGION-NONCONTIGUOUS-P
should also be added to other replacement commands, such as
`replace-string', `replace-regexp', `query-replace-regexp-eval',
and `map-query-replace-regexp'.  They too can benefit from
the new feature, and adding support for it is trivial (add
the optional arg and pass it to `perform-replace').

Please consider this bug report (#27896) to be a request
to add doc (in the Emacs manual) about replacing text over
a rectangular region.  That doc would be a good place to
point out that the rectangle limits do not limit the area
where searching is tried; they just provide post-matching
filtering to remove any matches that are not (wholly)
within the rectangle.

I think it's important to make this clear to users.  This
info should perhaps also be added to the doc strings of
the relevant commands.  (That's especially true if you
decide not to document this feature in the Emacs manual.)

> I think a user would expect the rectangle to define
> the region of possible query-replacing, not just define a clipping area
> from the full region of searching.  IOW, I think a user would expect the
> rectangular limits to be established first, and then searching to be
> limited to that rectangular space.
> 
> If nothing else, if this is the intended design then I think the doc
> should be clear about it.  It should say, in that case, that matches are
> sought throughout the full, non-rectangular region, and only those
> matches that are wholly (?) within the rectangle are then retained as
> possible matches.
> 
> My guess of what's happening is supported by this: If you do the same
> thing (same region) but without using `rectangle-mark-mode' then you see
> that rectangle mark mode just retains the matches for the normal,
> non-rectangular region, that are wholly within the rectangle.
> 
> Here are the matches for the normal, non-rectangular region:
> 
> ;; This buffer is for text that is not saved, and for Lisp evaluation.
>             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> ;; To create a file, visit it with C-x C-f and enter text in its buffer.
>         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> ;; This buffer is for text that is not saved, and for Lisp evaluation.
>             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> ;; To create a file, visit it with C-x C-f and enter text in its buffer.
>         ^^^
> 
> This should be documented, as it is not, I think, what someone expects
> by searching a rectangular region (a region delimited by a rectangle).
> I think someone would expect that the search domain is limited by the
> rectangle, and then query-replace applies to matches within that domain.
> 
> That's very different from the current behavior, which is to leave the
> search domain as the full region (undelimited by the rectangle) and then
> filter out (remove) any matches from that that are not wholly within the
> rectangle.
> 
> 
> 
> In GNU Emacs 25.2.1 (x86_64-w64-mingw32)
>  of 2017-04-24 built on LAPHROAIG
> Windowing system distributor 'Microsoft Corp.', version 6.1.7601
> Configured using:
>  'configure --without-dbus --without-compress-install 'CFLAGS=-O2
>  -static -g3''
> 
> 
>