bug#32956: 26.1.50; t-m-m mark deactivation documentation

[Drew Adams <drew.adams@oracle.com>]

>  Transient Mark mode is a global minor mode.  When enabled, the
>  region is highlighted with the `region' face whenever the mark
> -is active.  The mark is \"deactivated\" by changing the buffer,
> -and after certain other operations that set the mark but whose
> -main purpose is something else--for example, incremental search,
> -\\[beginning-of-buffer], and \\[end-of-buffer].
> +is active.  The mark is \"deactivated\" after certain non-motion
> +commands, including those that change the text in the buffer, and
> +during shift or mouse selection by any unshifted cursor motion
> +command (see Info node `Shift Selection' for more details).
> 
>  You can also deactivate the mark by typing \\[keyboard-quit] or
>  \\[keyboard-escape-quit].

The Elisp manual, node `The Mark' has similar text, so if
an update to the doc string is called for then maybe the
manual text needs a similar update.
____

BTW, this (the manual) might be a good place to mention
to Elisp users that (in `transient-mark-mode', at least) the
mark is also deactivated by default after each command,
by the command loop. Some commands inhibit this
automatic deactivation.

This is a fairly common question by Elisp users who try to
write a command that they think/hope will end with the
region staying activated (e.g. for use by a follow-up command).

This is maybe a good place to tell them about the automatic
deactivation (by default), and maybe even let them know
that they can use (setq deactivate-mark  nil) at the end of a
command definition to inhibit automatic deactivation.

In fact, this bit of `The Mark' doesn't seem quite right:

  A command can ... request deactivation of the mark upon
  return to the editor command loop by setting the variable
  'deactivate-mark' to a non-'nil' value.

I think that's a bit backward, at least in `transient-mark-mode'.
IIUC, the command loop automatically deactivates the mark
after each command, unless `deactivate-mark' is non-nil.
A command (in t-m-m, at least) need not set that variable to
non-nil to deactivate the mark, as it is normally treated as such.

The opposite is true: If you want the region to stay active
after your command is done (so that it is active for the
next command) then your command can set `deactivate-mark'
to nil to prevent automatic deactivation.