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

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