Doc of keyboard macros

Doc of keyboard macros

[Stefan Monnier]

https://emacs.stackexchange.com/questions/44918 points out that `C-x (`
and `C-x e` are not very visible in the doc, while F3 and F4 may be
difficult to reach on Apple's machines (and I just saw that they are
also difficult to reach on my Debian machine for some reason).
So I suggest making the "old" keyboard macro bindings a bit more
prominent in the doc (I also happen to prefer them over F3 and F4,
because of their mnemonic value).

Any objection to the patch below for emacs-26?


        Stefan


diff --git a/doc/emacs/kmacro.texi b/doc/emacs/kmacro.texi
index dac41fdb87..e71f23632d 100644
--- a/doc/emacs/kmacro.texi
+++ b/doc/emacs/kmacro.texi
@@ -47,19 +47,27 @@ Keyboard Macros
 @node Basic Keyboard Macro
 @section Basic Use
 
-@table @kbd
-@item @key{F3}
+@table @asis
+@item @kbd{C-x (} or @key{F3}
 Start defining a keyboard macro
 (@code{kmacro-start-macro-or-insert-counter}).
-@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 @key{F3}
-Re-execute last keyboard macro, then append keys to its definition.
-@item C-u C-u @key{F3}
-Append keys to the last keyboard macro without re-executing it.
-@item C-x C-k r
+
+When invoked with a @kbd{C-u} prefix, it first re-executes the last
+keyboard macro and then appends keys to its definition.
+
+When invoked with a double @kbd{C-u C-u}
+it append keys to the last keyboard macro without re-executing it.
+
+@item @kbd{C-x e} or @key{F4}
+Execute the most recent keyboard macro.  If a keyboard macro is being
+defined, end the definition.
+
+For historical reasons, the two bindings are subtly different: if
+invoked while a macro is being defined, @key{F4} only ends the current
+definition, while @kbd{C-x e} additionally immediately executes the
+just defined macro.
+
+@item @kbd{C-x C-k r}
 Run the last keyboard macro on each line that begins in the region
 (@code{apply-macro-to-region-lines}).
 @end table

Re: Doc of keyboard macros

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Date: Mon, 24 Sep 2018 10:47:55 -0400
> 
> https://emacs.stackexchange.com/questions/44918 points out that `C-x (`
> and `C-x e` are not very visible in the doc, while F3 and F4 may be
> difficult to reach on Apple's machines (and I just saw that they are
> also difficult to reach on my Debian machine for some reason).
> So I suggest making the "old" keyboard macro bindings a bit more
> prominent in the doc (I also happen to prefer them over F3 and F4,
> because of their mnemonic value).
> 
> Any objection to the patch below for emacs-26?

No real objection, but:

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

  . 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?

Re: Doc of keyboard macros

[Eli Zaretskii]

> Date: Mon, 24 Sep 2018 18:21:40 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: emacs-devel@gnu.org
> 
>   . 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.
> 
>   . 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?

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 (

Re: Doc of keyboard macros

[Stefan Monnier]

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

Re: Doc of keyboard macros

[Andreas Schwab]

On Sep 24 2018, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> 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}

s/@item/@itemx/

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

Re: Doc of keyboard macros

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Mon, 24 Sep 2018 12:36:35 -0400
> 
> >>   . 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 think so.

> 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".

Because they have very different effect, not just some minor variation
of the original command.

>  @table @kbd
> +@item C-x (
>  @item @key{F3}

The second one should be @itemx, not @item.  And I think we should
have F3 first, because "C-x (" is deprecated, and we are now
reinstating it for the benefit of some systems that are either rare or
ones that we aren't supposed to care about too much.

> +@item C-x e
>  @item @key{F4}

Same here.

> +@item C-u C-x (
>  @item C-u @key{F3}

Same here.

> +@item C-u C-u C-x (
>  @item C-u C-u @key{F3}

Same here.

Thanks.

Re: Doc of keyboard macros

[Stefan Monnier]

Fixed and pushed,
Thank you,


        Stefan


Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stefan Monnier <monnier@iro.umontreal.ca>
>> Date: Mon, 24 Sep 2018 12:36:35 -0400
>> 
>> >>   . 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 think so.
>
>> 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".
>
> Because they have very different effect, not just some minor variation
> of the original command.
>
>>  @table @kbd
>> +@item C-x (
>>  @item @key{F3}
>
> The second one should be @itemx, not @item.  And I think we should
> have F3 first, because "C-x (" is deprecated, and we are now
> reinstating it for the benefit of some systems that are either rare or
> ones that we aren't supposed to care about too much.
>
>> +@item C-x e
>>  @item @key{F4}
>
> Same here.
>
>> +@item C-u C-x (
>>  @item C-u @key{F3}
>
> Same here.
>
>> +@item C-u C-u C-x (
>>  @item C-u C-u @key{F3}
>
> Same here.
>
> Thanks.

Re: Doc of keyboard macros

[Juri Linkov]

> And I think we should have F3 first, because "C-x (" is deprecated,
> and we are now reinstating it for the benefit of some systems that are
> either rare or ones that we aren't supposed to care about too much.

There is a current tendency towards deprecating F1-F10 function keys
by hardware manufacturers.  These keys are already hard to press by default
on PC: a special additional key <Fn> needs to be pressed in combination of
<Fn>-<F3>, and a Chromebook has no row of function keys at all: in order
to get <F4>, you have to press <Search>-4.

Re: Doc of keyboard macros

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,  emacs-devel@gnu.org
> Date: Mon, 24 Sep 2018 22:23:03 +0300
> 
> There is a current tendency towards deprecating F1-F10 function keys
> by hardware manufacturers.  These keys are already hard to press by default
> on PC: a special additional key <Fn> needs to be pressed in combination of
> <Fn>-<F3>, and a Chromebook has no row of function keys at all: in order
> to get <F4>, you have to press <Search>-4.

Those are still faster than "C-x (", since they are a single key
combination, whereas "C-x (" is 2 key combinations.

Re: Doc of keyboard macros

[Alan Mackenzie]

Hello, Eli.

On Mon, Sep 24, 2018 at 22:35:40 +0300, Eli Zaretskii wrote:
> > From: Juri Linkov <juri@linkov.net>
> > Cc: Stefan Monnier <monnier@iro.umontreal.ca>,  emacs-devel@gnu.org
> > Date: Mon, 24 Sep 2018 22:23:03 +0300

> > There is a current tendency towards deprecating F1-F10 function keys
> > by hardware manufacturers.  These keys are already hard to press by default
> > on PC: a special additional key <Fn> needs to be pressed in combination of
> > <Fn>-<F3>, and a Chromebook has no row of function keys at all: in order
> > to get <F4>, you have to press <Search>-4.

> Those are still faster than "C-x (", since they are a single key
> combination, whereas "C-x (" is 2 key combinations.

I don't think the speed (or otherwise) of C-x ( compared with F3 is
important.  After one of these, the user is going to be slowly and
carefully typing in a sequence of key sequences, not wanting to make
mistakes and having to start again.

I would prefer to keep C-x ( and C-x ), because I use F3 and F4 for
other things (in particular, switching to frames F3 and F4).  C-x
<paren> also feels more mnemonic than F3 and F4.

Sorry if this is opening up an old debate which was settled long ago,
and I somehow missed.

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Doc of keyboard macros

[Joost Kremers]

On Mon, Sep 24 2018, Eli Zaretskii wrote:
>> From: Juri Linkov <juri@linkov.net>
>> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, 
>> emacs-devel@gnu.org
>> Date: Mon, 24 Sep 2018 22:23:03 +0300
>> 
>> There is a current tendency towards deprecating F1-F10 function 
>> keys
>> by hardware manufacturers.  These keys are already hard to 
>> press by default
>> on PC: a special additional key <Fn> needs to be pressed in 
>> combination of
>> <Fn>-<F3>, and a Chromebook has no row of function keys at all: 
>> in order
>> to get <F4>, you have to press <Search>-4.
>
> Those are still faster than "C-x (", since they are a single key
> combination, whereas "C-x (" is 2 key combinations.

I think that's debatable. Personally, if I want to hit a function 
key, I need to move my hand from the home row to reach for it, and 
I need to look at the keyboard to do it. Also, the <Fn> special 
modifier key is not in my muscle memory, which means I'd need to 
look at that as well.[1]

So hitting `C-x (` is definitely faster for me and requires no 
conscious action, quite unlike the function keys. I never use 
F3/F4 to define keyboard macros.

In fact, I never quite understood why (some) function keys have 
default bindings at all in Emacs. To me, function keys are as 
cumbersome as cursor keys, Home/End, or PgUp/PgDn.[2] Not that I 
mind, of course, it's just puzzling to me.

Joost



[1] My laptop's BIOS allows me to switch the effect of the Fn key, 
so I could actually get <F3> by pressing just the relevant key 
without Fn if I wanted to. But I'd still need to look at the 
keyboard to press it.

[2] Admittedly, those have default bindings as well, but they are 
standard across applications and operating systems. Function keys 
are not.


-- 
Joost Kremers
Life has its moments

Re: Doc of keyboard macros

[Mathias Dahl]

[-- Attachment #1: Type: text/plain, Size: 2366 bytes --]

>
> I think that's debatable. Personally, if I want to hit a function
> key, I need to move my hand from the home row to reach for it, and
> I need to look at the keyboard to do it....
>
> So hitting `C-x (` is definitely faster for me and requires no
> conscious action, quite unlike the function keys. I never use
> F3/F4 to define keyboard macros.
>
> In fact, I never quite understood why (some) function keys have
> default bindings at all in Emacs. To me, function keys are as
> cumbersome as cursor keys, Home/End, or PgUp/PgDn.[2] Not that I
> mind, of course, it's just puzzling to me.
>

 Hi,

Just to contrast the above, I'm a heavy user of the function keys in Emacs.
During the years, I have bound F1-F9 to some of my most used commands.
There's almost no logic at all in how they are setup but they are hard
wired in my brain by now and must be there. Not that I think anyone is
interested, but here they are, in order:

F1 - Switch to previous buffer (my most used command/key). This and kill
buffer on F5 was inspired by something Alex Schroeder once wrote about on
Emacswiki.
F2 - Other window
F3 - Anything (yup, never got around switching to Helm, or Ivy for that
matter), mostly with a bunch of super custom sources and commands
F4 - For some reason, this is untouched...
F5 - Kill buffer (no questions if buffer is saved), beeps if the buffer is
changed. I use this a lot.
F6 - Strip trailing spaces
F7 - Start kbd macro (this was before F3 was bound to that). I use C-x (
and C-x ) when I don't have my own setup or is using Emacs -Q for some
other reason...
F8 - Stop and/or execute kbd macro
F9 - Toggle truncate lines

I can "kind of" touch type, but I mostly do it if I type longer texts like
e-mails and such. So leaving the home row is not something that bothers me
much. And I make sure to use keyboards that does not require the Fn key to
make the function keys to work.

Most of the time I use the cursor/arrow keys instead of C-f, C-b, C-n and
C-p, but I use the latter also, when it suits me. Sometimes I also use
Home/End and PgUp/PgDn. Sometimes I use the Emacs' keys for the same
commands.

So, perhaps what I want to say is that some of us work in some
semi-random,  semi-structured ways, mixing "pure" Emacs with other styles
of interacting with Emacs. But that does not mean we should not strive for
good defaults...

/Mathias

[-- Attachment #2: Type: text/html, Size: 2924 bytes --]

Re: Doc of keyboard macros

[Marcin Borkowski]

On 2018-10-10, at 22:25, Mathias Dahl <mathias.dahl@gmail.com> wrote:

>>
>> I think that's debatable. Personally, if I want to hit a function
>> key, I need to move my hand from the home row to reach for it, and
>> I need to look at the keyboard to do it....
>>
>> So hitting `C-x (` is definitely faster for me and requires no
>> conscious action, quite unlike the function keys. I never use
>> F3/F4 to define keyboard macros.
>>
>> In fact, I never quite understood why (some) function keys have
>> default bindings at all in Emacs. To me, function keys are as
>> cumbersome as cursor keys, Home/End, or PgUp/PgDn.[2] Not that I
>> mind, of course, it's just puzzling to me.
>>
>
>  Hi,
>
> Just to contrast the above, I'm a heavy user of the function keys in Emacs.
> During the years, I have bound F1-F9 to some of my most used commands.

Interesting.

> There's almost no logic at all in how they are setup but they are hard
> wired in my brain by now and must be there. Not that I think anyone is
> interested, but here they are, in order:
>
> F1 - Switch to previous buffer (my most used command/key). This and kill
> buffer on F5 was inspired by something Alex Schroeder once wrote about on
> Emacswiki.
> F2 - Other window
> F3 - Anything (yup, never got around switching to Helm, or Ivy for that
> matter), mostly with a bunch of super custom sources and commands
> F4 - For some reason, this is untouched...
> F5 - Kill buffer (no questions if buffer is saved), beeps if the buffer is
> changed. I use this a lot.
> F6 - Strip trailing spaces
> F7 - Start kbd macro (this was before F3 was bound to that). I use C-x (
> and C-x ) when I don't have my own setup or is using Emacs -Q for some
> other reason...
> F8 - Stop and/or execute kbd macro
> F9 - Toggle truncate lines

I also use some function keys.

F3/F4 - default (keyboard macros).  I like these bindings a lot
(especially F3 when recording a macro).

F6 - see here http://mbork.pl/2017-06-12_smart-next-window-or-buffer

F8 - my hydra with various stuff (like git blame, git timemachine, Emacs
uptime, woman, switching between 1- and 2-monitor setup, toggle a few
minor modes, ffap...

F10 - my hydra with Org-related stuff (mainly clocking)

F12 - my hydra for emms

Best,

--
Marcin Borkowski
http://mbork.pl

Re: Doc of keyboard macros

[Yuri Khan]

On Sun, Oct 14, 2018 at 3:30 PM Marcin Borkowski <mbork@mbork.pl> wrote:

> I also use some function keys.

Mine is an unholy mess of bindings picked up from various editors and
IDEs I used to use.

F1: help prefix
F1 F1 (in emacs-lisp-mode-map): dwim wrapper that invokes
‘describe-symbol’ on ‘(elisp--current-symbol)’ or
‘(elisp--fnsym-in-current-sexp)’

F2: save-buffer (from Norton Commander and Turbo Pascal)

F3: find-file (from Turbo Pascal)

F4: replace-string (from Midnight Commander)

F5: zoom/unzoom (a custom command that [saves the window configuration
then kills other windows] or restores the saved window configuration;
inspired by Turbo Pascal)

C-F5: revert-buffer (from various web browsers)

M-F7 (in dired-mode-map): grep (from Norton Commander)

F8: next-error; S-F8: previous-error (from Visual Studio)

F9: projectile-compile-project, C-F9: projectile-run-project (from
Turbo Pascal), S-F9: projectile-test-project

F10: abort-recursive-edit if in a minibuffer, or kill-buffer otherwise
(heavily inspired by Norton Commander)

F11: toggle-frame-fullscreen (from web browsers)

M-F11: a ‘tabulated-list-mode’-based display of ‘recentf-list’
allowing removal and re-visiting (inspired by FAR Manager, a
descendant of Norton Commander)

Re: Doc of keyboard macros

[Juri Linkov]

> M-F7 (in dired-mode-map): grep (from Norton Commander)

Speaking of *Commanders, here are more-less directly corresponding commands:

(define-key dired-mode-map [f3]  'dired-view-file)
(define-key dired-mode-map [f4]  'dired-find-file)
(define-key dired-mode-map [f5]  'dired-do-copy)
(define-key dired-mode-map [f6]  'dired-do-rename)
(define-key dired-mode-map [f7]  'dired-create-directory)
(define-key dired-mode-map [f8]  'dired-do-delete)
(define-key dired-mode-map [f9]  'tmm-menubar)
(define-key dired-mode-map [f10] 'quit-window)

(mapc (lambda (elt)
        (define-key dired-mode-map (car elt)
          `(lambda ()
             (interactive)
             (dired-sort-other (concat dired-listing-switches ,(cadr elt))))))
      '(([(control f3)]       ""     "by name")
        ([(control f4)]       " -X"  "by extension")
        ([(control f5)]       " -t"  "by time")
        ([(control f6)]       " -S"  "by size")
        ([(control shift f3)] " -r"  "by reverse name")
        ([(control shift f4)] " -rX" "by reverse extension")
        ([(control shift f5)] " -rt" "by reverse time")
        ([(control shift f6)] " -rS" "by reverse size")))

(define-key dired-mode-map [insert] 'dired-mark)
(define-key dired-mode-map [kp-add] 'dired-mark-files-regexp)
(define-key dired-mode-map [kp-multiply] 'dired-toggle-marks)

(define-key dired-mode-map [(meta f7)] 'rgrep)

(define-key dired-mode-map [(shift control ?u)] 'window-swap-states)

(define-key dired-mode-map [(shift f5)] 'dired-du-count-sizes)

PS: dired-du-count-sizes from bug#22829 might need caching like in
http://invisible-island.net/ded/ded.html#dtree_caching

Re: Doc of keyboard macros

[Van L]

Is there a keycommand layout for the narrower keyboard 
without numpad, pgup, pgdown, home, end, etc?

In particular, for the aluminum Apple keyboard missing
the right control key. It is more comfortable for the
right elbow to not have to reach far out to the mouse. 

RE: Doc of keyboard macros

[Drew Adams]

> > And I think we should have F3 first, because "C-x (" is deprecated,
> > and we are now reinstating it for the benefit of some systems that are
> > either rare or ones that we aren't supposed to care about too much.
> 
> There is a current tendency towards deprecating F1-F10 function keys
> by hardware manufacturers.  These keys are already hard to press by default
> on PC: a special additional key <Fn> needs to be pressed in combination of
> <Fn>-<F3>, and a Chromebook has no row of function keys at all: in order
> to get <F4>, you have to press <Search>-4.

In addition to what Juri says: It makes sense for Emacs and users
to bind function keys (when available, obviously) to repeatable
commands, so you can just hold down the key to repeat the action.
It's a waste to use `F3' for `kmacro-start-macro-or-insert-counter'.

So +1 for favoring `C-x (' etc. over `F3' etc.

Re: Doc of keyboard macros

[Filipp Gunbin]

On 24/09/2018 20:07 +0300, Eli Zaretskii wrote:

> The second one should be @itemx, not @item.  And I think we should
> have F3 first, because "C-x (" is deprecated, and we are now
> reinstating it for the benefit of some systems that are either rare or
> ones that we aren't supposed to care about too much.

It always puzzled me why "C-x (" was deprecated.  I never found it
easier to reach F-row.  Yes, 1 key instead of 2, but..

Using prefix arg and other macro commands (C-x C-k something) looks more
uniform with "C-x (", which can be thought of as a shortcut for C-x C-k
[C-]s.

Filipp