bug#16513: 24.3.50; doc string of `use-empty-active-region'

bug#16513: 24.3.50; doc string of `use-empty-active-region'

[Drew Adams]

1. Remove the last part: ", and on the text near point otherwise."  It
is inappropriate and wrong.  (This is the reason I filed this bug.)

This is about commands that act differently depending on whether or
not the region is active.  Do not say anything about what the behavior
must be in either case: active or inactive.  Certainly, do not claim
that when the region is inactive such commands act on the text near
point. That is pure fantasy.

2. Simplify the following, which suggests that having an active region
is somehow different from having an active mark:

"If non-nil, region-aware commands treat the region as active as long as
the mark is active, even if the region is empty."  Just say: "If
non-nil, region-aware commands treat an active region as such, even if
it is empty."

3. Do not speak of "regions", as it can confuse people.  In any given
buffer at any moment there is only one region.  "The region" makes
sense; "regions" does not, unless you are talking about multiple
buffers.

In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2014-01-17 on ODIEONE
Bzr revision: 116059 michael.albinus@gmx.de-20140117182409-gz695p2c951idlee
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/binary --enable-checking=yes,glyphs
 'CFLAGS=-O0 -g3' LDFLAGS=-Lc:/Devel/emacs/lib
 CPPFLAGS=-Ic:/Devel/emacs/include'

bug#16513: 24.3.50; doc string of `use-empty-active-region'

[Lars Ingebrigtsen]

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

> 1. Remove the last part: ", and on the text near point otherwise."  It
> is inappropriate and wrong.  (This is the reason I filed this bug.)
>
> This is about commands that act differently depending on whether or
> not the region is active.  Do not say anything about what the behavior
> must be in either case: active or inactive.  Certainly, do not claim
> that when the region is inactive such commands act on the text near
> point. That is pure fantasy.
>
> 2. Simplify the following, which suggests that having an active region
> is somehow different from having an active mark:
>
> "If non-nil, region-aware commands treat the region as active as long as
> the mark is active, even if the region is empty."  Just say: "If
> non-nil, region-aware commands treat an active region as such, even if
> it is empty."
>
> 3. Do not speak of "regions", as it can confuse people.  In any given
> buffer at any moment there is only one region.  "The region" makes
> sense; "regions" does not, unless you are talking about multiple
> buffers.

The previous version of the doc strings seems to be more
straightforward.  Is there some subtlety that the new version tried to
get across?

!   "If non-nil, an active region takes control even if empty.
! This applies to certain commands which, in Transient Mark mode,
! apply to the active region if there is one.  If the setting is t,
! these commands apply to an empty active region if there is one.
! If the setting is nil, these commands treat an empty active
! region as if it were not active."

while it's now

(defcustom use-empty-active-region nil
  "Whether \"region-aware\" commands should act on empty regions.
If nil, region-aware commands treat empty regions as inactive.
If non-nil, region-aware commands treat the region as active as
long as the mark is active, even if the region is empty.

Region-aware commands are those that act on the region if it is
active and Transient Mark mode is enabled, and on the text near
point otherwise."

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#16513: 24.3.50; doc string of `use-empty-active-region'

[Lars Ingebrigtsen]

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

> 1. Remove the last part: ", and on the text near point otherwise."  It
> is inappropriate and wrong.  (This is the reason I filed this bug.)
>
> This is about commands that act differently depending on whether or
> not the region is active.  Do not say anything about what the behavior
> must be in either case: active or inactive.  Certainly, do not claim
> that when the region is inactive such commands act on the text near
> point. That is pure fantasy.

I think I understand what Chong was trying to express here now.

---
Region-aware commands are those that act on the region if it is
active and Transient Mark mode is enabled, and on the text near
point otherwise.
---

This explains the concept of "region-aware" commands -- they typically
switch between acting on the stuff around point and the stuff in the
region.  Like `DEL', which deletes the region if it is active, and the
previous character if not.

So I don't think it's wrong...

> 2. Simplify the following, which suggests that having an active region
> is somehow different from having an active mark:
>
> "If non-nil, region-aware commands treat the region as active as long as
> the mark is active, even if the region is empty."  Just say: "If
> non-nil, region-aware commands treat an active region as such, even if
> it is empty."

No, I like the mention of the mark, which helps my understanding of what
it's saying.

> 3. Do not speak of "regions", as it can confuse people.  In any given
> buffer at any moment there is only one region.  "The region" makes
> sense; "regions" does not, unless you are talking about multiple
> buffers.

I've fixed that now.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#16513: 24.3.50; doc string of `use-empty-active-region'

[Drew Adams]

> > 1. Remove the last part: ", and on the text near point otherwise."  It
> > is inappropriate and wrong.  (This is the reason I filed this bug.)
> >
> > This is about commands that act differently depending on whether or
> > not the region is active.  Do not say anything about what the behavior
> > must be in either case: active or inactive.  Certainly, do not claim
> > that when the region is inactive such commands act on the text near
> > point. That is pure fantasy.
> 
> I think I understand what Chong was trying to express here now.
> 
> ---
> Region-aware commands are those that act on the region if it is
> active and Transient Mark mode is enabled, and on the text near
> point otherwise.
> ---
> 
> This explains the concept of "region-aware" commands -- they typically
> switch between acting on the stuff around point and the stuff in the
> region.  Like `DEL', which deletes the region if it is active, and the
> previous character if not.
> 
> So I don't think it's wrong...

It is wrong.  What is correct is that region-aware commands act
on the region when it is active.  What is 100% wrong (though it
could be right for some command, of course) is to say anything
about the behavior when the region is not active.

It is just not true in general that when the region is not
active the command acts on text near point.  That is pure
invention.  NOTHING makes that happen.  A region-aware command
can do anything at all when the region is not active.

What could reasonably be said, perhaps, is that in general
such commands do something similar but to some other text,
not necessarily to the region text.  And in practice, such
commands (those that are predefined by Emacs, in any case)
typically act on the entire accessible portion of the buffer
(i.e., the whole buffer or its current restriction (narrowing)).

But certainly not some text near point.

> > 2. Simplify the following, which suggests that having an active region
> > is somehow different from having an active mark:
> >
> > "If non-nil, region-aware commands treat the region as active as long as
> > the mark is active, even if the region is empty."  Just say: "If
> > non-nil, region-aware commands treat an active region as such, even if
> > it is empty."
> 
> No, I like the mention of the mark, which helps my understanding of what
> it's saying.

It suggests that having an active region is somehow different
from having an active mark.  Instead, it would help to say
explicitly that they are the same thing: when the mark is
active so is the region, and vice versa.