GNU bug report logs - #36365
Add info how to deselect secondary selection (Emacs manual)

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 36365 in the body.
You can then email your comments to 36365 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Sebastian Urban <mrsebastianurban <at> gmail.com>
To: Bug GNU Emacs <bug-gnu-emacs <at> gnu.org>
Subject: Add info how to deselect secondary selection (Emacs manual)
Date: Mon, 24 Jun 2019 19:59:42 +0200

Because, if it's "selection", people may think that to deselect all
you need is to click 'mouse-1' somewhere, but it doesn't work, as well
as 'C-g' and it may be confusing.

Therefore please add information about 'M-mouse-1' as a way to
deselect, perhaps somewhere next to the L626-627 or after the
definition of 'M-mouse-1' L607-608 in KILLING.TEXI.

Then update documentation string for 'mouse-start-secondary' with the
same information.

===

Also (because it's the same chapter) in Emacs manual (INFO) "12.3.3
Secondary Selection" description of 'M-mouse-3' could be changed:

FROM
Set the secondary selection, with one end at the position clicked
and the other at the position specified with ‘M-mouse-1’
(‘mouse-secondary-save-then-kill’).  This also puts the selected
text in the kill ring.  A second ‘M-mouse-3’ at the same place
kills the secondary selection just made.

TO
Set the secondary selection, with one end at the position clicked and
the other at the position specified with ‘M-mouse-1’, and put the
selected text in the kill ring (‘mouse-secondary-save-then-kill’).
A second ‘M-mouse-3’ at the same place kills the secondary selection
just made.

Placement of 'mouse-secondary-save-then-kill' will be better, right
now it may confuse people because it stands next to 'M-mouse-1' which
has different command.


S. U.

Message #10 received at 36365-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Sebastian Urban <mrsebastianurban <at> gmail.com>
Cc: 36365-done <at> debbugs.gnu.org
Subject: Re: bug#36365: Add info how to deselect secondary selection (Emacs
 manual)
Date: Sat, 06 Jul 2019 11:31:56 +0300

> From: Sebastian Urban <mrsebastianurban <at> gmail.com>
> Date: Mon, 24 Jun 2019 19:59:42 +0200
> 
> Because, if it's "selection", people may think that to deselect all
> you need is to click 'mouse-1' somewhere, but it doesn't work, as well
> as 'C-g' and it may be confusing.
> 
> Therefore please add information about 'M-mouse-1' as a way to
> deselect, perhaps somewhere next to the L626-627 or after the
> definition of 'M-mouse-1' L607-608 in KILLING.TEXI.
> 
> Then update documentation string for 'mouse-start-secondary' with the
> same information.
> 
> ===
> 
> Also (because it's the same chapter) in Emacs manual (INFO) "12.3.3
> Secondary Selection" description of 'M-mouse-3' could be changed:
> 
> FROM
> Set the secondary selection, with one end at the position clicked
> and the other at the position specified with ‘M-mouse-1’
> (‘mouse-secondary-save-then-kill’).  This also puts the selected
> text in the kill ring.  A second ‘M-mouse-3’ at the same place
> kills the secondary selection just made.
> 
> TO
> Set the secondary selection, with one end at the position clicked and
> the other at the position specified with ‘M-mouse-1’, and put the
> selected text in the kill ring (‘mouse-secondary-save-then-kill’).
> A second ‘M-mouse-3’ at the same place kills the secondary selection
> just made.
> 
> Placement of 'mouse-secondary-save-then-kill' will be better, right
> now it may confuse people because it stands next to 'M-mouse-1' which
> has different command.

Thanks, I fixed these two issues.

Message #13 received at 36365 <at> debbugs.gnu.org (full text, mbox):

From: Sebastian Urban <mrsebastianurban <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 36365 <at> debbugs.gnu.org
Subject: Re: bug#36365: Add info how to deselect secondary selection (Emacs
 manual)
Date: Sat, 6 Jul 2019 20:17:13 +0200

Ok, thanks, but what about documentation string for
'mouse-start-secondary' (i.e. 'M-x describe-function -> m-s-s')?

I also have problem with:
... if you click @kbd{M-mouse-1} on the mode line or on the header line.

I guessing that clicking 'M-mouse-1' anywhere in the text will cancel
selection, but also start new one, and doing so on mode line/header
line, will not start new selection, is it correct so far?  But then
when I do so I get:
<mode-line> <M-mouse-1> is undefined
OR
<header-line> <M-mouse-1> is undefined
and secondary selection is still there.  Am I doing something wrong?

Message #16 received at 36365 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Sebastian Urban <mrsebastianurban <at> gmail.com>
Cc: 36365 <at> debbugs.gnu.org
Subject: Re: bug#36365: Add info how to deselect secondary selection (Emacs
 manual)
Date: Sat, 06 Jul 2019 21:21:21 +0300

> From: Sebastian Urban <mrsebastianurban <at> gmail.com>
> Cc: 36365 <at> debbugs.gnu.org
> Date: Sat, 6 Jul 2019 20:17:13 +0200
> 
> Ok, thanks, but what about documentation string for
> 'mouse-start-secondary' (i.e. 'M-x describe-function -> m-s-s')?

What about it?  There was no mention of that in your original report.

> I also have problem with:
> ... if you click @kbd{M-mouse-1} on the mode line or on the header line.
> 
> I guessing that clicking 'M-mouse-1' anywhere in the text will cancel
> selection, but also start new one, and doing so on mode line/header
> line, will not start new selection, is it correct so far?  But then
> when I do so I get:
> <mode-line> <M-mouse-1> is undefined
> OR
> <header-line> <M-mouse-1> is undefined
> and secondary selection is still there.  Am I doing something wrong?

I have no idea, as on my system secondary selections simply don't
work.  I guess someone else will have to find the way of deselecting
without starting a new selection, if one exists.  And if it doesn't
exist, I will simply remove that text, so that docs match the reality.

Message #19 received at 36365 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: mrsebastianurban <at> gmail.com
Cc: 36365 <at> debbugs.gnu.org
Subject: Re: bug#36365: Add info how to deselect secondary selection (Emacs
 manual)
Date: Sat, 06 Jul 2019 21:24:23 +0300

> Date: Sat, 06 Jul 2019 21:21:21 +0300
> From: Eli Zaretskii <eliz <at> gnu.org>
> Cc: 36365 <at> debbugs.gnu.org
> 
> > From: Sebastian Urban <mrsebastianurban <at> gmail.com>
> > Cc: 36365 <at> debbugs.gnu.org
> > Date: Sat, 6 Jul 2019 20:17:13 +0200
> > 
> > Ok, thanks, but what about documentation string for
> > 'mouse-start-secondary' (i.e. 'M-x describe-function -> m-s-s')?
> 
> What about it?  There was no mention of that in your original report.

Oh, sorry, I see there was, but I missed it.

But I see nothing wrong with the doc string as it is.

Message #22 received at 36365 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: mrsebastianurban <at> gmail.com
Cc: 36365 <at> debbugs.gnu.org
Subject: Re: bug#36365: Add info how to deselect secondary selection (Emacs
 manual)
Date: Sat, 06 Jul 2019 21:35:20 +0300

> Date: Sat, 06 Jul 2019 21:21:21 +0300
> From: Eli Zaretskii <eliz <at> gnu.org>
> Cc: 36365 <at> debbugs.gnu.org
> 
> > I guessing that clicking 'M-mouse-1' anywhere in the text will cancel
> > selection, but also start new one, and doing so on mode line/header
> > line, will not start new selection, is it correct so far?  But then
> > when I do so I get:
> > <mode-line> <M-mouse-1> is undefined
> > OR
> > <header-line> <M-mouse-1> is undefined
> > and secondary selection is still there.  Am I doing something wrong?
> 
> I have no idea, as on my system secondary selections simply don't
> work.  I guess someone else will have to find the way of deselecting
> without starting a new selection, if one exists.  And if it doesn't
> exist, I will simply remove that text, so that docs match the reality.

I see now that there's no way of canceling a secondary selection
without starting a new one.  So I changed the text to reflect that.

Message #25 received at 36365 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, mrsebastianurban <at> gmail.com
Cc: 36365 <at> debbugs.gnu.org
Subject: RE: bug#36365: Add info how to deselect secondary selection (Emacs
 manual)
Date: Sat, 6 Jul 2019 14:12:05 -0700 (PDT)

> I see now that there's no way of canceling a secondary selection
> without starting a new one.  So I changed the text to reflect that.

Correct.  An empty secondary selection is the same as
no secondary selection (at least as far as Emacs is
concerned).  When you try to yank the empty secondary
selection Emacs raises the error "No secondary selection".

(That's as it should be, IMO.)

Message #28 received at 36365 <at> debbugs.gnu.org (full text, mbox):

From: Sebastian Urban <mrsebastianurban <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 36365 <at> debbugs.gnu.org
Subject: Re: bug#36365: Add info how to deselect secondary selection (Emacs
 manual)
Date: Sun, 7 Jul 2019 10:05:44 +0200

> But I see nothing wrong with the doc string as it is.

Right now the string is:
  Set one end of the secondary selection to the position clicked on.
  Use <M-mouse-3> to set the other end
  and complete the secondary selection.

As you can see - no information about deselect, so perhaps just
copy-paste last sentence from your patch - "This command cancels any
existing secondary selection, when it starts a new one."

> I see now that there's no way of cancelling a secondary selection
> without starting a new one.  So I changed the text to reflect that.

Alright, but I think:
   use @kbd{M-mouse-3} to set the other end and complete the selection.

that this sentence from the patch is unnecessary.  How to set
secondary selection is in description of 'M-mouse-3' which is just ONE
line below.  In doc string of 'mouse-start-secondary' it is OK,
because there is no description of 'M-mouse-3', but in the manual
there is.

Message #31 received at 36365 <at> debbugs.gnu.org (full text, mbox):

From: Sebastian Urban <mrsebastianurban <at> gmail.com>
To: Sebastian Urban <mrsebastianurban <at> gmail.com>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 36365 <at> debbugs.gnu.org
Subject: Re: bug#36365: Add info how to deselect secondary selection (Emacs
 manual)
Date: Thu, 1 Aug 2019 15:33:17 +0200

>> But I see nothing wrong with the doc string as it is.
>
> Right now the string is:
>    Set one end of the secondary selection to the position clicked
>    on.  Use <M-mouse-3> to set the other end and complete the
>    secondary selection.
>
> As you can see - no information about deselect, so perhaps just
> copy-paste last sentence from your patch - "This command
> cancels any existing secondary selection, when it starts a new
> one."

Any update on this...

>> I see now that there's no way of cancelling a secondary selection
>> without starting a new one.  So I changed the text to reflect that.
>
> Alright, but I think:
>    use @kbd{M-mouse-3} to set the other end and complete the
>    selection.
>
> that this sentence from the patch is unnecessary.  How to set
> secondary selection is in description of 'M-mouse-3' which is just
> ONE line below.  In doc string of 'mouse-start-secondary' it is OK,
> because there is no description of 'M-mouse-3', but in the manual
> there is.

and this?

Message #34 received at 36365 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Sebastian Urban <mrsebastianurban <at> gmail.com>
Cc: mrsebastianurban <at> gmail.com, 36365 <at> debbugs.gnu.org
Subject: Re: bug#36365: Add info how to deselect secondary selection (Emacs
 manual)
Date: Fri, 02 Aug 2019 12:00:16 +0300

> From: Sebastian Urban <mrsebastianurban <at> gmail.com>
> Cc: 36365 <at> debbugs.gnu.org
> Date: Thu, 1 Aug 2019 15:33:17 +0200
> 
> >> But I see nothing wrong with the doc string as it is.
> >
> > Right now the string is:
> >    Set one end of the secondary selection to the position clicked
> >    on.  Use <M-mouse-3> to set the other end and complete the
> >    secondary selection.
> >
> > As you can see - no information about deselect, so perhaps just
> > copy-paste last sentence from your patch - "This command
> > cancels any existing secondary selection, when it starts a new
> > one."
> 
> Any update on this...
> 
> >> I see now that there's no way of cancelling a secondary selection
> >> without starting a new one.  So I changed the text to reflect that.
> >
> > Alright, but I think:
> >    use @kbd{M-mouse-3} to set the other end and complete the
> >    selection.
> >
> > that this sentence from the patch is unnecessary.  How to set
> > secondary selection is in description of 'M-mouse-3' which is just
> > ONE line below.  In doc string of 'mouse-start-secondary' it is OK,
> > because there is no description of 'M-mouse-3', but in the manual
> > there is.
> 
> and this?

I don't think there's anything wrong with the documentation you cite,
and I thought I already explained why I thought so in this discussion.

Message #37 received at 36365 <at> debbugs.gnu.org (full text, mbox):

From: Sebastian Urban <mrsebastianurban <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 36365 <at> debbugs.gnu.org
Subject: Re: bug#36365: Add info how to deselect secondary selection (Emacs
 manual)
Date: Fri, 2 Aug 2019 12:52:23 +0200

> I don't think there's anything wrong with the documentation you
> cite, and I thought I already explained why I thought so in this
> discussion.

Well, now I'm confused.  I reread the thread and I found nothing but
"I see nothing wrong with the doc string as it is" as an explanation
for not changing the doc string of 'mouse-start-secondary'.  And I'm
still going to write that it's missing information about deselecting,
which could be useful.

As for description of 'M-mouse-1' in Emacs Manual, I will also write
that the "use @kbd{M-mouse-3} to set the other end and complete the
selection" part of the sentence below is unnecessary.

From KILLING.TEXI (L604-610):
 @findex mouse-start-secondary
 @kindex M-mouse-1
 @item M-mouse-1
 Set one endpoint for the @dfn{secondary selection}
 (@code{mouse-start-secondary}); use @kbd{M-mouse-3} to set the other
 end and complete the selection.  This command cancels any existing
 secondary selection, when it starts a new one.

But in this case, if you have a reason for this, that I cannot see,
I'll leave this one alone.

Message #40 received at 36365 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Sebastian Urban <mrsebastianurban <at> gmail.com>
Cc: 36365 <at> debbugs.gnu.org
Subject: Re: bug#36365: Add info how to deselect secondary selection (Emacs
 manual)
Date: Fri, 02 Aug 2019 15:05:09 +0300

> From: Sebastian Urban <mrsebastianurban <at> gmail.com>
> Cc: 36365 <at> debbugs.gnu.org
> Date: Fri, 2 Aug 2019 12:52:23 +0200
> 
> > I don't think there's anything wrong with the documentation you
> > cite, and I thought I already explained why I thought so in this
> > discussion.
> 
> Well, now I'm confused.  I reread the thread and I found nothing but
> "I see nothing wrong with the doc string as it is" as an explanation
> for not changing the doc string of 'mouse-start-secondary'.  And I'm
> still going to write that it's missing information about deselecting,
> which could be useful.

We've established that it isn't possible to deselect without making a
new selection.  So I don't think deselection is something we can
describe, as it doesn't really exist.

> As for description of 'M-mouse-1' in Emacs Manual, I will also write
> that the "use @kbd{M-mouse-3} to set the other end and complete the
> selection" part of the sentence below is unnecessary.
> 
>  From KILLING.TEXI (L604-610):
>   @findex mouse-start-secondary
>   @kindex M-mouse-1
>   @item M-mouse-1
>   Set one endpoint for the @dfn{secondary selection}
>   (@code{mouse-start-secondary}); use @kbd{M-mouse-3} to set the other
>   end and complete the selection.  This command cancels any existing
>   secondary selection, when it starts a new one.
> 
> But in this case, if you have a reason for this, that I cannot see,
> I'll leave this one alone.

Yes, the manual should generally present a coherent text, so the
addition looked like an improvement to me.

Message #43 received at 36365 <at> debbugs.gnu.org (full text, mbox):

From: Sebastian Urban <mrsebastianurban <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 36365 <at> debbugs.gnu.org
Subject: Re: bug#36365: Add info how to deselect secondary selection (Emacs
 manual)
Date: Fri, 2 Aug 2019 15:29:43 +0200

> We've established that it isn't possible to deselect without making
> a new selection.

True.

> So I don't think deselection is something we can describe, as it
> doesn't really exist.

That's why additional sentence won't be:
   "This command cancels any existing secondary selection."
Instead it should be:
   "This command cancels any existing secondary selection, when it
   starts a new one."

This sentence is from your patch and is applied to 'M-mouse-1'
description in the manual, which runs 'mouse-start-secondary'.

>> As for description of 'M-mouse-1' in Emacs Manual, (...)
>
> Yes, the manual should generally present a coherent text, so the
> addition looked like an improvement to me.

OK, although I still disagree that this is an improvement, as I said
in previous message, I'm leaving this one alone.

Message #46 received at 36365 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Sebastian Urban <mrsebastianurban <at> gmail.com>
Cc: 36365 <at> debbugs.gnu.org
Subject: Re: bug#36365: Add info how to deselect secondary selection (Emacs
 manual)
Date: Fri, 02 Aug 2019 17:29:55 +0300

> From: Sebastian Urban <mrsebastianurban <at> gmail.com>
> Cc: 36365 <at> debbugs.gnu.org
> Date: Fri, 2 Aug 2019 15:29:43 +0200
> 
> > We've established that it isn't possible to deselect without making
> > a new selection.
> 
> True.
> 
> > So I don't think deselection is something we can describe, as it
> > doesn't really exist.
> 
> That's why additional sentence won't be:
>     "This command cancels any existing secondary selection."
> Instead it should be:
>     "This command cancels any existing secondary selection, when it
>     starts a new one."
> 
> This sentence is from your patch and is applied to 'M-mouse-1'
> description in the manual, which runs 'mouse-start-secondary'.

It's okay for the manual to go an extra mile, but the fact that
starting a new selection cancels the old one is a trivium, so it isn't
necessary in the doc string.

Message #49 received at 36365 <at> debbugs.gnu.org (full text, mbox):

From: Sebastian Urban <mrsebastianurban <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 36365 <at> debbugs.gnu.org
Subject: Re: bug#36365: Add info how to deselect secondary selection (Emacs
 manual)
Date: Fri, 2 Aug 2019 17:57:45 +0200

> It's okay for the manual to go an extra mile, but the fact that
> starting a new selection cancels the old one is a trivium, so it
> isn't necessary in the doc string.

OK, if you say so, then from my point of view this discussion is
finished.

Thanks again for updating manual.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.