[Emacs-diffs] master 6057d79 * doc/lispref/keymaps.texi (Extended Menu Items): Tweak :key-sequence

[Emacs-diffs] master 6057d79 * doc/lispref/keymaps.texi (Extended Menu Items): Tweak :key-sequence

[Eli Zaretskii]

The new text says:

   @item :key-sequence @var{key-sequence}
   This property specifies which key sequence is likely to be bound to the
  -same command invoked by this menu item.  If you specify the right key
  -sequence, that makes preparing the menu for display run much faster.
  +same command invoked by this menu item.  If you specify a correct key
  +sequence, that sequence will be preferred over others.
                           ^^^^^^^^^^^^^^^^^
In what sense will that sequence be "preferred" in this case?

Also, I see that easymenu.el still claims that there's a speed
advantage to using :key-sequence.

Thanks.

Re: [Emacs-diffs] master 6057d79 * doc/lispref/keymaps.texi (Extended Menu Items): Tweak :key-sequence

[Eli Zaretskii]

Ping!

> Date: Sat, 11 Apr 2020 09:45:59 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: emacs-devel@gnu.org
> 
> The new text says:
> 
>    @item :key-sequence @var{key-sequence}
>    This property specifies which key sequence is likely to be bound to the
>   -same command invoked by this menu item.  If you specify the right key
>   -sequence, that makes preparing the menu for display run much faster.
>   +same command invoked by this menu item.  If you specify a correct key
>   +sequence, that sequence will be preferred over others.
>                            ^^^^^^^^^^^^^^^^^
> In what sense will that sequence be "preferred" in this case?
> 
> Also, I see that easymenu.el still claims that there's a speed
> advantage to using :key-sequence.
> 
> Thanks.
> 
> 

Re: [Emacs-diffs] master 6057d79 * doc/lispref/keymaps.texi (Extended Menu Items): Tweak :key-sequence

[Stefan Monnier]

>>    @item :key-sequence @var{key-sequence}
>>    This property specifies which key sequence is likely to be bound to the
>>   -same command invoked by this menu item.  If you specify the right key
>>   -sequence, that makes preparing the menu for display run much faster.
>>   +same command invoked by this menu item.  If you specify a correct key
>>   +sequence, that sequence will be preferred over others.
>>                            ^^^^^^^^^^^^^^^^^
>> In what sense will that sequence be "preferred" in this case?
>> Also, I see that easymenu.el still claims that there's a speed
>> advantage to using :key-sequence.

Indeed.

How 'bout the patch below?  I'm still not really satisfied (and I think
removing the duplication would also be good).


        Stefan


diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 4db9969767..1e81fb1dc5 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -2223,14 +2223,11 @@ Extended Menu Items
 set the variable so that the button you clicked on becomes selected.
 
 @item :key-sequence @var{key-sequence}
-This property specifies which key sequence is likely to be bound to the
-same command invoked by this menu item.  If you specify a correct key
-sequence, that sequence will be preferred over others.
-
-If you specify an incorrect key sequence, it has no effect; before Emacs
-displays @var{key-sequence} in the menu, it verifies that
-@var{key-sequence} is really equivalent to this menu item.  Specifying
-@code{nil} for @var{key-sequence} is equivalent to the
+This property specifies which key sequence to display as keyboard equivalent.
+Before Emacs displays @var{key-sequence} in the menu, it verifies that
+@var{key-sequence} is really equivalent to this menu item, so it only
+has an effect if you specify a correct key sequence.
+Specifying @code{nil} for @var{key-sequence} is equivalent to the
 @code{:key-sequence} attribute being absent.
 
 @item :keys @var{string}
@@ -2913,17 +2910,17 @@ Easy Menu
 
 @table @code
 @item :keys @var{keys}
-@var{keys} is a keyboard equivalent to the menu item (a string).  This
-is normally not needed, as keyboard equivalents are computed
+@var{keys} is a string to display as keyboard equivalent to the menu item.
+This is normally not needed, as keyboard equivalents are computed
 automatically.  @var{keys} is expanded with
 @code{substitute-command-keys} before it is displayed (@pxref{Keys in
 Documentation}).
 
 @item :key-sequence @var{keys}
-@var{keys} is a hint for speeding up Emacs's first display of the
-menu.  It should be @code{nil} if you know that the menu item has no keyboard
-equivalent; otherwise it should be a string or vector specifying a
-keyboard equivalent for the menu item.
+@var{keys} is a hint indicating which key sequence to display as
+keyboard equivalent, in case the command is bound to several key sequences.
+It has no effect if @var{keys} is not bound to same command as this
+menu item.
 
 @item :active @var{enable}
 @var{enable} is an expression; if it evaluates to @code{nil}, the item

Re: [Emacs-diffs] master 6057d79 * doc/lispref/keymaps.texi (Extended Menu Items): Tweak :key-sequence

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org
> Date: Sun, 19 Apr 2020 10:42:46 -0400
> 
> >>    @item :key-sequence @var{key-sequence}
> >>    This property specifies which key sequence is likely to be bound to the
> >>   -same command invoked by this menu item.  If you specify the right key
> >>   -sequence, that makes preparing the menu for display run much faster.
> >>   +same command invoked by this menu item.  If you specify a correct key
> >>   +sequence, that sequence will be preferred over others.
> >>                            ^^^^^^^^^^^^^^^^^
> >> In what sense will that sequence be "preferred" in this case?
> >> Also, I see that easymenu.el still claims that there's a speed
> >> advantage to using :key-sequence.
> 
> Indeed.
> 
> How 'bout the patch below?  I'm still not really satisfied (and I think
> removing the duplication would also be good).

The new text is clear, thanks.  I think this should go to the release
branch.

I'm also okay with removing the duplication (e.g., how about having a
cross-reference in one of the places pointing to the other one?)

Thanks.

Re: [Emacs-diffs] master 6057d79 * doc/lispref/keymaps.texi (Extended Menu Items): Tweak :key-sequence

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

That patch is good, but how about replacing this

  > +Specifying @code{nil} for @var{key-sequence} is equivalent to the
  >  @code{:key-sequence} attribute being absent.

with this?

  If @var{key-sequence} is @code{nil}, this property has no effect.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)