bug#50727: Contradictory conventions with new command kbd-macro-display

bug#50727: Contradictory conventions with new command kbd-macro-display

[Stefan Kangas]

Severity: minor

`kbd-macro-display' is a new command in Emacs 28 bound to `C-x C-k Q'.
(See commit d4e9d191aeba.)

However, the `kmacro-bind-to-key' docstring says:

    The key sequences [C-x C-k 0] through [C-x C-k 9] and [C-x C-k A]
    through [C-x C-k Z] are reserved for user bindings, and to bind to
    one of these sequences, just enter the digit or letter, rather than
    the whole sequence.

This advice seems to conflict with the chosen key binding for
`kbd-macro-display'.

bug#50727: Contradictory conventions with new command kbd-macro-display

[Gregory Heytings]

>
> `kbd-macro-display' is a new command in Emacs 28 bound to `C-x C-k Q'. 
> (See commit d4e9d191aeba.)
>
> However, the `kmacro-bind-to-key' docstring says:
>
>    The key sequences [C-x C-k 0] through [C-x C-k 9] and [C-x C-k A]
>    through [C-x C-k Z] are reserved for user bindings, and to bind to
>    one of these sequences, just enter the digit or letter, rather than
>    the whole sequence.
>
> This advice seems to conflict with the chosen key binding for 
> `kbd-macro-display'.
>

It's 'kbd-macro-redisplay', not 'kbd-macro-display'.  Indeed it conflicts 
with the keys that are supposed to be reserved for user bindings, but it 
is by far not the only one:

C-x C-k Q	kdb-macro-redisplay
C-x C-k b	kmacro-bind-to-key
C-x C-k e	edit-kbd-macro
C-x C-k l	kmacro-edit-lossage
C-x C-k n	kmacro-name-last-macro
C-x C-k q	kbd-macro-query
C-x C-k r	apply-macro-to-region-lines
C-x C-k s	kmacro-start-macro
C-x C-k x	kmacro-to-register

bug#50727: Contradictory conventions with new command kbd-macro-display

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 21 Sep 2021 16:22:26 -0700
> Cc: larsi@gnus.org, marcowahlsoft@gmail.com
> 
>     The key sequences [C-x C-k 0] through [C-x C-k 9] and [C-x C-k A]
>     through [C-x C-k Z] are reserved for user bindings, and to bind to
>     one of these sequences, just enter the digit or letter, rather than
>     the whole sequence.

Regardless of the main issue here, why does this doc string use this
strange notation for key sequences?  What is the meaning of the
brackets here, and why don't we use `..' as usual?

bug#50727: Contradictory conventions with new command kbd-macro-display

[Stefan Kangas]

Gregory Heytings <gregory@heytings.org> writes:

> It's 'kbd-macro-redisplay', not 'kbd-macro-display'.

Sorry, yes: `kbd-macro-redisplay'.

> Indeed it conflicts with the keys that are supposed to be reserved for
> user bindings, but it is by far not the only one:
>
> C-x C-k Q	kdb-macro-redisplay
> C-x C-k b	kmacro-bind-to-key
> C-x C-k e	edit-kbd-macro
> C-x C-k l	kmacro-edit-lossage
> C-x C-k n	kmacro-name-last-macro
> C-x C-k q	kbd-macro-query
> C-x C-k r	apply-macro-to-region-lines
> C-x C-k s	kmacro-start-macro
> C-x C-k x	kmacro-to-register

I believe only the first one of these breaks the convention, as it is
the only one to use an upper-case letter.

bug#50727: Contradictory conventions with new command kbd-macro-display

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>>     The key sequences [C-x C-k 0] through [C-x C-k 9] and [C-x C-k A]
>>     through [C-x C-k Z] are reserved for user bindings, and to bind to
>>     one of these sequences, just enter the digit or letter, rather than
>>     the whole sequence.
>
> Regardless of the main issue here, why does this doc string use this
> strange notation for key sequences?  What is the meaning of the
> brackets here, and why don't we use `..' as usual?

AFAICT, there is no particular reason for using that notation here.
I'll push a fix for that shortly, lumped in with some other checkdoc
fixes.

bug#50727: Contradictory conventions with new command kbd-macro-display

[Marco Wahl]

Stefan Kangas <stefan@marxist.se> writes:

> Gregory Heytings <gregory@heytings.org> writes:
>
>> It's 'kbd-macro-redisplay', not 'kbd-macro-display'.
>
> Sorry, yes: `kbd-macro-redisplay'.
>
>> Indeed it conflicts with the keys that are supposed to be reserved for
>> user bindings, but it is by far not the only one:
>>
>> C-x C-k Q	kdb-macro-redisplay
>> C-x C-k b	kmacro-bind-to-key
>> C-x C-k e	edit-kbd-macro
>> C-x C-k l	kmacro-edit-lossage
>> C-x C-k n	kmacro-name-last-macro
>> C-x C-k q	kbd-macro-query
>> C-x C-k r	apply-macro-to-region-lines
>> C-x C-k s	kmacro-start-macro
>> C-x C-k x	kmacro-to-register
>
> I believe only the first one of these breaks the convention, as it is
> the only one to use an upper-case letter.

Thanks for pointing out the issue!

Now what to do?

What about dropping key sequence C-x C-k Q and use C-x C-k d instead?
Or even dropping that key sequence entirey?

I vote for keeping a key sequence for kdb-macro-redisplay, tho.

bug#50727: Contradictory conventions with new command kbd-macro-display

[Gregory Heytings]

>> Indeed it conflicts with the keys that are supposed to be reserved for 
>> user bindings, but it is by far not the only one:
>>
>> C-x C-k Q	kdb-macro-redisplay
>> C-x C-k b	kmacro-bind-to-key
>> C-x C-k e	edit-kbd-macro
>> C-x C-k l	kmacro-edit-lossage
>> C-x C-k n	kmacro-name-last-macro
>> C-x C-k q	kbd-macro-query
>> C-x C-k r	apply-macro-to-region-lines
>> C-x C-k s	kmacro-start-macro
>> C-x C-k x	kmacro-to-register
>
> I believe only the first one of these breaks the convention, as it is 
> the only one to use an upper-case letter.
>

Indeed, I thought that the convention was similar to the C-c LETTER one, 
in which both lower and upper case letters are reserved for users, but you 
are correct, it's only upper case letters that are reserved for users in 
this case.  Which IMO isn't a good thing, typing C-x C-k S-LETTER is 
awkward.

bug#50727: Contradictory conventions with new command kbd-macro-display

[Marco Wahl]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stefan Kangas <stefan@marxist.se>
>> Date: Tue, 21 Sep 2021 16:22:26 -0700
>> Cc: larsi@gnus.org, marcowahlsoft@gmail.com
>>
>>     The key sequences [C-x C-k 0] through [C-x C-k 9] and [C-x C-k A]
>>     through [C-x C-k Z] are reserved for user bindings, and to bind to
>>     one of these sequences, just enter the digit or letter, rather than
>>     the whole sequence.
>
> Regardless of the main issue here, why does this doc string use this
> strange notation for key sequences?  What is the meaning of the
> brackets here, and why don't we use `..' as usual?

Of course I don't know but I guess the reason for that notation has been
just a lack of knowledge about the usual notation style.

bug#50727: Contradictory conventions with new command kbd-macro-display

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 21 Sep 2021 23:53:06 -0700
> Cc: 50727@debbugs.gnu.org, larsi@gnus.org, marcowahlsoft@gmail.com
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >>     The key sequences [C-x C-k 0] through [C-x C-k 9] and [C-x C-k A]
> >>     through [C-x C-k Z] are reserved for user bindings, and to bind to
> >>     one of these sequences, just enter the digit or letter, rather than
> >>     the whole sequence.
> >
> > Regardless of the main issue here, why does this doc string use this
> > strange notation for key sequences?  What is the meaning of the
> > brackets here, and why don't we use `..' as usual?
> 
> AFAICT, there is no particular reason for using that notation here.
> I'll push a fix for that shortly, lumped in with some other checkdoc
> fixes.

Thanks.

bug#50727: Contradictory conventions with new command kbd-macro-display

[Lars Ingebrigtsen]

Marco Wahl <marcowahlsoft@gmail.com> writes:

> What about dropping key sequence C-x C-k Q and use C-x C-k d instead?

I moved it to `C-x C-k d' on the trunk now.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no