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.