bug#37146: 26.2; (elisp) Interactive Codes, for `K'

bug#37146: 26.2; (elisp) Interactive Codes, for `K'

[Drew Adams]

This is what it says:

'K'
     A key sequence, whose definition you intend to change.  This works
     like 'k', except that it suppresses, for the last input event in
     the key sequence, the conversions that are normally used (when
     necessary) to convert an undefined key into a defined one.

That's inadequate.  In this node you have no idea what "the conversions
that are normally used (when necessary) to convert an undefined key into
a defined one" are, or even what that phrase means.

Either such conversions need to be described here or, if they are
described in some other node then please add a cross-reference to that
node.  Otherwise, there is no way for us to understand what `K' is/does.

I couldn't even find a description of such conversion by starting with
the parent node and searching for "conve".  But I don't claim to have
studied the full context of each search hit.

In GNU Emacs 26.2 (build 1, x86_64-w64-mingw32)
 of 2019-04-13
Repository revision: fd1b34bfba8f3f6298df47c8e10b61530426f749
Windowing system distributor `Microsoft Corp.', version 10.0.17763
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#37146: 26.2; (elisp) Interactive Codes, for `K'

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

  >      A key sequence, whose definition you intend to change.  This works
  >      like 'k', except that it suppresses, for the last input event in
  >      the key sequence, the conversions that are normally used (when
  >      necessary) to convert an undefined key into a defined one.

  > That's inadequate.  In this node you have no idea what "the conversions
  > that are normally used (when necessary) to convert an undefined key into
  > a defined one" are, or even what that phrase means.

To explain that here would be too much duolication.  A reference
to the Lisp manual would perhaps be worth it.
-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#37146: 26.2; (elisp) Interactive Codes, for `K'

[Drew Adams]

> > That's inadequate.  In this node you have no idea what "the
> > conversions that are normally used (when necessary) to
> > convert an undefined key into a defined one" are, or even
> > what that phrase means.
> 
> To explain that here would be too much duolication.
> A reference to the Lisp manual would perhaps be worth it.

Yes, that's would be great.  But this _is_ the Lisp
manual.  And I'm not sure the doc to link to exists.
I hope it does, or it will be added.

I guess perhaps the conversions mentioned are those 
described in (elisp) `Key Sequence Input' for function
`read-key-sequence'.  But I'm not sure that's what's
meant.

It's also not clear to me what is meant by "whose
definition you intend to change".  How so?  That seems
to be a description of the ` use case (or main use
case?) of `K' (as opposed to `k'), but it's not clear
to me what that's about.

bug#37146: 26.2; (elisp) Interactive Codes, for `K'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> This is what it says:
>
> 'K'
>      A key sequence, whose definition you intend to change.  This works
>      like 'k', except that it suppresses, for the last input event in
>      the key sequence, the conversions that are normally used (when
>      necessary) to convert an undefined key into a defined one.
>
> That's inadequate.  In this node you have no idea what "the conversions
> that are normally used (when necessary) to convert an undefined key into
> a defined one" are, or even what that phrase means.

Yes, it's pretty obscure.  I've now changed this to the following in
Emacs 28:

@item K
A key sequence on a form that can be used as input to functions like
@code{define-key}.  This works like @samp{k}, except that it
suppresses, for the last input event in the key sequence, the
conversions that are normally used (when necessary) to convert an
undefined key into a defined one (@pxref{Key Sequence Input}), so this
form is usually used when prompting for a new key sequence that is to
be bound to a command.


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

bug#37146: 26.2; (elisp) Interactive Codes, for `K'

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Tue, 15 Jun 2021 18:35:03 +0200
> Cc: 37146@debbugs.gnu.org
> 
> A key sequence on a form that can be used as input to functions like
                 ^^^^^^^^^
That sounds wrong to me.  What does it mean "on a form"?  Did you mean
"of a form"?

bug#37146: 26.2; (elisp) Interactive Codes, for `K'

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> A key sequence on a form that can be used as input to functions like
>                  ^^^^^^^^^
> That sounds wrong to me.  What does it mean "on a form"?  Did you mean
> "of a form"?

Uhm...  possibly?  Perhaps it should be reformulated completely.

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