bug#36365: Add info how to deselect secondary selection (Emacs manual)

bug#36365: Add info how to deselect secondary selection (Emacs manual)

[Sebastian Urban]

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.

bug#36365: Add info how to deselect secondary selection (Emacs manual)

[Eli Zaretskii]

> From: Sebastian Urban <mrsebastianurban@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.

bug#36365: Add info how to deselect secondary selection (Emacs manual)

[Sebastian Urban]

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?

bug#36365: Add info how to deselect secondary selection (Emacs manual)

[Eli Zaretskii]

> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Cc: 36365@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.

bug#36365: Add info how to deselect secondary selection (Emacs manual)

[Eli Zaretskii]

> Date: Sat, 06 Jul 2019 21:21:21 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: 36365@debbugs.gnu.org
> 
> > From: Sebastian Urban <mrsebastianurban@gmail.com>
> > Cc: 36365@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.

bug#36365: Add info how to deselect secondary selection (Emacs manual)

[Eli Zaretskii]

> Date: Sat, 06 Jul 2019 21:21:21 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: 36365@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.

bug#36365: Add info how to deselect secondary selection (Emacs manual)

[Drew Adams]

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

bug#36365: Add info how to deselect secondary selection (Emacs manual)

[Sebastian Urban]

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

bug#36365: Add info how to deselect secondary selection (Emacs manual)

[Sebastian Urban]

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

bug#36365: Add info how to deselect secondary selection (Emacs manual)

[Eli Zaretskii]

> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Cc: 36365@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.

bug#36365: Add info how to deselect secondary selection (Emacs manual)

[Sebastian Urban]

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

bug#36365: Add info how to deselect secondary selection (Emacs manual)

[Eli Zaretskii]

> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Cc: 36365@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.

bug#36365: Add info how to deselect secondary selection (Emacs manual)

[Sebastian Urban]

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

bug#36365: Add info how to deselect secondary selection (Emacs manual)

[Eli Zaretskii]

> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Cc: 36365@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.

bug#36365: Add info how to deselect secondary selection (Emacs manual)

[Sebastian Urban]

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