GNU bug report logs - #14206
24.3.50; doc string of `execute-kbd-macro'

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 14206 in the body.
You can then email your comments to 14206 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: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.3.50; doc string of `execute-kbd-macro'
Date: Sun, 14 Apr 2013 17:33:45 -0700

The doc string is misleading, especially this part: "as string of editor
command characters".  Presumably what is meant is as a sequence of
command chars (better - a sequence of events).  Compare the Elisp manual
description, which explicitly mentions that MACRO can be a string or a
vector (or a symbol with a function value).
 
 
 
In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2013-04-09 on ODIEONE
Bzr revision: 112253 rgm <at> gnu.org-20130409101736-f1vzgrwt88suqqis
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib'
 

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 14206 <at> debbugs.gnu.org
Subject: Re: bug#14206: 24.3.50; doc string of `execute-kbd-macro'
Date: Sat, 08 Feb 2014 03:59:31 -0800

"Drew Adams" <drew.adams <at> oracle.com> writes:

> The doc string is misleading, especially this part: "as string of editor
> command characters".  Presumably what is meant is as a sequence of
> command chars (better - a sequence of events).  Compare the Elisp manual
> description, which explicitly mentions that MACRO can be a string or a
> vector (or a symbol with a function value).

Uhm...

(defun foo () "foo")

(execute-kbd-macro 'foo)

->

Debugger entered--Lisp error: (error "Keyboard macros must be strings or vectors")
  execute-kbd-macro(foo)
  eval((execute-kbd-macro (quote foo)) nil)

(execute-kbd-macro "foo")
-> foo

(execute-kbd-macro ["f"])
->
After 0 kbd macro iterations: undefined: Keyboard macro terminated by a command ringing the bell

What kind of vector is this talking about?

It's kinda confusing all over.

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

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

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 14206 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#14206: 24.3.50; doc string of `execute-kbd-macro'
Date: Sat, 08 Feb 2014 13:11:23 +0100

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> What kind of vector is this talking about?

The same thing you use for a key in a key binding.

Andreas.

-- 
Andreas Schwab, schwab <at> linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

From: Kevin Rodgers <kevin.d.rodgers <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#14206: 24.3.50; doc string of `execute-kbd-macro'
Date: Sat, 08 Feb 2014 08:45:44 -0700

On 2/8/14 4:59 AM, Lars Ingebrigtsen wrote:
> "Drew Adams"<drew.adams <at> oracle.com>  writes:
>
>> The doc string is misleading, especially this part: "as string of editor
>> command characters".  Presumably what is meant is as a sequence of
>> command chars (better - a sequence of events).  Compare the Elisp manual
>> description, which explicitly mentions that MACRO can be a string or a
>> vector (or a symbol with a function value).
>
> Uhm...
>
> (defun foo () "foo")
>
> (execute-kbd-macro 'foo)
>
> ->
>
> Debugger entered--Lisp error: (error "Keyboard macros must be strings or vectors")
>    execute-kbd-macro(foo)
>    eval((execute-kbd-macro (quote foo)) nil)
>
> (execute-kbd-macro "foo")
> ->  foo
>
> (execute-kbd-macro ["f"])
> ->
> After 0 kbd macro iterations: undefined: Keyboard macro terminated by a command ringing the bell
>
> What kind of vector is this talking about?

A vector of keyboard events: (execute-kbd-macro [?f ?o ?o])

> It's kinda confusing all over.

-- 
Kevin Rodgers
Denver, Colorado, USA

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Kevin Rodgers <kevin.d.rodgers <at> gmail.com>
Cc: 14206 <at> debbugs.gnu.org
Subject: Re: bug#14206: 24.3.50; doc string of `execute-kbd-macro'
Date: Sat, 08 Feb 2014 17:50:01 -0800

Kevin Rodgers <kevin.d.rodgers <at> gmail.com> writes:

>> (defun foo () "foo")
>>
>> (execute-kbd-macro 'foo)
>>
>> ->
>>
>> Debugger entered--Lisp error: (error "Keyboard macros must be
>> strings or vectors")
>>    execute-kbd-macro(foo)
>>    eval((execute-kbd-macro (quote foo)) nil)

So is the "If MACRO is a symbol, its function definition is used." thing
wrong?

>> (execute-kbd-macro ["f"])
>> ->
>> After 0 kbd macro iterations: undefined: Keyboard macro terminated
>> by a command ringing the bell
>>
>> What kind of vector is this talking about?
>
> A vector of keyboard events: (execute-kbd-macro [?f ?o ?o])

Right.  I've now added this to the doc string.

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

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Kevin Rodgers <kevin.d.rodgers <at> gmail.com>
Cc: 14206 <at> debbugs.gnu.org
Subject: Re: bug#14206: 24.3.50; doc string of `execute-kbd-macro'
Date: Fri, 29 Apr 2016 01:29:17 +0200

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Kevin Rodgers <kevin.d.rodgers <at> gmail.com> writes:
>
>>> (defun foo () "foo")
>>>
>>> (execute-kbd-macro 'foo)
>>>
>>> ->
>>>
>>> Debugger entered--Lisp error: (error "Keyboard macros must be
>>> strings or vectors")
>>>    execute-kbd-macro(foo)
>>>    eval((execute-kbd-macro (quote foo)) nil)
>
> So is the "If MACRO is a symbol, its function definition is used." thing
> wrong?

This is what Fexecute_kbd_macro does:

  final = indirect_function (macro);
  if (!STRINGP (final) && !VECTORP (final))
    error ("Keyboard macros must be strings or vectors");

In what contexts can a function end up being a string?  Uhm...  If
somebody has said

(fset 'foo "bar")

?

Is this a useful thing?  Should it be documented?  I can't see any
callers in the Emacs code base calling `execute-kbd-macro' with a symbol
after grepping a bit...

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

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: kevin.d.rodgers <at> gmail.com, 14206 <at> debbugs.gnu.org
Subject: Re: bug#14206: 24.3.50; doc string of `execute-kbd-macro'
Date: Fri, 29 Apr 2016 09:56:11 +0300

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Date: Fri, 29 Apr 2016 01:29:17 +0200
> Cc: 14206 <at> debbugs.gnu.org
> 
> Lars Ingebrigtsen <larsi <at> gnus.org> writes:
> 
> > Kevin Rodgers <kevin.d.rodgers <at> gmail.com> writes:
> >
> >>> (defun foo () "foo")
> >>>
> >>> (execute-kbd-macro 'foo)
> >>>
> >>> ->
> >>>
> >>> Debugger entered--Lisp error: (error "Keyboard macros must be
> >>> strings or vectors")
> >>>    execute-kbd-macro(foo)
> >>>    eval((execute-kbd-macro (quote foo)) nil)
> >
> > So is the "If MACRO is a symbol, its function definition is used." thing
> > wrong?
> 
> This is what Fexecute_kbd_macro does:
> 
>   final = indirect_function (macro);
>   if (!STRINGP (final) && !VECTORP (final))
>     error ("Keyboard macros must be strings or vectors");
> 
> In what contexts can a function end up being a string?  Uhm...  If
> somebody has said
> 
> (fset 'foo "bar")
> 
> ?

No, I think (fset 'foo "\M-:").

IOW, an indirect function could produce a macro, right?

In general, keyboard macros produce strings like that, which I'm sure
you know, so I'm not sure if I understand your question.

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

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Kevin Rodgers <kevin.d.rodgers <at> gmail.com>, 14206 <at> debbugs.gnu.org
Subject: Re: bug#14206: 24.3.50; doc string of `execute-kbd-macro'
Date: Fri, 29 Apr 2016 11:24:26 +0200

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Is this a useful thing?

It's a keyboard macro.

> Should it be documented?

See (emacs) Save Keyboard Macro, (elisp) Keyboard Macros.

Andreas.

-- 
Andreas Schwab, schwab <at> linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: kevin.d.rodgers <at> gmail.com, 14206 <at> debbugs.gnu.org
Subject: Re: bug#14206: 24.3.50; doc string of `execute-kbd-macro'
Date: Fri, 29 Apr 2016 15:00:07 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

> No, I think (fset 'foo "\M-:").
>
> IOW, an indirect function could produce a macro, right?
>
> In general, keyboard macros produce strings like that, which I'm sure
> you know, so I'm not sure if I understand your question.

I did not know that putting non-function stuff into the function slot of
a symbol was a thing that we do.  Actually, I don't think it is.  :-)

So I agree that this documentation is still kinda incomprehensible, even
though what it says is literally true:

MACRO can also be a vector of keyboard events.  If MACRO is a symbol,
its function definition is used.

Perhaps something like

If MACRO is a symbol, and its function definition is a string or a
vector of keyboard events, its function definition is used.

?  Or put it at the end, saying that it's deprecated...

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

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Andreas Schwab <schwab <at> linux-m68k.org>
Cc: Kevin Rodgers <kevin.d.rodgers <at> gmail.com>, 14206 <at> debbugs.gnu.org
Subject: Re: bug#14206: 24.3.50; doc string of `execute-kbd-macro'
Date: Fri, 29 Apr 2016 15:02:58 +0200

Andreas Schwab <schwab <at> linux-m68k.org> writes:

> See (emacs) Save Keyboard Macro, (elisp) Keyboard Macros.

Aha!

(defun kmacro-name-last-macro (symbol)
  "Assign a name to the last keyboard macro defined.
Argument SYMBOL is the name to define.
The symbol's function definition becomes the keyboard macro string.
Such a \"function\" cannot be called from Lisp, but it is a valid editor command."

I see...

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

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

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Eli Zaretskii <eliz <at> gnu.org>, kevin.d.rodgers <at> gmail.com,
 14206 <at> debbugs.gnu.org
Subject: Re: bug#14206: 24.3.50; doc string of `execute-kbd-macro'
Date: Fri, 29 Apr 2016 17:55:08 +0200

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Perhaps something like
>
> If MACRO is a symbol, and its function definition is a string or a
> vector of keyboard events, its function definition is used.

But the function definition is used unconditionally.

Andreas.

-- 
Andreas Schwab, schwab <at> linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Andreas Schwab <schwab <at> linux-m68k.org>
Cc: Eli Zaretskii <eliz <at> gnu.org>, kevin.d.rodgers <at> gmail.com,
 14206 <at> debbugs.gnu.org
Subject: Re: bug#14206: 24.3.50; doc string of `execute-kbd-macro'
Date: Fri, 29 Apr 2016 18:10:44 +0200

Andreas Schwab <schwab <at> linux-m68k.org> writes:

> Lars Ingebrigtsen <larsi <at> gnus.org> writes:
>
>> Perhaps something like
>>
>> If MACRO is a symbol, and its function definition is a string or a
>> vector of keyboard events, its function definition is used.
>
> But the function definition is used unconditionally.

True.  So perhaps just a usage note?  "This is useful for keyboard
macros stored as function definitions" or something?  Because as it is
now, the natural interpretation is that it's generally useful for
functions.  And it isn't.

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

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

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: kevin.d.rodgers <at> gmail.com, 14206 <at> debbugs.gnu.org
Subject: Re: bug#14206: 24.3.50; doc string of `execute-kbd-macro'
Date: Fri, 29 Apr 2016 21:23:17 +0200

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> True.  So perhaps just a usage note?  "This is useful for keyboard
> macros stored as function definitions" or something?  Because as it is
> now, the natural interpretation is that it's generally useful for
> functions.  And it isn't.

The whole point of the function is to execute a kbd macro, which can
also be stored in the function slot of a symbol.  That's all what the
doc string says.

Andreas.

-- 
Andreas Schwab, schwab <at> linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

From: Johan Bockgård <bojohan <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Kevin Rodgers <kevin.d.rodgers <at> gmail.com>,
 Andreas Schwab <schwab <at> linux-m68k.org>, 14206 <at> debbugs.gnu.org
Subject: Re: bug#14206: 24.3.50; doc string of `execute-kbd-macro'
Date: Sat, 30 Apr 2016 17:56:42 +0200

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Andreas Schwab <schwab <at> linux-m68k.org> writes:
>
>> See (emacs) Save Keyboard Macro, (elisp) Keyboard Macros.
>
> Aha!
>
> (defun kmacro-name-last-macro (symbol)
>   "Assign a name to the last keyboard macro defined.
> Argument SYMBOL is the name to define.
> The symbol's function definition becomes the keyboard macro string.
> Such a \"function\" cannot be called from Lisp, but it is a valid editor command."
>
> I see...

And `name-last-kbd-macro' (which should probably be an obsolete alias
for kmacro-name-last-macro).

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 14206 <at> debbugs.gnu.org
Subject: Re: bug#14206: 24.3.50; doc string of `execute-kbd-macro'
Date: Mon, 14 Mar 2022 12:17:02 +0100

"Drew Adams" <drew.adams <at> oracle.com> writes:

> The doc string is misleading, especially this part: "as string of editor
> command characters".  Presumably what is meant is as a sequence of
> command chars (better - a sequence of events).  Compare the Elisp manual
> description, which explicitly mentions that MACRO can be a string or a
> vector (or a symbol with a function value).

I've now updated the doc string (mainly by copying text from the manual,
which explained things a whole lot better) in Emacs 29.

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

Previous Next

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