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

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

[Charles A. Roelli]

t-m-m's documentation currently states:

	      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,
  M-<, and M->.

All of the examples (incremental search, M-<, and M->) do not always
deactivate the mark.  For example, for incremental search, try from
emacs -Q:

M-< C-SPC C-s buffer RET	> the mark is not deactivated

For M-< and M->, try:

M-< M-@ M-</M->			> neither M-< nor M-> deactivate the mark

There does seem to be at least one case where M-< and M-> do
deactivate the mark.  Try:

double-clicking the word "buffer" in *scratch*
M-</M->

Both M-< and M-> deactivate the mark in this case.  IIUC, this
behavior is explained in (info "(emacs) Shift Selection"):

     A mark set via mouse commands behaves the same as a mark set via
  shift-selection (*note Setting Mark::).  For example, if you specify a
  region by dragging the mouse, you can continue to extend the region
  using shifted cursor motion commands.  In either case, any unshifted
  cursor motion command deactivates the mark.

In light of this, here's a change for review on emacs-26:

diff --git a/lisp/simple.el b/lisp/simple.el
index d5674aa..8bbafe4 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -5793,10 +5793,10 @@ transient-mark-mode
 
 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].

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

[Drew Adams]

>  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.

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

[Eli Zaretskii]

> Date: Sat, 06 Oct 2018 16:19:55 +0200
> From: charles@aurox.ch (Charles A. Roelli)
> 
> In light of this, here's a change for review on emacs-26:
> 
> diff --git a/lisp/simple.el b/lisp/simple.el
> index d5674aa..8bbafe4 100644
> --- a/lisp/simple.el
> +++ b/lisp/simple.el
> @@ -5793,10 +5793,10 @@ transient-mark-mode
>  
>  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].

Fine with me (but do please make similar changes in the ELisp manual).

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

[Charles A. Roelli]

tags 32956 fixed
close 32956 26.2
quit

> Date: Sat, 06 Oct 2018 19:39:57 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> 
> Fine with me (but do please make similar changes in the ELisp manual).

Ok, I've pushed the fix.  The manual does not have the same error, so
I've left it as is.

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

[Charles A. Roelli]

> Date: Sat, 6 Oct 2018 14:48:01 +0000 (UTC)
> From: Drew Adams <drew.adams@oracle.com>
> Content-Type: text/plain; charset=us-ascii
> 
> 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.

The manual looks correct to me.  I think in this case the manual has
been updated without an equivalent change to the docstring of t-m-m.

> 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"?

> 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.

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

[Drew Adams]

> > 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.

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

[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.

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

[Charles A. Roelli]

> Date: Sun, 07 Oct 2018 16:39:07 +0200
> From: charles@aurox.ch (Charles A. Roelli)
>
> But the Emacs manual does lack an index entry for "deactivating the
> mark", which seems like an area for improvement.

FWIW, this change for emacs-26 should fix it, as well as adding an
entry for activating the mark.

diff --git a/doc/emacs/mark.texi b/doc/emacs/mark.texi
index 0ffa9f7..1050587 100644
--- a/doc/emacs/mark.texi
+++ b/doc/emacs/mark.texi
@@ -17,11 +17,13 @@ Mark
 changes.
 
 @cindex active region
+@cindex activating the mark
   Setting the mark at a position in the text also @dfn{activates} it.
 When the mark is active, we say also that the region is active; Emacs
 indicates its extent by highlighting the text within it, using the
 @code{region} face (@pxref{Face Customization}).
 
+@cindex deactivating the mark
   After certain non-motion commands, including any command that
 changes the text in the buffer, Emacs automatically @dfn{deactivates}
 the mark; this turns off the highlighting.  You can also explicitly

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

[Eli Zaretskii]

> Date: Sun, 07 Oct 2018 21:42:07 +0200
> From: charles@aurox.ch (Charles A. Roelli)
> Cc: 32956@debbugs.gnu.org
> 
> FWIW, this change for emacs-26 should fix it, as well as adding an
> entry for activating the mark.
> 
> diff --git a/doc/emacs/mark.texi b/doc/emacs/mark.texi
> index 0ffa9f7..1050587 100644
> --- a/doc/emacs/mark.texi
> +++ b/doc/emacs/mark.texi
> @@ -17,11 +17,13 @@ Mark
>  changes.
>  
>  @cindex active region
> +@cindex activating the mark
>    Setting the mark at a position in the text also @dfn{activates} it.
>  When the mark is active, we say also that the region is active; Emacs
>  indicates its extent by highlighting the text within it, using the
>  @code{region} face (@pxref{Face Customization}).
>  
> +@cindex deactivating the mark
>    After certain non-motion commands, including any command that
>  changes the text in the buffer, Emacs automatically @dfn{deactivates}
>  the mark; this turns off the highlighting.  You can also explicitly

Fine with me, thanks.

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

[Charles A. Roelli]

> Date: Mon, 08 Oct 2018 05:28:33 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> 
> > diff --git a/doc/emacs/mark.texi b/doc/emacs/mark.texi
> > index 0ffa9f7..1050587 100644
> > --- a/doc/emacs/mark.texi
> > +++ b/doc/emacs/mark.texi
> > @@ -17,11 +17,13 @@ Mark
> >  changes.
> >  
> >  @cindex active region
> > +@cindex activating the mark
> >    Setting the mark at a position in the text also @dfn{activates} it.
> >  When the mark is active, we say also that the region is active; Emacs
> >  indicates its extent by highlighting the text within it, using the
> >  @code{region} face (@pxref{Face Customization}).
> >  
> > +@cindex deactivating the mark
> >    After certain non-motion commands, including any command that
> >  changes the text in the buffer, Emacs automatically @dfn{deactivates}
> >  the mark; this turns off the highlighting.  You can also explicitly
> 
> Fine with me, thanks.

Thanks, I've pushed it.