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

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

[Alan Mackenzie]

Hi, Emacs!

The description in the Emacs manual of Transient Mark Mode and related
topics falls somewhat short of being adequate.  In particular:

On page "Mark":

(i) There are no @dfn{active}, @dfn{active mark}, @dfn{active region}.
  o - My suggestion: "The region is termed @dfn{active} when it is
    highlighted.  The mark is @dfn{active} whenever the region is active.
    This usage of ``active'' is largely historical, originating from the
    time when region commands were disabled when the region wasn't
    highlighted."  (BTW: what is the correct past participle of
    "highlight"?  Is it "highlighted" or "highlit"?)

(ii) "If the mark is active, the region always extends between point and
  the mark," is gibberish.  Does the region only sometimes extend between
  point and mark in other circumstances?

(iii) There is confusion here as to whether a region continues to exist
  when it is "inactive".  My personal view is that the region comes into
  existence when the mark is first set, and both continue existing until
  the buffer is killed, regardless of whether they happen to be "active"
  at any particular time.

(iii) "The text between point and the mark is called \"the region\"",
  coupled with "The region persists only until you use it" implies that
  this text no longer "persists" after the region is "used".  This sort
  of suggests that "using" a region kills the text in it.  At any rate,
  this bit of manual gives a very sloppy impression, even if it does have
  a coherent meaning.

(iv) "The mark is automatically \"deactivated\" after certain non-motion
  commands, including any command that changes the text in the buffer."
  appears to be false.  (It's not possible to be definite here without
  knowing exactly what "active" means.)  At any rate, when the region is
  not highlit, C-w works.  (This is due to the default setting of the
  perplexingly named `mark-even-if-inactive'; I think this variable
  should be renamed to `allow-commands-on-inactive-region'.)

On page "Persistent Mark":

(v) The page title "Persistent Marks" is stupid.  Marks ARE persistent
  (see (iii) above) (unless you're talking about the ones which were
  superseded by euros in 2001).  This page should be renamed "Transient
  Mark Mode", or perhaps "Disabling Transient Mark Mode".  This comment
  also applies to most of the uses of "persistent" in this page.

(vi) "By default, the region is highlighted whenever it exists, and
  disappears once you use it or explicitly deactivate the mark.".  This
  is untrue, or at best horribly confused.  (See (iii) above).  What does
  it mean to say that a region "disappears"?  Given the given
  @dfn{region} (see (iii)), "disappears" can only mean "is killed", which
  is absurd.

(vii) This page fails explicitly to state the essence of deactivated
  transient mark mode, namely that the region isn't highlit.  Or, rather
  it mentions it only in the small print section, which nobody reads
  unless desperate.

(viii) "When Transient Mark mode is off, the mark is persistent: it is
  _never_ deactivated, but can be set to different locations using
  commands such as `C-<SPC>'.  After the first time you set the mark in a
  buffer, there is always a region in that buffer." is horribly
  confusing.
  o - This paragraph seems to hold, regardless of whether t-m-m is
    enabled, hence doesn't belong on this page.  Maybe.
  o - If an @dfn{active} region means a highlighted one (as I suggest
    above), then with disabled t-m-m, the region is NEVER ACTIVE, not
    "always active".

(ix) Etc.  There're more things sloppy in this page, but this email is
  already long enough.

#########################################################################

Additionally, there appears to be a conspiracy to marginalise the
classical Emacs mark handling.  Surely discussion of this belongs in the
main "Mark" page, not hidden in some misnamed subsidiary page.  I would
be prepared to make this change myself.

Other than that, the best way to fix all these faults, I believe, is to
replace all occurances of the ridiculous phrases "active region" and
"active mark" by the accurate "highlit region" (or "highlighted region"),
after which the absurdities will pretty much resolve themselves.

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[Chong Yidong]

Thanks; I've made some changes to the text to address these concerns.
Please take another look.

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

[Alan Mackenzie]

Hi, Yidong!

On Thu, May 28, 2009 at 12:54:15PM -0400, Chong Yidong wrote:
> Thanks; I've made some changes to the text to address these concerns.
> Please take another look.

;-).

The essence of my unhappiness is that "active" isn't defined.  You've
put in a formal @dfn{active}, but weaselled out of actually defining it.
You state what happens _when_ the mark is "active", but not what a mark
has to do or to be to acquire or to lose the essence of "active"ness.

You also haven't defined what a region has to do, be, or become, to be
"active".  The phrase "when the region is active" occurs several times
in the rest of the manual.  For the rest of this email, I'm going to
presume that the region is "active" exactly whenever the mark is.

If the term "active" cannot be defined, it should be purged from the
manual and the software, being replaced by terms we can define.  Surely?

As I see it, an "active" region has three attributes:
(i) C-w kills it;
(ii) It's highlit;
(iii) M-$ checks the spelling of EACH WORD IN THE REGION (as opposed to
  just the one surrounding point).

Now, which of these (or which combination of them) constitutes
"active"ness?

(i)? I guess it originally was, but due to the default setting of
  `mark-even-if-inactive', all regions are now active(i) all the time,
  rendering the entire description redundant and confusing.

(ii)? "Active" is a strange way of writing "highlit", but if this is the
  meaning, then when transient-mark-mode is nil (as described in
  "Persistent Mark"), the mark is NEVER active(ii).

(iii)? This cannot be.  The semantic chasm between "check the spelling
  of lots of words, not just one" and the dictionary meaning of "active"
  is just too vast.  Anyhow, with null t-m-m, the mark is NEVER
  active(iii).

########################################################################

In *scratch*, disable Transient Mark Mode, write the following line and
put the region as indicated:

    one two threeee
         ^         ^
	 |         |
       point     mark

The mark is now active (since t-m-m is nil).  Therefore the region is
"active".  Execute the command `ispell-word' with M-$; this is a command
which supposedly works on the region when the region is "active".  It
fails to flag the non-word "threeee", suggesting that it regards the
region as "inactive".  Energise transient transient-mark-mode with C-u
C-x C-x, and repeat M-$.  It now flags "threeee", as it should have done
before.

#########################################################################

I assert that the use of "active" in pages "Mark" and "Persistent Mark"
and most of the rest of the book, renders them incoherent and
meaningless, and that the only way to restore coherence is to get rid of
"active".

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[Chong Yidong]

Alan Mackenzie <acm@muc.de> writes:

> The essence of my unhappiness is that "active" isn't defined.  You've
> put in a formal @dfn{active}, but weaselled out of actually defining
> it.  You state what happens _when_ the mark is "active", but not what
> a mark has to do or to be to acquire or to lose the essence of
> "active"ness.

Good point; I've changed this accordingly.

As for changing the "active mark" terminology, that's not particularly
profitable, because it's already deeply embedded in the C and Lisp code
for over a decade.  (There are, of course, many other terminology
problems of this sort in Emacs.)  The main thing that's important, I
think, is that the description of the "transient-mark-mode enabled"
behavior and the "transient-mark-mode disabled" behavior are each
internally consistent; they aren't always mutually consistent, but
that's too bad.

> In *scratch*, disable Transient Mark Mode, write the following line and
> put the region as indicated:
>
>     one two threeee
>          ^         ^
> 	 |         |
>        point     mark
>
> The mark is now active (since t-m-m is nil).  Therefore the region is
> "active".  Execute the command `ispell-word' with M-$; this is a command
> which supposedly works on the region when the region is "active".  It
> fails to flag the non-word "threeee", suggesting that it regards the
> region as "inactive".

As described in the section about what happens when Transient Mark mode
is disabled:

  Some commands, which ordinarily operate on the region when the mark is
  active, instead act on the entire buffer.  For instance, @kbd{C-x u}
  normally reverses changes within the region if the mark is active;
  when Transient Mark mode is off, it acts on the entire buffer.
  However, you can type @kbd{C-u C-x u} to make it operate on the
  region.  @xref{Undo}.  Other commands that act this way are identified
  in their own documentation.

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

[Alan Mackenzie]

Good midnight, Yidong!

On Thu, May 28, 2009 at 04:48:15PM -0400, Chong Yidong wrote:
> Alan Mackenzie <acm@muc.de> writes:

> > The essence of my unhappiness is that "active" isn't defined.  You've
> > put in a formal @dfn{active}, but weaselled out of actually defining
> > it.  You state what happens _when_ the mark is "active", but not what
> > a mark has to do or to be to acquire or to lose the essence of
> > "active"ness.

> Good point; I've changed this accordingly.

Hmmm.  No you haven't.  You have noted one of the circumstances in which
a mark becomes active, yet haven't said what it is for a mark to BE
active.  It is as though a young child has asked you what "pregnant"
means, and the entire gist of your answer is "a woman becomes pregnant
after a kissing and cuddling session".  Unless you mention the growing
foetus, your answer is evasive and unhelpful, in fact not really an
answer at all.  What, exactly, is the essence of "active"ness, in the
same way that the foetus is the essence of pregnancy?

I think the answer has got to be along the following lines:  "The region
is called @dfn{active} when Emacs marks it internally as the portion of
buffer which any of a certain set of commands is to work on, when
otherwise the command would use the whole buffer, or a single word, or
some other portion of buffer.  When the region is active, the mark is
also said to be @dfn{active}." - essentially the (iii) from my previous
email.  Sorry for the poor wording - it's late and I'm tired.

With an actual definition such as this, it becomes clear that when
transient-mark-mode is disabled, the region and mark are always inactive.

> As for changing the "active mark" terminology, that's not particularly
> profitable, because it's already deeply embedded in the C and Lisp code
> for over a decade.

Bugs should be fixed, regardless of how long they've been in the source.
What's new here is that the current bug is no longer a mere option, it's
become a factory default.

> (There are, of course, many other terminology problems of this sort in
> Emacs.)

Are there?  I don't think there are.  "of this sort" here means "so vague
that you've got to struggle to pick up the meaning by osmosis".  I can't
think of any others, off hand.

> The main thing that's important, I think, is that the description of
> the "transient-mark-mode enabled" behavior and the "transient-mark-mode
> disabled" behavior are each internally consistent; they aren't always
> mutually consistent, but that's too bad.

Manuals shouldn't be patronising.  When a manual implicitly says "if you
can't even figure out what I mean by \"active\", you're stupid", that's
patronising.  A concrete example of this is in T. Capers Jones's book
"Estimating Software Costs", where he expounds expansively about
"function points" (some sort of measurement of functional content), yet
regards it as beneath him actually to say what a "function point" is, for
the benefit of ignorant cretins like me.  

> > In *scratch*, disable Transient Mark Mode, write the following line
> > and put the region as indicated:

> >     one two threeee
> >          ^         ^
> >          |         |
> >        point     mark

> > The mark is now active (since t-m-m is nil).  Therefore the region is
> > "active".  Execute the command `ispell-word' with M-$; this is a command
> > which supposedly works on the region when the region is "active".  It
> > fails to flag the non-word "threeee", suggesting that it regards the
> > region as "inactive".

> As described in the section about what happens when Transient Mark mode
> is disabled:

>   Some commands, which ordinarily operate on the region when the mark is
>   active, instead act on the entire buffer.

That is a definition of "active", surely, as I suggested above.  Surely,
it is better to regard the mark and region as being inactive when t-m-m
is disabled?

>   For instance, @kbd{C-x u} normally reverses changes within the region
>   if the mark is active; when Transient Mark mode is off, it acts on
>   the entire buffer.  However, you can type @kbd{C-u C-x u} to make it
>   operate on the region.  @xref{Undo}.  Other commands that act this
>   way are identified in their own documentation.

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[Davis Herring]

>>   Some commands, which ordinarily operate on the region when the mark is
>>   active, instead act on the entire buffer.
>
> That is a definition of "active", surely, as I suggested above.  Surely,
> it is better to regard the mark and region as being inactive when t-m-m
> is disabled?

It seems to me that there are two kinds of activeness of the mark (and the
region; they have between them only one state).  The first kind (call it
active1) is associated with commands like `kill-region', which refuse to
do anything unless the region is active1.  Outside of transient mark mode,
the mark is always active1 if it exists at all; with tmm, the mark is
frequently activated1 and deactivated1.

The other kind (active2) is associated with commands like `undo',
`insert-parentheses', and `how-many', which restrict, extend, or change
(respectively) their area of effect to be the region iff it is active2. 
Outside of transient mark mode, the mark is never active2 at all; with
tmm, the mark is active2 iff it is active1.

So we see that while there are two predicates, they can be resolved as (or
(not transient-mark-mode) (mark-active)) and (and transient-mark-mode
(mark-active)).  Since my imaginary function `mark-active' is only ever
called when tmm is on, we may take it to return nil otherwise and replace
active2 with just (mark-active).  There is then only one variable
"active", but tmm has different effects on different interpretations of
its value.

Sidebar: I like the 22 feature of turning tmm on temporarily; I don't like
it in general (partly because I like the mark being active1), but
otherwise I cannot have an active2 mark at all.

Davis

-- 
This product is sold by volume, not by mass.  If it appears too dense or
too sparse, it is because mass-energy conversion has occurred during
shipping.

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

[Chong Yidong]

Alan Mackenzie <acm@muc.de> writes:

>> As for changing the "active mark" terminology, that's not particularly
>> profitable, because it's already deeply embedded in the C and Lisp code
>> for over a decade.
>
> Bugs should be fixed, regardless of how long they've been in the source.
> What's new here is that the current bug is no longer a mere option, it's
> become a factory default.

No, changing the variable `mark-active' is a non-starter.  There's too
much code outside the Emacs source tree that depends on its current
meaning.

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

[Stefan Monnier]

> Hmmm.  No you haven't.  You have noted one of the circumstances in which
> a mark becomes active, yet haven't said what it is for a mark to BE
> active.  It is as though a young child has asked you what "pregnant"
> means, and the entire gist of your answer is "a woman becomes pregnant
> after a kissing and cuddling session".  Unless you mention the growing
> foetus, your answer is evasive and unhelpful, in fact not really an
> answer at all.  What, exactly, is the essence of "active"ness, in the
> same way that the foetus is the essence of pregnancy?

The problkem is that the activeness of the mark doesn't describe some
property of some other state.  It's a state itself.  In your analogy,
there's no foetus that would allow us to determine whether the mark
is active.  All we have is the `mark-active' variable, so in the end all
we can say is "the mark is active if the mark is active".

> I think the answer has got to be along the following lines:  "The region
> is called @dfn{active} when Emacs marks it internally as the portion of
> buffer which any of a certain set of commands is to work on, when
> otherwise the command would use the whole buffer, or a single word, or
> some other portion of buffer.  When the region is active, the mark is
> also said to be @dfn{active}." - essentially the (iii) from my previous
> email.  Sorry for the poor wording - it's late and I'm tired.

I would find this fairly confusing, giving the impression that Emacs
magically sometimes marks the region in some way outside of the
user's control.

> Surely, it is better to regard the mark and region as being inactive
> when t-m-m is disabled?

That's a delicate question, because mark-active sadly disagrees
with you.  Basically, I'd agree, but the code needs to be changed to
reflect that (by basically introducing a notion of "existing mark" as
distinct from "mark active").


        Stefan

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

[Kevin Rodgers]

Stefan Monnier wrote:
>> Hmmm.  No you haven't.  You have noted one of the circumstances in which
>> a mark becomes active, yet haven't said what it is for a mark to BE
>> active.  It is as though a young child has asked you what "pregnant"
>> means, and the entire gist of your answer is "a woman becomes pregnant
>> after a kissing and cuddling session".  Unless you mention the growing
>> foetus, your answer is evasive and unhelpful, in fact not really an
>> answer at all.  What, exactly, is the essence of "active"ness, in the
>> same way that the foetus is the essence of pregnancy?
> 
> The problkem is that the activeness of the mark doesn't describe some
> property of some other state.  It's a state itself.  In your analogy,
> there's no foetus that would allow us to determine whether the mark
> is active.  All we have is the `mark-active' variable, so in the end all
> we can say is "the mark is active if the mark is active".

Can't we say that "the mark is active if `mark-active' is non-nil"?

Note that mark-active is not mentioned in the Emacs manual, only in the
Emacs Lisp manual.

-- 
Kevin Rodgers
Denver, Colorado, USA

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

[Andreas Roehler]

Kevin Rodgers wrote:
> Stefan Monnier wrote:
>>> Hmmm.  No you haven't.  You have noted one of the circumstances in which
>>> a mark becomes active, yet haven't said what it is for a mark to BE
>>> active.  It is as though a young child has asked you what "pregnant"
>>> means, and the entire gist of your answer is "a woman becomes pregnant
>>> after a kissing and cuddling session".  Unless you mention the growing
>>> foetus, your answer is evasive and unhelpful, in fact not really an
>>> answer at all.  What, exactly, is the essence of "active"ness, in the
>>> same way that the foetus is the essence of pregnancy?
>>
>> The problkem is that the activeness of the mark doesn't describe some
>> property of some other state.  It's a state itself.  In your analogy,
>> there's no foetus that would allow us to determine whether the mark
>> is active.  All we have is the `mark-active' variable, so in the end all
>> we can say is "the mark is active if the mark is active".
> 
> Can't we say that "the mark is active if `mark-active' is non-nil"?
> 
> Note that mark-active is not mentioned in the Emacs manual, only in the
> Emacs Lisp manual.
> 


We have three states but two words for now to describe it

States are:

- the mark is set
- the mark is set and exists at different location from point, i.e. region has an extent
- region has an extent and is visible (transient-mark-mode on)

The both first may be described with `exist'
The both latter with `active'

Confusion might be solved naming the states

1) region-exists-p
2) region-has-extent
3) region-is-visible

Best regards

Andreas Röhler

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

[Stephen J. Turnbull]

Andreas Roehler writes:

 > 1) region-exists-p
 > 2) region-has-extent

Please don't use this term this way.  It would be very confusing for
XEmacs.

It's not clear to me why anybody cares about whether the region has
non-zero length or not, anyway.  It seems to me that `region-exists-p'
and `region-active-p' as used in XEmacs would be sufficient.

 > 3) region-is-visible

I don't understand what Alan's problem with "active regions" is.  As
I've pointed out in the past, although "receptive" might be a better
term, usages like "active receptor" (in biochemistry) are very common.
If Alan is essentially unique in this objection, and he seems to be
(sorry, Alan!) then I see no need to cater to him.

 > 
 > Best regards
 > 
 > Andreas Röhler
 > 

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Thu, 28 May 2009 21:55:51 -0400
> Cc: Chong Yidong <cyd@stupidchicken.com>, emacs-devel@gnu.org
> 
> > I think the answer has got to be along the following lines:  "The region
> > is called @dfn{active} when Emacs marks it internally as the portion of
> > buffer which any of a certain set of commands is to work on, when
> > otherwise the command would use the whole buffer, or a single word, or
> > some other portion of buffer.  When the region is active, the mark is
> > also said to be @dfn{active}." - essentially the (iii) from my previous
> > email.  Sorry for the poor wording - it's late and I'm tired.
> 
> I would find this fairly confusing

So would I.  If you read this text carefully, it actually says
something like "the region is active when Emacs marks it as active."
That's hardly a definition of what "active" is.

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

[Eli Zaretskii]

> Date: Thu, 28 May 2009 23:03:59 +0000
> From: Alan Mackenzie <acm@muc.de>
> Cc: emacs-devel@gnu.org
> 
> > The main thing that's important, I think, is that the description of
> > the "transient-mark-mode enabled" behavior and the "transient-mark-mode
> > disabled" behavior are each internally consistent; they aren't always
> > mutually consistent, but that's too bad.
> 
> Manuals shouldn't be patronising.  When a manual implicitly says "if you
> can't even figure out what I mean by \"active\", you're stupid", that's
> patronising.

Did the manual actually say that? where?

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

[Alan Mackenzie]

Hi, Stephen!

On Fri, May 29, 2009 at 05:25:44PM +0900, Stephen J. Turnbull wrote:
> Andreas Roehler writes:

>  > 1) region-exists-p
>  > 2) region-has-extent

> Please don't use this term this way.  It would be very confusing for
> XEmacs.

> It's not clear to me why anybody cares about whether the region has
> non-zero length or not, anyway.

<sarcasm> Obviously the situation was too simple and obvious, so it was
necessary to introduce some complication to make people sit up and think.
</sarcasm>

I'm speculating here: When a region has zero length, it's difficult to
see the highlighting on it.  Because it "looks" as thought the region is
not "active", it's possibly better to handle user commands as though it
weren't "active".  Maybe.

> It seems to me that `region-exists-p' and `region-active-p' as used in
> XEmacs would be sufficient.

Does XEmacs have a definition of an "active region"?  ;-)

>  > 3) region-is-visible

> I don't understand what Alan's problem with "active regions" is.  As
> I've pointed out in the past, although "receptive" might be a better
> term, usages like "active receptor" (in biochemistry) are very common.
> If Alan is essentially unique in this objection, and he seems to be
> (sorry, Alan!) then I see no need to cater to him.

No problem!  But that's not my gripe here.  (My objection to using words
like "active" to describe a state which isn't "being an agent" is that
such loose usage is liable to lead to confusion.  Here, it has manifestly
lead to massive confusion.)

My problem is that the technical word "active" is used without being
defined.  I surely can't be the only Emacs user who feels patronised and
insulted when manuals talk down at me by using fancy words without saying
what they mean.  Often, when manual authors do this, it is because they
themselves don't know what their fancy word means either, as is the case
here.  "But EVERYBODY know what \"active\" means!" just won't do.

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[Alan Mackenzie]

Hi, Eli!

On Fri, May 29, 2009 at 11:37:26AM +0300, Eli Zaretskii wrote:
> > From: Stefan Monnier <monnier@iro.umontreal.ca>
> > Date: Thu, 28 May 2009 21:55:51 -0400
> > Cc: Chong Yidong <cyd@stupidchicken.com>, emacs-devel@gnu.org

> > > I think the answer has got to be along the following lines:  "The region
> > > is called @dfn{active} when Emacs marks it internally as the portion of
> > > buffer which any of a certain set of commands is to work on, when
> > > otherwise the command would use the whole buffer, or a single word, or
> > > some other portion of buffer.  When the region is active, the mark is
> > > also said to be @dfn{active}." - essentially the (iii) from my previous
> > > email.  Sorry for the poor wording - it's late and I'm tired.

> > I would find this fairly confusing

> So would I.  If you read this text carefully, it actually says
> something like "the region is active when Emacs marks it as active."
> That's hardly a definition of what "active" is.

Well, it's just as good as anybody else has come up with, so far!

But the criticism isn't quite fair.  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'".  At least, it would have done if I'd've
been wide enough awake.

Do you agree or disagree with me that this is what "active" means,
regardless of my clumsy way of saying it?  If you disagree, what do
think "active" actually does mean?

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[Alan Mackenzie]

Hi, Eli!

On Fri, May 29, 2009 at 11:38:26AM +0300, Eli Zaretskii wrote:
> > Date: Thu, 28 May 2009 23:03:59 +0000
> > From: Alan Mackenzie <acm@muc.de>
> > Cc: emacs-devel@gnu.org

> > > The main thing that's important, I think, is that the description
> > > of the "transient-mark-mode enabled" behavior and the
> > > "transient-mark-mode disabled" behavior are each internally
> > > consistent; they aren't always mutually consistent, but that's too
> > > bad.

> > Manuals shouldn't be patronising.  When a manual implicitly says "if
> > you can't even figure out what I mean by \"active\", you're stupid",
> > that's patronising.

> Did the manual actually say that? where?

No, it didn't _actually_ say that, it _implicitly_ said it; or, more
precisely, that's the message I would hear if I were an Emacs user trying
to make sense of that page of the manual.

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[Eli Zaretskii]

> Date: Fri, 29 May 2009 09:35:33 +0000
> Cc: cyd@stupidchicken.com, emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> > > Manuals shouldn't be patronising.  When a manual implicitly says "if
> > > you can't even figure out what I mean by \"active\", you're stupid",
> > > that's patronising.
> 
> > Did the manual actually say that? where?
> 
> No, it didn't _actually_ say that, it _implicitly_ said it; or, more
> precisely, that's the message I would hear if I were an Emacs user trying
> to make sense of that page of the manual.

What text, exactly, could send such a message?

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

[Stephen J. Turnbull]

Eli Zaretskii writes:

 > > > email.  Sorry for the poor wording - it's late and I'm tired.
 > > 
 > > I would find this fairly confusing
 > 
 > So would I.  If you read this text carefully, it actually says
 > something like "the region is active when Emacs marks it as active."
 > That's hardly a definition of what "active" is.

Read a little more carefully.  It also explains how the behavior of
Emacs changes when the mark is active.  That *is* a definition of 
"active".  ACM did say he was tired, but he's rarely *that* tired.

How about

    In Emacs, the region is the substring of buffer text between point
    and mark.  If the mark is not set, then there is no region.
    (Point always exists, and the mark is normally set early in the
    life of a buffer, and is moved, not unset, thereafter.)  Some
    commands operate on this region, copying it, killing it, deleting
    it, or transforming it.  [Insert list here if you like.]

    In transient mark mode, the region may be active or inactive.
    This is implemented as an internal flag which is set implicitly by
    commands which highlight the region (for example, "shifted motion
    commands").  The flag's value is accessed with `region-active-p'.
    In transient mark mode, commands that operate on the region
    require it to be active, or they signal an error.  That is, when
    transient mark mode is on, we say the region is @def{active} when
    region commands are effective.  Otherwise, we say the region is
    @def{not active}.

    When transient mark mode is off, the region is never highlighted,
    and commands that operate on the region will error only in the
    case that the mark is unset in that buffer, and the region does
    not exist.  We also say the region is @def{not active} whenever
    transient mark mode is off.

    As a sort of abuse of terminology, it is often said that "the mark
    is active" (resp. "not active"), when what is meant is "the region
    is active" (resp. "not active").  "Inactive" may be used as a
    synonym for "not active".

I'm probably missing or wrong on some details, but as an outline
something like the above should do.

IMO, a large part of the problem here is confusing the mark with the
region.  If the mark is set, you can always do `(goto-char (mark))' or
M-x pop-mark, etc.  The mark is *not* transient.  The region is.  But
I guess it's too late to fix that.

I swear on a stack of Bibles that the above text was written by me, my
employer has no clue or claim on it, and I hereby contribute it to
XEmacs (and veto its application since we don't have transient mark
mode, thank Jamie!)  But it's now the FSF's; do with it what you will,
my papers for XEmacs are on file.

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 <monnier@iro.umontreal.ca>, cyd@stupidchicken.com,
>   emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> 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 non-@code{nil} value.

  The region becomes active when:

  <describe here the various ways of activating the region>

WDYT?

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

[Eli Zaretskii]

> From: "Stephen J. Turnbull" <stephen@xemacs.org>
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,
>     acm@muc.de,
>     cyd@stupidchicken.com,
>     emacs-devel@gnu.org
> Date: Fri, 29 May 2009 18:55:29 +0900
> 
> Eli Zaretskii writes:
> 
>  > > > email.  Sorry for the poor wording - it's late and I'm tired.
>  > > 
>  > > I would find this fairly confusing
>  > 
>  > So would I.  If you read this text carefully, it actually says
>  > something like "the region is active when Emacs marks it as active."
>  > That's hardly a definition of what "active" is.
> 
> Read a little more carefully.  It also explains how the behavior of
> Emacs changes when the mark is active.  That *is* a definition of 
> "active".

Right, but that "definition-through-behavior" was exactly what Alan
opposed to in the first place!

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

[Andreas Roehler]

Stephen J. Turnbull wrote:
> Eli Zaretskii writes:
> 
>  > > > email.  Sorry for the poor wording - it's late and I'm tired.
>  > > 
>  > > I would find this fairly confusing
>  > 
>  > So would I.  If you read this text carefully, it actually says
>  > something like "the region is active when Emacs marks it as active."
>  > That's hardly a definition of what "active" is.
> 
> Read a little more carefully.  It also explains how the behavior of
> Emacs changes when the mark is active.  That *is* a definition of 
> "active".  ACM did say he was tired, but he's rarely *that* tired.
> 
> How about
> 
>     In Emacs, the region is the substring of buffer text between point
>     and mark.  If the mark is not set, then there is no region.
>     (Point always exists, and the mark is normally set early in the
>     life of a buffer, and is moved, not unset, thereafter.)  Some
>     commands operate on this region, copying it, killing it, deleting
>     it, or transforming it.  [Insert list here if you like.]
> 
>     In transient mark mode, the region may be active or inactive.
>     This is implemented as an internal flag which is set implicitly by
>     commands which highlight the region (for example, "shifted motion
>     commands").  The flag's value is accessed with `region-active-p'.
>     In transient mark mode, commands that operate on the region
>     require it to be active, or they signal an error.  That is, when
>     transient mark mode is on, we say the region is @def{active} when
>     region commands are effective.  Otherwise, we say the region is
>     @def{not active}.
> 
>     When transient mark mode is off, the region is never highlighted,
>     and commands that operate on the region will error only in the
>     case that the mark is unset in that buffer, and the region does
>     not exist. 

IMHO its better to let this up to the programmer/circumstances.
It might be well useful to make user aware of region via highlighting,
preventing accidently killing and the like.

Raised was just the question if the highlighting should be called
´transient-mark-mode' - as there is no transition so far.

Why not introduce `region-highlight-mode' instead?


 We also say the region is @def{not active} whenever
>     transient mark mode is off.
> 
>     As a sort of abuse of terminology, it is often said that "the mark
>     is active" (resp. "not active"), when what is meant is "the region
>     is active" (resp. "not active").  "Inactive" may be used as a
>     synonym for "not active".
> 
> I'm probably missing or wrong on some details, but as an outline
> something like the above should do.
> 
> IMO, a large part of the problem here is confusing the mark with the
> region.  If the mark is set, you can always do `(goto-char (mark))' or
> M-x pop-mark, etc.  The mark is *not* transient.  The region is.  But
> I guess it's too late to fix that.
> 
> I swear on a stack of Bibles that the above text was written by me, my
> employer has no clue or claim on it, and I hereby contribute it to
> XEmacs (and veto its application since we don't have transient mark
> mode, thank Jamie!)  But it's now the FSF's; do with it what you will,
> my papers for XEmacs are on file.
> 
> 
> 

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

[Alan Mackenzie]

Hi, Davis!

On Thu, May 28, 2009 at 04:53:14PM -0700, Davis Herring wrote:
> >>   Some commands, which ordinarily operate on the region when the
> >>   mark is active, instead act on the entire buffer.

> > That is a definition of "active", surely, as I suggested above.
> > Surely, it is better to regard the mark and region as being inactive
> > when t-m-m is disabled?

> It seems to me that there are two kinds of activeness of the mark (and
> the region; they have between them only one state).  The first kind
> (call it active1) is associated with commands like `kill-region', which
> refuse to do anything unless the region is active1.  Outside of
> transient mark mode, the mark is always active1 if it exists at all;
> with tmm, the mark is frequently activated1 and deactivated1.

> The other kind (active2) is associated with commands like `undo',
> `insert-parentheses', and `how-many', which restrict, extend, or change
> (respectively) their area of effect to be the region iff it is active2. 
> Outside of transient mark mode, the mark is never active2 at all; with
> tmm, the mark is active2 iff it is active1.

Bingo!  That's the answer!  Thanks!

So an honest @dfn{active} would be along the lines:

    Historically, @dfn{active region} has had two distinct, sometimes
    contradictory meanings:
    @itemize @bullet
    @item
    Certain commands which use the region, such as @key{C-w}
    (@code{kill-region}) are disabled when the region isn't @dfn{active}.
    As from Emacs 23, the region is now always ``active'' in this sense,
    unless you set the user option @code{mark-even-when-inactive}
    (@pxref{...}).
    @item
    Certain commands work in an enhanced manner when the region is
    @dfn{active}: for example, `fill-paragraph' (@pxref{..}) fills the
    region when it is active, rather than just the current paragraph.
    When the region is ``active'' in this sense, it is highlit.
    @end @itemize

    Most uses of ``active'' in this manual have the second meaning.

> So we see that while there are two predicates, they can be resolved as (or
> (not transient-mark-mode) (mark-active)) and (and transient-mark-mode
> (mark-active)).

I think these can be more simply expressed as (i) mark-active and (ii)
(use-region-p).

> Since my imaginary function `mark-active' is only ever called when tmm
> is on, we may take it to return nil otherwise and replace active2 with
> just (mark-active).  There is then only one variable "active", but tmm
> has different effects on different interpretations of its value.

> Sidebar: I like the 22 feature of turning tmm on temporarily; I don't like
> it in general (partly because I like the mark being active1), but
> otherwise I cannot have an active2 mark at all.

Doesn't (setq mark-even-if-inactive t) do what you want?

> Davis

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[Alan Mackenzie]

Hi, Eli!

On Fri, May 29, 2009 at 01:11:30PM +0300, Eli Zaretskii wrote:
> > Date: Fri, 29 May 2009 09:27:09 +0000
> > Cc: Stefan Monnier <monnier@iro.umontreal.ca>, cyd@stupidchicken.com,
> >   emacs-devel@gnu.org
> > From: Alan Mackenzie <acm@muc.de>

> > My definition says "a region is
> > active, when ....

> 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 think what you come up with below is more or less the same as I was
trying to construct.  But I'm glad we agree about what the definition is
needed for.

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

I think that isn't circularity, it's repetition - the first bit stands on
its own.  Even if it is formally circular, I think its meaning is clear.

We're in danger of descending into philosophy, here.

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

It would result in something better than what was there before, even if
perhaps not 100% formally valid.

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

I'm not sure whether that's a fair criticism or not.  The original "Mark"
page didn't define "active" at all.  Yidong's second amendment still
didn't define "active", instead describing how you made a region
"active".  The one in the middle?  I can't remember it exactly, and
cvs.savannah.gnu.org is down at the moment.  There was something about it
which either didn't define "active", or wasn't clearly a definition.

Defining a state by saying what its effect on Emacs is is the canonical
way to define it.

> > 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 non-@code{nil} value.

>   The region becomes active when:

>   <describe here the various ways of activating the region>

> WDYT?

I pretty much agree with you.  Except, Davis has discerned that we have
been using "active" in two incompatible ways.

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[Alan Mackenzie]

On Fri, May 29, 2009 at 12:48:39PM +0300, Eli Zaretskii wrote:
> > Date: Fri, 29 May 2009 09:35:33 +0000
> > Cc: cyd@stupidchicken.com, emacs-devel@gnu.org
> > From: Alan Mackenzie <acm@muc.de>

> > > > Manuals shouldn't be patronising.  When a manual implicitly says
> > > > "if you can't even figure out what I mean by \"active\", you're
> > > > stupid", that's patronising.

> > > Did the manual actually say that? where?

> > No, it didn't _actually_ say that, it _implicitly_ said it; or, more
> > precisely, that's the message I would hear if I were an Emacs user
> > trying to make sense of that page of the manual.

> What text, exactly, could send such a message?

All the text using the obscure undefined word "active".

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

[Stefan Monnier]

>   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 non-@code{nil} value.

>   The region becomes active when:

>   <describe here the various ways of activating the region>

That looks pretty good to me.  Of course it also needs to say when the
region becomes inactive.


        Stefan

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

[Drew Adams]

I really didn't want to add to this thread, but it sounds like you might
actually end up changing the doc for this, so I will.

I don't know what the doc (including both manuals and all doc strings) says now,
in detail, and I don't have time to check. I think my recollection is probably
pretty correct about this, but if the doc somewhere doesn't fit my impression,
it can be fixed.

Summary: "active" applies only to transient-mark-mode. It is misguided to
interpret it otherwise or explain it otherwise, in the doc or here.


1. The mark's existence in a given buffer, and hence the region's existence
there, is an accessory question. It affects Lisp code and it affects whether you
can do region things (obviously), but it is not related to the notion of
"active" region or mark.

2. Similarly, whether the region is empty (point=mark) is accessory to the
question of region activeness - and to the question of region existence. These
things each need to be dealt with separately, before discussing them together
(e.g. in the description of the behavior of some command that tests one or more
of them).

3. It is OK to call the region, and even the mark, "active" and "inactive", if
we want to. (Sorry, Alan.) Stephen is right here. We could perhaps come up with
better terms, but we should not, at this point.

4. Davis is right about there being two notions of activeness (in this thread).
But only if we confuse things by applying the term "active" to things it has
never been applied to (in the doc).

AFAIK, we have never, in the doc, referred to activeness other than in the
context of transient-mark-mode, that is, when t-m-m is on. Activeness of the
region or mark is a notion that is applicable only to t-m-m. If t-m-m mode is
off, then the region is neither active nor inactive. It just is (or isn't, if
there is no mark). Once we make this clear (to each other and to doc readers),
the "problem" disappears.

5. Both Davis's active1 and active2 reflect this (#4).

With t-m-m on, the region is active1 iff the "region is active" in traditional
parlance. With t-m-m off, the region is active1 always (provided the mark
exists). That last statement says that active1 is only a t-m-m notion.

Likewise, for Davis's active2. With t-m-m on, the region is active2 iff the
"region is active" in traditional parlance. With t-m-m off, the region is never
active2. Again, that last statement says that active2 is only a t-m-m notion.

If you are always happy, regardless of the phase of the moon, then the moon
phase no bearing on your happiness. Likewise, if you are never happy.

6. Temporary t-m-m does not complicate things, in terms of the notion of
"active" region. It is just a temporary use of t-m-m. Everything is consistent
in this regard, AFAIK. (I'm no expert on temporary t-m-m, however, and I'm not
vouching for its doc.)

7. The proper predicate for testing whether the region is (in)active is (null
mark-active). That's all. But again, such a test makes sense only when t-m-m
mode is on. If you are testing only `mark-active' outside of t-m-m, then you are
wasting your time.

8. Whether or not you can do certain things with the region, and knowing whether
a given command will operate on the region (or the whole buffer or whatever), is
orthogonal to whether you are in t-m-m and, if so, whether the region is active.
That is, whether the command even looks at the region and the t-m-m state
(`mark-active') is up to the command.

It is the particular command that decides what happens in any given context:
whether it acts on the region; whether it does so regardless of t-m-m; whether,
if in t-m-m, the action is different whether the region is active or not; and so
on.

9. The confusion for Alan and perhaps some other users and doc readers is that
they have gotten the impression that the region being "active" has some meaning
outside t-m-m. They (mis)read doc that talks about some command's acting or not
acting on the region depending on whether the region is active. They interpret
the use of "active" here to apply also when t-m-m is off, as if it speaks to
whether or not the region is _usable_ by the command or whether the command is
region-aware.

This confusion comes perhaps from imperfect wording - dunno. The doc should
state clearly (remind readers) that any behavior that is conditional on whether
the region is active is conditional only when t-m-m is on, because the region
can be active only when t-m-m is on.

10. A further consideration is whether the region is empty, that is, point=mark.
This distinction makes sense independently of t-m-m. "Active region" applies
only to t-m-m, but "empty region" applies whether t-m-m is on or off. (It does
not apply always, however. A region cannot be empty or non-empty if it does not
yet exist.)

11. Similarly, for the existence of the mark (hence the region) in a given
buffer. This distinction makes sense independently of t-m-m. This distinction is
always available - it is the only condition of the three that can always be
tested. You cannot test (numerically) whether point=mark unless the mark exists.
You cannot test whether the mark is active unless t-m-m is on. 

12. "Well, hold it", you say. You can test `mark-active' anytime. Yes, but
without also testing t-m-m the value of variable `mark-active' won't tell you
whether the mark/region is active. This is a possible source of confusion for
those readers who use Emacs Lisp. The doc of `mark-active' just needs to make it
clear that it is a variable that applies only to t-m-m.

13. The behavior of some commands can be conditional on: (1) t-m-m region
activeness (so with t-m-m mode off there is no distinction/condition); (2)
region emptiness; (3) region existence; or some combination of 1-3.

The existence test can always be used to change command behavior. The emptiness
test can be used anytime the mark exists. Testing for an active region can be
done only when t-m-m mode is on.

14. The doc for a given command needs to make clear the various behavior changes
and the conditions that determine them. The introduction of such conditional
commands, especially those that check for an active region, has, I think, led to
confusion for some people. We need to be very clear in their doc about these
notions and tests.

In particular, to help readers understand such doc strings (after we've made the
strings clear), we need to _remind_ readers here and there of these things: (1)
The mark might not exist in some buffer; it does not exist until you set mark.
(2) The region might be empty, which means point=mark. (3) If t-m-m mode is off,
then whether the region is active cannot be tested: active region is a t-m-m
concept.

15. If it helps, we can state somewhere that the full name of the notion "active
region" is "transient-mark-mode active region". The former is really an
abbreviation for the latter. Speaking only of "active region" is like speaking
only of "the length" instead of "the line length".

As long as we were speaking only in the context of t-m-m, there was no problem.
But as soon as we speak of "active region" in a context (e.g. some command
behavior) where t-m-m does not necessarily apply, we need to make it very clear
that this is a t-m-m notion only.

16. I don't have a concrete suggestion for changing any terminology. A priori, I
think we should keep the current terminology, which fits with `mark-active' etc.

17. But we should clarify the doc wherever that might be needed. The doc string
for `mark-active', for instance, is one place to start: "Non-nil means the mark
and region are currently active in this buffer." We need to add something like
this: "The value is used only when transient-mark-mode is on. Active and
inactive mark and region apply only to transient-mark-mode."

HTH. In sum, the solution is to recognize and make clear(er) that "active"
applies only to t-m-m. It is misguided to try to describe or define "active"
outside t-m-m. Trust me, that attempt would ultimately make things far _more_
confusing. (Sorry, Alan.)

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

[Alan Mackenzie]

Hi, Drew,

Thanks very much for this post!

On Fri, May 29, 2009 at 09:40:03AM -0700, Drew Adams wrote:
> I really didn't want to add to this thread, but it sounds like you might
> actually end up changing the doc for this, so I will.

> I don't know what the doc (including both manuals and all doc strings)
> says now, in detail, and I don't have time to check. I think my
> recollection is probably pretty correct about this, but if the doc
> somewhere doesn't fit my impression, it can be fixed.

> Summary: "active" applies only to transient-mark-mode. It is misguided
> to interpret it otherwise or explain it otherwise, in the doc or here.


> 1. The mark's existence in a given buffer, and hence the region's
> existence there, is an accessory question. It affects Lisp code and it
> affects whether you can do region things (obviously), but it is not
> related to the notion of "active" region or mark.

> 2. Similarly, whether the region is empty (point=mark) is accessory to
> the question of region activeness - and to the question of region
> existence. These things each need to be dealt with separately, before
> discussing them together (e.g. in the description of the behavior of
> some command that tests one or more of them).

> 3. It is OK to call the region, and even the mark, "active" and
> "inactive", if we want to. (Sorry, Alan.) Stephen is right here. We
> could perhaps come up with better terms, but we should not, at this
> point.

:-)  No apologies needed.  I don't like "active", but clearly it's going
to stay.  The bad thing is not having it defined, and thus everybody
having a different idea of what it means.

> 4. Davis is right about there being two notions of activeness (in this
> thread).  But only if we confuse things by applying the term "active"
> to things it has never been applied to (in the doc).

I don't think you're right about this.  Even with t-m-m enabled, there's
both types of "active"ness - the one which highlights, and the other
which you permanently activate by setting `mark-even-if-inactive'.

> AFAIK, we have never, in the doc, referred to activeness other than in
> the context of transient-mark-mode, that is, when t-m-m is on.
> Activeness of the region or mark is a notion that is applicable only to
> t-m-m. If t-m-m mode is off, then the region is neither active nor
> inactive. It just is (or isn't, if there is no mark). Once we make this
> clear (to each other and to doc readers), the "problem" disappears.

I would support this solution wholeheartedly.

> 5. Both Davis's active1 and active2 reflect this (#4).

> With t-m-m on, the region is active1 iff the "region is active" in
> traditional parlance. With t-m-m off, the region is active1 always
> (provided the mark exists). That last statement says that active1 is
> only a t-m-m notion.

Yes.

> Likewise, for Davis's active2. With t-m-m on, the region is active2 iff
> the "region is active" in traditional parlance. With t-m-m off, the
> region is never active2. Again, that last statement says that active2
> is only a t-m-m notion.

Yes.

> If you are always happy, regardless of the phase of the moon, then the
> moon phase no bearing on your happiness. Likewise, if you are never
> happy.

> 6. Temporary t-m-m does not complicate things, in terms of the notion
> of "active" region. It is just a temporary use of t-m-m. Everything is
> consistent in this regard, AFAIK. (I'm no expert on temporary t-m-m,
> however, and I'm not vouching for its doc.)

Yes.

> 7. The proper predicate for testing whether the region is (in)active is
> (null mark-active). That's all. But again, such a test makes sense only
> when t-m-m mode is on. If you are testing only `mark-active' outside of
> t-m-m, then you are wasting your time.

This is active1.  This is always t (unless `mark-even-if-inactive' is set
to nil).

> 8. Whether or not you can do certain things with the region, and
> knowing whether a given command will operate on the region (or the
> whole buffer or whatever), is orthogonal to whether you are in t-m-m
> and, if so, whether the region is active.  That is, whether the command
> even looks at the region and the t-m-m state (`mark-active') is up to
> the command.

I'm not sure what you're saying here.  I agree with your second sentence,
but I'm not sure how it connects with the first, which doesn't seem
right.

> It is the particular command that decides what happens in any given
> context: whether it acts on the region; whether it does so regardless
> of t-m-m; whether, if in t-m-m, the action is different whether the
> region is active or not; and so on.

> 9. The confusion for Alan and perhaps some other users and doc readers
> is that they have gotten the impression that the region being "active"
> has some meaning outside t-m-m. They (mis)read doc that talks about
> some command's acting or not acting on the region depending on whether
> the region is active. They interpret the use of "active" here to apply
> also when t-m-m is off, as if it speaks to whether or not the region is
> _usable_ by the command or whether the command is region-aware.

Thanks!  That's a very helpful way of characterising the problem.  There
are a lot of places in the manual which say "when the region is active",
without mentioning disabled t-m-m.

> This confusion comes perhaps from imperfect wording - dunno. The doc
> should state clearly (remind readers) that any behavior that is
> conditional on whether the region is active is conditional only when
> t-m-m is on, because the region can be active only when t-m-m is on.

Agreed wholeheartedly.  This clarification should occur at every point in
the doc which mentions "active"ness.

> 10. A further consideration is whether the region is empty, that is,
> point=mark.  This distinction makes sense independently of t-m-m.
> "Active region" applies only to t-m-m, but "empty region" applies
> whether t-m-m is on or off. (It does not apply always, however. A
> region cannot be empty or non-empty if it does not yet exist.)

Is this so important?  Some commands take the same action for empty
region as inactive region.  This seems an orthogonal issue.

> 11. Similarly, for the existence of the mark (hence the region) in a
> given buffer. This distinction makes sense independently of t-m-m. This
> distinction is always available - it is the only condition of the three
> that can always be tested. You cannot test (numerically) whether
> point=mark unless the mark exists.  You cannot test whether the mark is
> active unless t-m-m is on. 

If you talk about "the region", what you say clearly only applies after
the mark has been set.

> 12. "Well, hold it", you say. You can test `mark-active' anytime. Yes,
> but without also testing t-m-m the value of variable `mark-active'
> won't tell you whether the mark/region is active. This is a possible
> source of confusion for those readers who use Emacs Lisp. The doc of
> `mark-active' just needs to make it clear that it is a variable that
> applies only to t-m-m.

`mark-active' is active1, and can't now be changed.  Its doc string
should make clear that its notion of "active" is different from the more
useful active2.

> 13. The behavior of some commands can be conditional on: (1) t-m-m
> region activeness (so with t-m-m mode off there is no
> distinction/condition); (2) region emptiness; (3) region existence; or
> some combination of 1-3.

> The existence test can always be used to change command behavior. The
> emptiness test can be used anytime the mark exists. Testing for an
> active region can be done only when t-m-m mode is on.

> 14. The doc for a given command needs to make clear the various behavior changes
> and the conditions that determine them. The introduction of such conditional
> commands, especially those that check for an active region, has, I think, led to
> confusion for some people. We need to be very clear in their doc about these
> notions and tests.

That means revising lots of doc strings, doesn't it?  ;-)

> In particular, to help readers understand such doc strings (after we've made the
> strings clear), we need to _remind_ readers here and there of these things: (1)
> The mark might not exist in some buffer; it does not exist until you set mark.
> (2) The region might be empty, which means point=mark. (3) If t-m-m mode is off,
> then whether the region is active cannot be tested: active region is a t-m-m
> concept.

> 15. If it helps, we can state somewhere that the full name of the notion "active
> region" is "transient-mark-mode active region". The former is really an
> abbreviation for the latter. Speaking only of "active region" is like speaking
> only of "the length" instead of "the line length".

A masterpiece of clear thinking!  Thanks.

> As long as we were speaking only in the context of t-m-m, there was no problem.
> But as soon as we speak of "active region" in a context (e.g. some command
> behavior) where t-m-m does not necessarily apply, we need to make it very clear
> that this is a t-m-m notion only.

> 16. I don't have a concrete suggestion for changing any terminology. A priori, I
> think we should keep the current terminology, which fits with `mark-active' etc.

The "active" we usually mean is active2.  The "active" in `mark-active'
is active1.  Something needs to give, somewhere.

> 17. But we should clarify the doc wherever that might be needed. The doc string
> for `mark-active', for instance, is one place to start: "Non-nil means the mark
> and region are currently active in this buffer." We need to add something like
> this: "The value is used only when transient-mark-mode is on. Active and
> inactive mark and region apply only to transient-mark-mode."

> HTH. In sum, the solution is to recognize and make clear(er) that "active"
> applies only to t-m-m. It is misguided to try to describe or define "active"
> outside t-m-m. Trust me, that attempt would ultimately make things far _more_
> confusing. (Sorry, Alan.)

Thanks for such a helpful post, Drew.

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[Drew Adams]

> Thanks very much for this post!

You're welcome.

> > 4. Davis is right about there being two notions of activeness
> > (in this thread).  But only if we confuse things by applying
> > the term "active" to things it has never been applied to
> > (in the doc).
> 
> I don't think you're right about this.

Notice the parts in parens. "Active" should never be used in the doc to mean
anything other than _transient-mark-mode_ active region (or mark). In this
thread, people, including Davis, have applied "active" to other things. But the
doc should not.

[It _should_ not, IMO, and I thought that it also _did_ not, but I see that
Emacs 22 Emacs manual node Transient Mark does speak about the "normal mode of
use" (i.e. with t-m-m turned off) having mark-setting commands "activate" the
mark. I think this language is not helpful. 

That node attempts to introduce the concept of active region, which is purely
for t-m-m, by an analogy to the situation where t-m-m is off. Which is OK. But
it should not use the terms "active" or "activate" when referring to the mark or
region with t-m-m off. This abuse of language hurts more than it helps.

Proof that this is slippery analogy, and not the definition of "active", is that
this explanation of the "normal mode" activating the mark is said to be so
because "there is _always_ a region". This confuses region existence with region
activeness. And a few sentences later, it says that in t-m-m "most of the time
there is no region"!

No wonder people are confused. And in the Emacs 23 manual, things are not
necessarily much better. It speaks of the region being "highlighted whenever it
exists", and so on.

I'll leave the manual alone now. I'll speak about what I think it should say,
rather than what it might really say at the moment.]

> Even with t-m-m enabled, there's both types of "active"ness
> - the one which highlights,

That is the only activeness, as far as the doc use of the word is concerned
(modulo the exceptions mentioned above). If the region is not active (which
means not active in t-m-m), then it is not highlighted. If it is not
highlighted, then it is not active (which means not active in t-m-m).

Region highlighting outside of t-m-m (e.g. using a mouse, with t-m-m off) is
perhaps another gray area. I don't know much about that. Does it have the same
effect in all cases as a temporary t-m-m? I kind of doubt it. But let's leave
this aside, for the moment. We might have to rationalize that behavior, to bring
it into line with t-m-m, - or not: leave it as something different altogether.
But in any case, my suggestion is that we not use the work "active" to describe
it (unless it can be made 100% identical to a temporary t-m-m).

> and the other which you permanently activate by setting
> `mark-even-if-inactive'.

Non-nil `mark-even-if-inactive' does not make the region _active_ (in the sense
I favor). It simply means that you can _use_ the region (or mark) even when it
is inactive. That is to say, in (some?) situations where a command would not
make use of the region when it is inactive, that command will still make use of
it. This variable has meaning (effect) only for t-m-m.

Yes, it is not clearly expressed (though the code must clearly define) which
commands make use of the inactive region to do what. IOW, what does it mean to
"use" the inactive region, "as if it were active"?

I agree that this is not clearly expressed in the doc, but changing the meaning
of "active" to mean anything other than t-m-m active would not be helpful, IMO.

> > AFAIK, we have never, in the doc, referred to activeness 
> > other than in the context of transient-mark-mode,

[I correct myself above. But that doc is poor, IMO. The doc _should_ never refer
to region activeness other than for t-m-m.]

> > that is, when t-m-m is on. Activeness of the region or mark is a
> > notion that is applicable only to t-m-m. If t-m-m mode is off,
> > then the region is neither active nor inactive. It just is
> > (or isn't, if there is no mark). Once we make this
> > clear (to each other and to doc readers), the "problem" disappears.
> 
> I would support this solution wholeheartedly.
> 
> > 5. Both Davis's active1 and active2 reflect this (#4).
> 
> > With t-m-m on, the region is active1 iff the "region is active" in
> > traditional parlance. With t-m-m off, the region is active1 always
> > (provided the mark exists). That last statement says that active1 is
> > only a t-m-m notion.
> 
> Yes.
> 
> > Likewise, for Davis's active2. With t-m-m on, the region is 
> > active2 iff the "region is active" in traditional parlance.
> > With t-m-m off, the region is never active2. Again, that last
> > statement says that active2 is only a t-m-m notion.
> 
> Yes.
> 
> > 7. The proper predicate for testing whether the region is 
> > (in)active is (null mark-active). That's all. But again, such
> > a test makes sense only when t-m-m mode is on. If you are
> > testing only `mark-active' outside of
> > t-m-m, then you are wasting your time.
> 
> This is active1.  This is always t (unless
> `mark-even-if-inactive' is set to nil).

Not sure what you're saying. `mark-even-if-inactive' does not change whether the
mark is active.

BTW, there are only 17 occurrences of `mark-even-if-inactive' in the entire Lisp
source code, and 7 of them are for Viper. 1 is for Customize, just to give it
its standard value. 1 is in a doc string. 12 are defvars or set it or bind it or
save it. 

There are only 2 places in all of the Emac Lisp code where we _test_ the value
of `mark-even-if-inactive'. So we should be able to explain this better, in
terms of its intention and effect. Those occurrences are:

1. In `mouse-save-then-kill' - if it is non-nil, this essentially lets us ignore
t-m-m when selecting text.

2. In function `mark' - if it is non-nil, then we return the mark value even if
it is not active. IOW, it lets us ignore t-m-m when getting the mark value.

That's it. Admittedly, the second is a basic function, so there's no telling
which commands might check the `mark' value and decide to have a different
behavior depending, ultimately, on the value of `mark-even-if-inactive'.

But the behavior difference is just that with nil value t-m-m raises an error if
the mark is not active (unless the command catches that with `condition-case'
and does something different).

> > 8. Whether or not you can do certain things with the region, and
> > knowing whether a given command will operate on the region (or the
> > whole buffer or whatever), is orthogonal to whether you are in t-m-m
> > and, if so, whether the region is active.  That is, whether 
> > the command even looks at the region and the t-m-m state 
> > (`mark-active') is up to the command.
> 
> I'm not sure what you're saying here.  I agree with your 
> second sentence, but I'm not sure how it connects with the first,
> which doesn't seem right.

I should have phrased it better. I meant only that you cannot know anything
without consulting the doc for the particular command. Knowing you're in t-m-m
does not help here in any general way. A given command can do what it wants. No
behavioral generalization fits, wrt t-m-m. The followup sentences explain it
better:

> > It is the particular command that decides what happens in any given
> > context: whether it acts on the region; whether it does so 
> > regardless of t-m-m; whether, if in t-m-m, the action is different
> > whether the region is active or not; and so on.
> 
> > 9. The confusion for Alan and perhaps some other users and 
> > doc readers is that they have gotten the impression that the region 
> > being "active" has some meaning outside t-m-m. They (mis)read doc
> > that talks about some command's acting or not acting on the region
> > depending on whether the region is active. They interpret the use
> > of "active" here to apply also when t-m-m is off, as if it speaks
> > to whether or not the region is _usable_ by the command or whether
> > the command is region-aware.
> 
> Thanks!  That's a very helpful way of characterising the 
> problem.  There are a lot of places in the manual which say "when
> the region is active", without mentioning disabled t-m-m.

I'm beginning to realize that now. We need to decide on the terms to use. I've
made my proposal in that regard (reserve "active region/mark" for t-m-m). Once
we agree, the doc needs to be cleaned up. The Emacs 22 manual node Transient
Mark is a prime example of confusing people by talking about how the region is
always active when t-m-m is off and how the region always exists but does not
exist most of the time when t-m-m is on. And so on.

Let's save "active region" and "active mark" as notions relevant only to t-m-m.
Then, let's clean up the doc accordingly.

Then, let's figure out how best to handle (a) mouse highlighting (~activating)
of the region, and (b) `mark-even-if-inactive' - that is, how to talk about
them.

> > This confusion comes perhaps from imperfect wording - dunno. The doc
> > should state clearly (remind readers) that any behavior that is
> > conditional on whether the region is active is conditional only when
> > t-m-m is on, because the region can be active only when t-m-m is on.
> 
> Agreed wholeheartedly.  This clarification should occur at 
> every point in the doc which mentions "active"ness.
> 
> > 10. A further consideration is whether the region is empty, that is,
> > point=mark.  This distinction makes sense independently of t-m-m.
> > "Active region" applies only to t-m-m, but "empty region" applies
> > whether t-m-m is on or off. (It does not apply always, however. A
> > region cannot be empty or non-empty if it does not yet exist.)
> 
> Is this so important?  Some commands take the same action for empty
> region as inactive region.  This seems an orthogonal issue.

That's the point. Nonempty is something different from "active". But much of the
time it makes sense for a command to treat an empty region the same as an
inactive region (in t-m-m). That's the point. That means that the doc for such
commands should specifically mention "if the region is active and nonempty"...

In my functions, for instance, I typically say something like "If the region is
not active or is empty, then bob and eob are used." Or "This is used only if
Transient Mark mode is off or the region is inactive or empty."

> > 11. Similarly, for the existence of the mark (hence the region)
> > in a given buffer. This distinction makes sense independently
> > of t-m-m. This distinction is always available - it is the only
> > condition of the three that can always be tested. You cannot test
> > (numerically) whether point=mark unless the mark exists.  You
> > cannot test whether the mark is active unless t-m-m is on. 
> 
> If you talk about "the region", what you say clearly only 
> applies after the mark has been set.

There is no region before there is a mark.

> > 12. "Well, hold it", you say. You can test `mark-active'
> > anytime. Yes, but without also testing t-m-m the value of
> > variable `mark-active' won't tell you whether the mark/region
> > is active. This is a possible source of confusion for those
> > readers who use Emacs Lisp. The doc of `mark-active' just
> > needs to make it clear that it is a variable that
> > applies only to t-m-m.
> 
> `mark-active' is active1, and can't now be changed.  Its doc string
> should make clear that its notion of "active" is different 
> from the more useful active2.

I don't understand (or else I don't agree). `mark-active' is a variable used
(only) by t-m-m. Nothing more. It concerns the notion of "active" that I've been
arguing for: "active" means something (wrt the region/mark) only in t-m-m.
`mark-active' is _the_ test for whether the region/mark is active. It's simply
that whether or not it is active has no meaning outside of t-m-m. That's my
standpoint, at least.

> > 13. The behavior of some commands can be conditional on: (1) t-m-m
> > region activeness (so with t-m-m mode off there is no
> > distinction/condition); (2) region emptiness; (3) region 
> > existence; or some combination of 1-3.
> 
> > The existence test can always be used to change command 
> > behavior. The emptiness test can be used anytime the mark
> > exists. Testing for an active region can be done only when
> > t-m-m mode is on.
> 
> > 14. The doc for a given command needs to make clear the 
> > various behavior changes and the conditions that determine
> > them. The introduction of such conditional commands,
> > especially those that check for an active region, 
> > has, I think, led to confusion for some people. We need to
> > be very clear in their doc about these notions and tests.
> 
> That means revising lots of doc strings, doesn't it?  ;-)

Dunno. It's more important to start with the manual, cleaning it up so it
reserves "active" region/mark for t-m-m and makes these notions clear. Once this
is clear, doc for individual commands can be cleared up progressively.

I think part of the problem is the lack of clarity in the minds of those who
wrote the doc strings - basing themselves on the existing doc mud. Once everyone
is on the same page wrt the notions, and uses the (cleaned up) doc for those
basic notions as a base, doc for commands will get cleaned up case by case.

> > In particular, to help readers understand such doc strings 
> > (after we've made the strings clear), we need to _remind_
> > readers here and there of these things: (1) The mark might
> > not exist in some buffer; it does not exist until you set mark.
> > (2) The region might be empty, which means point=mark. (3) 
> > If t-m-m mode is off, then whether the region is active cannot
> > be tested: active region is a t-m-m concept.

BTW - This is probably not the place to bring this up ;-), but why do buffers
start out with no mark set? From a user conceptual standpoint, it would be
easier to say that every buffer always has a mark and region. By default, the
mark position for each buffer could be (point-min). IOW, mark could be treated
just like point in this regard.

It's just a question. Is there (still) a good reason not to have an initial
mark? Is it so that the mark is always set only by the user? Is it to reduce the
size of the global mark ring (or ensure that all of its entries are meaningful)?
Just wondering. 

> > 15. If it helps, we can state somewhere that the full name 
> > of the notion "active region" is "transient-mark-mode active
> > region". The former is really an abbreviation for the latter.
> > Speaking only of "active region" is like speaking
> > only of "the length" instead of "the line length".
> 
> A masterpiece of clear thinking!  Thanks.
> 
> > As long as we were speaking only in the context of t-m-m, 
> > there was no problem. But as soon as we speak of "active
> > region" in a context (e.g. some command behavior) where
> > t-m-m does not necessarily apply, we need to make it very
> > clear that this is a t-m-m notion only.
> 
> > 16. I don't have a concrete suggestion for changing any 
> > terminology. A priori, I think we should keep the current
> > terminology, which fits with `mark-active' etc.
> 
> The "active" we usually mean is active2.

That's where we disagree. At least I don't usually (or ever) mean active2. As
Davis said, "with tmm, the mark is active2 iff it is active1." For me, "active"
has meaning only in t-m-m, and in that case, there is never any distinction
between active1 and active2.

I don't think it's helpful to speak of active1 and active2. Call them foo1 and
foo2, if you like. And it doesn't help to characterize them in terms of the
kinds of commands each supports, which was the initial description Davis gave.
_Defined_ as Davis defined them, however:

def foo1: (or (not transient-mark-mode) (mark-active))
def foo2: (and transient-mark-mode (mark-active))

they can help us reason. But I think they've already served their purpose, which
for me was to help show that (1) they are both only t-m-m notions, having
meaning only when t-m-m is on (see above, where you agreed "Yes" twice) and (2)
in the context of t-m-m being on, they mean the same thing (look at the
definitions): they both mean `mark-active' when t-m-m is on.

> The "active" in `mark-active' is active1.

It is active2 also. When t-m-m is on. And you've agreed that "active/inactive"
has meaning only when t-m-m is on.

> Something needs to give, somewhere.

I don't follow. (?)
 
> > 17. But we should clarify the doc wherever that might be 
> > needed. The doc string for `mark-active', for instance, is
> > one place to start: "Non-nil means the mark
> > and region are currently active in this buffer." We need to 
> > add something like this: "The value is used only when
> > transient-mark-mode is on. Active and inactive mark and
> > region apply only to transient-mark-mode."
> 
> > HTH. In sum, the solution is to recognize and make 
> > clear(er) that "active" applies only to t-m-m. It is misguided
> > to try to describe or define "active" outside t-m-m. Trust me,
> > that attempt would ultimately make things far _more_
> > confusing. (Sorry, Alan.)
> 
> Thanks for such a helpful post, Drew.

Dunno if we'll all reach consensus on the terminology, but we can probably all
agree that the current doc is not all that clear. ;-)

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

[Stephen J. Turnbull]

Eli Zaretskii writes:
 > > From: "Stephen J. Turnbull" <stephen@xemacs.org>
 > > Eli Zaretskii writes:
 > > 
 > >  > > > email.  Sorry for the poor wording - it's late and I'm tired.
 > >  > > 
 > >  > > I would find this fairly confusing
 > >  > 
 > >  > So would I.  If you read this text carefully, it actually says
 > >  > something like "the region is active when Emacs marks it as active."
 > >  > That's hardly a definition of what "active" is.
 > > 
 > > Read a little more carefully.  It also explains how the behavior of
 > > Emacs changes when the mark is active.  That *is* a definition of 
 > > "active".
 > 
 > Right, but that "definition-through-behavior" was exactly what Alan
 > opposed to in the first place!

No.  Alan objected to d-t-b where "behavior" refers to "how to make
Emacs 'activate' the mark" (behavior changes activity).  What he wants
is "how does Emacs's behavior change when the mark is 'active'?"
(activity changes behavior).  These are quite different.

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

[Stephen J. Turnbull]

Alan Mackenzie writes:

 > Does XEmacs have a definition of an "active region"?  ;-)

Yes, although it's a little hard to find because of the heritage of
XEmacs in the Lisp machine world.  C-h v zmacs-regions RET sez:

------------------------------------------------------------------------
`zmacs-regions' is a built-in boolean variable.
  -- loaded from "/playpen/src/XEmacs/xemacs/src/editfns.c"

Value: t

Documentation:
*Whether LISPM-style active regions should be used.
This means that commands which operate on the region (the area between the
point and the mark) will only work while the region is in the ``active''
state, which is indicated by highlighting.  Executing most commands causes
the region to not be in the active state, so (for example) C-w will only
work immediately after activating the region.

More specifically:

 - Commands which operate on the region only work if the region is active.
 - Only a very small set of commands cause the region to become active:
   Those commands whose semantics are to mark an area, like `mark-defun'.
 - The region is deactivated after each command that is executed, except that:
 - "Motion" commands do not change whether the region is active or not.

set-mark-command (C-SPC) pushes a mark and activates the region.  Moving the
cursor with normal motion commands (C-n, C-p, etc) will cause the region
between point and the recently-pushed mark to be highlighted.  It will
remain highlighted until some non-motion command is executed.

exchange-point-and-mark (C-x C-x) activates the region.  So if you mark a
region and execute a command that operates on it, you can reactivate the
same region with C-x C-x (or perhaps C-x C-x C-x C-x) to operate on it
again.

Generally, commands which push marks as a means of navigation (like
beginning-of-buffer and end-of-buffer (M-< and M->)) do not activate the
region.  But commands which push marks as a means of marking an area of
text (like mark-defun (M-C-h), mark-word (M-@) or mark-whole-buffer (C-x h))
do activate the region.

The way the command loop actually works with regard to deactivating the
region is as follows:

- If the variable `zmacs-region-stays' has been set to t during the command
  just executed, the region is left alone (this is how the motion commands
  make the region stay around; see the `_' flag in the `interactive'
  specification).  `zmacs-region-stays' is reset to nil before each command
  is executed.
- If the function `zmacs-activate-region' has been called during the command
  just executed, the region is left alone.  Very few functions should
  actually call this function.
- Otherwise, if the region is active, the region is deactivated and
  the `zmacs-deactivate-region-hook' is called.
------------------------------------------------------------------------

 > Here, it has manifestly lead to massive confusion.

I suspect that is mostly just the unfortunate Emacs terminology,
variable names, and documentation for the concept (sorry guys, but
"unfortunate" is the nicest thing I can say about the stuff quoted in
this thread), not because the word "active" itself is confusing.

 > "But EVERYBODY know what \"active\" means!" just won't do.

I don't think XEmacs's definition has that problem.

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

[Lennart Borgman]

On Mon, Jun 1, 2009 at 4:34 AM, Stephen J. Turnbull <stephen@xemacs.org> wrote:
> Alan Mackenzie writes:
>
>  > Does XEmacs have a definition of an "active region"?  ;-)
>
> Yes, although it's a little hard to find because of the heritage of
> XEmacs in the Lisp machine world.  C-h v zmacs-regions RET sez:
>
> ------------------------------------------------------------------------
> `zmacs-regions' is a built-in boolean variable.
>  -- loaded from "/playpen/src/XEmacs/xemacs/src/editfns.c"
>
> Value: t
>
> Documentation:
> *Whether LISPM-style active regions should be used.
> This means that commands which operate on the region (the area between the
> point and the mark) will only work while the region is in the ``active''
> state, which is indicated by highlighting.  Executing most commands causes
> the region to not be in the active state, so (for example) C-w will only
> work immediately after activating the region.
>
> More specifically:
>
>  - Commands which operate on the region only work if the region is active.
>  - Only a very small set of commands cause the region to become active:
>   Those commands whose semantics are to mark an area, like `mark-defun'.
>  - The region is deactivated after each command that is executed, except that:
>  - "Motion" commands do not change whether the region is active or not.
>
> set-mark-command (C-SPC) pushes a mark and activates the region.  Moving the
> cursor with normal motion commands (C-n, C-p, etc) will cause the region
> between point and the recently-pushed mark to be highlighted.  It will
> remain highlighted until some non-motion command is executed.

This sounds good to me and is easy to read.


> exchange-point-and-mark (C-x C-x) activates the region.  So if you mark a
> region and execute a command that operates on it, you can reactivate the
> same region with C-x C-x (or perhaps C-x C-x C-x C-x) to operate on it
> again.

That seems useful. (But the cua hint is a bit obscure.)


> Generally, commands which push marks as a means of navigation (like
> beginning-of-buffer and end-of-buffer (M-< and M->)) do not activate the
> region.  But commands which push marks as a means of marking an area of
> text (like mark-defun (M-C-h), mark-word (M-@) or mark-whole-buffer (C-x h))
> do activate the region.

This is also clear.


> The way the command loop actually works with regard to deactivating the
> region is as follows:
>
> - If the variable `zmacs-region-stays' has been set to t during the command
>  just executed, the region is left alone (this is how the motion commands
>  make the region stay around; see the `_' flag in the `interactive'
>  specification).  `zmacs-region-stays' is reset to nil before each command
>  is executed.
> - If the function `zmacs-activate-region' has been called during the command
>  just executed, the region is left alone.  Very few functions should
>  actually call this function.
> - Otherwise, if the region is active, the region is deactivated and
>  the `zmacs-deactivate-region-hook' is called.
> ------------------------------------------------------------------------
>
>  > Here, it has manifestly lead to massive confusion.
>
> I suspect that is mostly just the unfortunate Emacs terminology,
> variable names, and documentation for the concept (sorry guys, but
> "unfortunate" is the nicest thing I can say about the stuff quoted in
> this thread), not because the word "active" itself is confusing.

I think something like the text above could make "(emacs) Mark" more
easy to read.


>  > "But EVERYBODY know what \"active\" means!" just won't do.
>
> I don't think XEmacs's definition has that problem.
>
>
>

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

[Andreas Roehler]

Stephen J. Turnbull wrote:
> Alan Mackenzie writes:
> 
>  > Does XEmacs have a definition of an "active region"?  ;-)
> 
> Yes, although it's a little hard to find because of the heritage of
> XEmacs in the Lisp machine world.  C-h v zmacs-regions RET sez:
> 
> ------------------------------------------------------------------------
> `zmacs-regions' is a built-in boolean variable.
>   -- loaded from "/playpen/src/XEmacs/xemacs/src/editfns.c"
> 
> Value: t
> 
> Documentation:
> *Whether LISPM-style active regions should be used.
> This means that commands which operate on the region (the area between the
> point and the mark) will only work while the region is in the ``active''
> state, which is indicated by highlighting.  Executing most commands causes
> the region to not be in the active state, so (for example) C-w will only
> work immediately after activating the region.
> 
> More specifically:
> 
>  - Commands which operate on the region only work if the region is active.
>  - Only a very small set of commands cause the region to become active:
>    Those commands whose semantics are to mark an area, like `mark-defun'.
>  - The region is deactivated after each command that is executed, except that:
>  - "Motion" commands do not change whether the region is active or not.
> 
> set-mark-command (C-SPC) pushes a mark and activates the region.  Moving the
> cursor with normal motion commands (C-n, C-p, etc) will cause the region
> between point and the recently-pushed mark to be highlighted.  It will
> remain highlighted until some non-motion command is executed.
> 
> exchange-point-and-mark (C-x C-x) activates the region.  So if you mark a
> region and execute a command that operates on it, you can reactivate the
> same region with C-x C-x (or perhaps C-x C-x C-x C-x) to operate on it
> again.
> 
> Generally, commands which push marks as a means of navigation (like
> beginning-of-buffer and end-of-buffer (M-< and M->)) do not activate the
> region.  But commands which push marks as a means of marking an area of
> text (like mark-defun (M-C-h), mark-word (M-@) or mark-whole-buffer (C-x h))
> do activate the region.
> 
> The way the command loop actually works with regard to deactivating the
> region is as follows:
> 
> - If the variable `zmacs-region-stays' has been set to t during the command
>   just executed, the region is left alone (this is how the motion commands
>   make the region stay around; see the `_' flag in the `interactive'
>   specification).  `zmacs-region-stays' is reset to nil before each command
>   is executed.
> - If the function `zmacs-activate-region' has been called during the command
>   just executed, the region is left alone.  Very few functions should
>   actually call this function.
> - Otherwise, if the region is active, the region is deactivated and
>   the `zmacs-deactivate-region-hook' is called.
> ------------------------------------------------------------------------
> 
>  > Here, it has manifestly lead to massive confusion.
> 
> I suspect that is mostly just the unfortunate Emacs terminology,
> variable names, and documentation for the concept (sorry guys, but
> "unfortunate" is the nicest thing I can say about the stuff quoted in
> this thread), not because the word "active" itself is confusing.
> 
>  > "But EVERYBODY know what \"active\" means!" just won't do.
> 
> I don't think XEmacs's definition has that problem.
> 
> 
> 

IMHO XEmacs has another problem, see the docstrings of
related functions


` ...
(region-active-p)

...
Return non-nil if the region is active in the current buffer.
If `zmacs-regions' is true, this is equivalent to `region-exists-p'.
Otherwise, this function always returns false.

`  ...
(region-exists-p)
...
Return t if the region exists.
If active regions are in use (i.e. `zmacs-regions' is true), this means that
 the region is active.  Otherwise, this means that the user has pushed
 a mark in this buffer at some point in the past.


AFAIU definitions (including zmacs-regions) are here intermixed. At
least one may be dropped.

For me GNU variable `mark-active' is more straightforward by its value,
but should be named `mark-set' rather.

Info about an existing extend I understand by
`region-exists-p' in the word-sense (not the current definition).
Writing `region-extends-p' might be still better.

Third command may (but must not) require a visibility of region.

Would leave that to the programmers to decide, delivering
`region-visible-p' for the purpose.


My wishlist so far for all Emacsen:

`mark-set'
`region-extends-p'
`region-visible-p'

Andreas

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

[Stephen J. Turnbull]

Andreas Roehler writes:

 > AFAIU definitions (including zmacs-regions) are here intermixed. At
 > least one may be dropped.

I don't think so.  zmacs-regions is a variable that controls a
feature.  Some people dislike that feature, so it is a user option.
The other two are functions that retrieve internal state.  None of the
three can be defined in terms of the others without changing the
semantics radically.

 > For me GNU variable `mark-active' is more straightforward by its value,
 > but should be named `mark-set' rather.

What do you need it to do that plain `mark' doesn't already do?

Note that since all of these APIs are of long standing in XEmacs at
least, I'm pretty sure they're not going to change in XEmacs, despite
the sheer perversity of the current semantics of `region-exists-p',
`region-active-p', and `mark'.  But it would be reasonable to add new
ones if there are things that can't be easily done with the current
ones, or if it would make code clearer.