bug#14206: 24.3.50; doc string of `execute-kbd-macro'

bug#14206: 24.3.50; doc string of `execute-kbd-macro'

[Drew Adams]

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@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'
 

bug#14206: 24.3.50; doc string of `execute-kbd-macro'

[Lars Ingebrigtsen]

"Drew Adams" <drew.adams@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/

bug#14206: 24.3.50; doc string of `execute-kbd-macro'

[Andreas Schwab]

Lars Ingebrigtsen <larsi@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@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

bug#14206: 24.3.50; doc string of `execute-kbd-macro'

[Kevin Rodgers]

On 2/8/14 4:59 AM, Lars Ingebrigtsen wrote:
> "Drew Adams"<drew.adams@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

bug#14206: 24.3.50; doc string of `execute-kbd-macro'

[Lars Ingebrigtsen]

Kevin Rodgers <kevin.d.rodgers@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/

bug#14206: 24.3.50; doc string of `execute-kbd-macro'

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Kevin Rodgers <kevin.d.rodgers@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

bug#14206: 24.3.50; doc string of `execute-kbd-macro'

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Fri, 29 Apr 2016 01:29:17 +0200
> Cc: 14206@debbugs.gnu.org
> 
> Lars Ingebrigtsen <larsi@gnus.org> writes:
> 
> > Kevin Rodgers <kevin.d.rodgers@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.

bug#14206: 24.3.50; doc string of `execute-kbd-macro'

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@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

bug#14206: 24.3.50; doc string of `execute-kbd-macro'

[Andreas Schwab]

Lars Ingebrigtsen <larsi@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@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

bug#14206: 24.3.50; doc string of `execute-kbd-macro'

[Lars Ingebrigtsen]

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

> Lars Ingebrigtsen <larsi@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

bug#14206: 24.3.50; doc string of `execute-kbd-macro'

[Andreas Schwab]

Lars Ingebrigtsen <larsi@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@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

bug#14206: 24.3.50; doc string of `execute-kbd-macro'

[Andreas Schwab]

Lars Ingebrigtsen <larsi@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@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

bug#14206: 24.3.50; doc string of `execute-kbd-macro'

[Lars Ingebrigtsen]

Andreas Schwab <schwab@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

bug#14206: 24.3.50; doc string of `execute-kbd-macro'

[Johan Bockgård]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Andreas Schwab <schwab@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).

bug#14206: 24.3.50; doc string of `execute-kbd-macro'

[Lars Ingebrigtsen]

"Drew Adams" <drew.adams@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