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

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

> > 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.
> 
> Hmm, deactivate-mark is nil by default -- what effect would setting it
> to "nil" again have?  Is it to counteract the effect of previous
> function calls within the command, which may have set
> "deactivate-mark" to "t"?

This is about defining a command that activates the region
and wants to leave/keep it activated after the command
is finished.

Consider, as one example, a repeatable command that
does something  with the active region (e.g. indents it).
Because it is repeatable it wants to keep the region 
activated, for the next action. It needs to do this at
the end: (setq deactivate-mark  nil).

Users sometimes try to define commands that try to
leave the region active, not realizing that the command
loop will deactivate the region when the command is
done - unless the command sets `deactivate-mark' to nil.

> > 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.
> 
> Again, though, deactivate-mark is "nil" by default, so it seems that
> some editing function has to set it to "t" for the mark to really be
> deactivated.

I don't understand what you mean by "really be deactivated".
But see above.