Re: Doc of keyboard macros

[Stefan Monnier <monnier@iro.umontreal.ca>]

>>   . You are breaking the manual's style when describing commands: we
>>     always start with a list of the commands with short descriptions,
>>     and follow that by the detailed descriptions.

Not sure exactly in which way I broke with that convention.
Does it mean that I should move the "details" (like the C-u/C-uC-u and
the F4-vs-C-xe discussion) to after the table?

[ Yes, I admit ashamedly that I'm still not really familiar with
  Emacs's manual's style.  ]

>>   . I don't understand the rationale for removing the "C-u" and
>>     "C-u C-u" sequences from the short list.  What is the purpose of
>>     that?

Because I found it clunky/inconvenient to "repeat" the "@kbd{C-x (} or
@key{F3}" in the form of

    @kbd{C-u C-u C-x (} or @kbd{C-u C-u @key{F3}}

so I preferred to move the C-u/C-uC-u discussion elsewhere.

Now that I think a bit more about it, I actually wonder why we bother
discussing this C-u business so early in the "Basic Keyboard Macro".
I personally never found this of much use: of all the times that I need
to modify the previous macro, the proportion where it can be done by
appending to it seems vanishingly small.

> Oh, and one more nit: there's no need to use the likes of
>
>    @item @kbd{C-x (} or @key{F3}
>
> (which also required you to switch from "@table @kbd" to @asis), you
> could use @itemx instead:
>
>    @item @key{F3}
>    @itemx C-x (

Oh, cool!

So how 'bout the simpler patch below instead,


        Stefan


PS: BTW, I think I figured why I can't easily use F3/F4 (nor F2) on my
systems: I have enabled the "mousekeys" option via setxkbmap (this is
for my old Thinkpad X30 whose mouse buttons don't work any more ;-)
Oddly enough on the machine on which I tried it earlier this results in
those keys doing nothing at all, but on the machine I'm currently using,
they correctly emulate mouse buttons.


diff --git a/doc/emacs/kmacro.texi b/doc/emacs/kmacro.texi
index dac41fdb87..914bb68890 100644
--- a/doc/emacs/kmacro.texi
+++ b/doc/emacs/kmacro.texi
@@ -48,15 +48,19 @@ Basic Keyboard Macro
 @section Basic Use
 
 @table @kbd
+@item C-x (
 @item @key{F3}
 Start defining a keyboard macro
 (@code{kmacro-start-macro-or-insert-counter}).
+@item C-x e
 @item @key{F4}
 If a keyboard macro is being defined, end the definition; otherwise,
 execute the most recent keyboard macro
 (@code{kmacro-end-or-call-macro}).
+@item C-u C-x (
 @item C-u @key{F3}
 Re-execute last keyboard macro, then append keys to its definition.
+@item C-u C-u C-x (
 @item C-u C-u @key{F3}
 Append keys to the last keyboard macro without re-executing it.
 @item C-x C-k r