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