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 <address@hidden> 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).