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

[charles@aurox.ch (Charles A. Roelli)]

> Date: Sun, 7 Oct 2018 01:02:28 +0000 (UTC)
> From: Drew Adams <drew.adams@oracle.com>
> 
> > 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).

I think changing or adding text in the buffer is what eventually tells
the command loop to deactivate the mark (via the variable
deactivate-mark).  The command loop should not do that by default
after each command.  For example, from emacs -Q:

M-: (defun foo () (interactive)) RET C-x h M-x foo RET > does NOT deactivate the mark
M-: (defun foo () (interactive) (insert "text")) RET C-x h M-x foo RET > DOES deactivate the mark

So, developers should only have to add (setq deactivate-mark nil) to
the end of their command if it is a command that changes or adds
buffer text without wanting to deactivate the mark.

This is explained in the Elisp manual (where it belongs, I think).
But the Emacs manual does lack an index entry for "deactivating the
mark", which seems like an area for improvement.