Re: Documentation of transient-mark-mode is sloppy, wrong, and confused.

[Eli Zaretskii]

> Date: Fri, 29 May 2009 09:27:09 +0000
> Cc: Stefan Monnier <address@hidden>, address@hidden,
>   address@hidden
> From: Alan Mackenzie <address@hidden>
> 
> My definition says "a region is
> active, when it will make itself the object manipulated by any of the
> commands `replace-string', `how-many', `keep-lines', `undo',
> `ispell-word', `ispell', `Mouse-3', `indent-for-tab-command',
> `fill-paragraph', `sgml-tag', <setting of colour text properties>,
> `set-justification-left/right/center/full/none', `comment-dwim',
> <VC-Directory-Mode's m, u commands>, <Stuff when delete-selection-mode
> is enabled>, `keyboard-quit'".

You are replacing a possibly obscure definition with one that is even
more obscure.  Your text says "a region is active when it is an object
manipulated by commands XXX, YYY, ZZZ, etc."  I cannot make heads or
tails of this definition.  And even if I could, it is not
instrumental, I cannot apply this definition to know when the region
is active and when it isn't.

I'm guessing that you wanted to say something like "region is active
when these and those commands operate on the region only, as opposed
to the entire buffer."  But that is a circular definition, because the
manual will say in a short while that "when region is active, some
commands operate on the region rather than on the whole buffer."

So I think trying to go in this direction will result in an impasse.

> Do you agree or disagree with me that this is what "active" means,
> regardless of my clumsy way of saying it?

I disagree.  You in effect say how an active region changes behavior
of Emacs commands, which is exactly what you didn't like in the
original text.

> If you disagree, what do think "active" actually does mean?

How about something along the following lines:

  The region can be in one of two states: active or inactive.  When
  the region is active, certain Emacs commands automatically operate
  on the text in the region, instead of on the whole buffer.  For
  example, bla-bla-bla.  By contrast, an inactive region can only be
  operated upon by commands specially designed for that job, such as
  @code{call-process-region}, @code{count-lines-region},
  @code{write-region}, etc.

  When the region is active, the function @code{region-active-p}
  returns a address@hidden value.

  The region becomes active when:

  <describe here the various ways of activating the region>

WDYT?