@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Keyboard Macros, Files, Fixit, Top
@chapter Keyboard Macros
In this chapter we describe how to record a sequence of editing
commands so you can repeat it conveniently later.
- A @dfn{keyboard macro} is a command defined by the user to stand for
+ A @dfn{keyboard macro} is a command defined by an Emacs user to stand for
another sequence of keys. For example, if you discover that you are
about to type @kbd{C-n M-d C-d} forty times, you can speed your work by
defining a keyboard macro to do @kbd{C-n M-d C-d}, and then executing
@section Basic Use
@table @kbd
-@item C-x (
-@itemx @key{F3}
+@item @key{F3}
+@itemx C-x (
Start defining a keyboard macro (@code{kmacro-start-macro}).
+@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-x )
End the definition of a keyboard macro (@code{kmacro-end-macro}).
@item C-x e
Execute the most recent keyboard macro (@code{kmacro-end-and-call-macro}).
First end the definition of the keyboard macro, if currently defining it.
To immediately execute the keyboard macro again, just repeat the @kbd{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 (
Re-execute last keyboard macro, then add more keys to its definition.
@item C-u C-u C-x (
(@code{apply-macro-to-region-lines}).
@end table
+@kindex F3
+@kindex F4
@kindex C-x (
@kindex C-x )
@kindex C-x e
@findex kmacro-start-macro
@findex kmacro-end-macro
@findex kmacro-end-and-call-macro
- To start defining a keyboard macro, type the @kbd{C-x (} command
+ To start defining a keyboard macro, type the @kbd{F3} or @kbd{C-x (} command
(@code{kmacro-start-macro}). From then on, your keys continue to be
executed, but also become part of the definition of the macro. @samp{Def}
appears in the mode line to remind you of what is going on. When you are
-finished, the @kbd{C-x )} command (@code{kmacro-end-macro}) terminates the
+finished, the @kbd{F4} or @kbd{C-x )} command (@code{kmacro-end-macro}) terminates the
definition (without becoming part of it!). For example,
@example
The key @key{F4} is like a combination of @kbd{C-x )} and @kbd{C-x
e}. If you're defining a macro, @key{F4} ends the definition.
-Otherwise it executes the last macro.
+Otherwise it executes the last macro. For example,
+
+@example
+F3 xyz F4 F4 F4
+@end example
+
+@noindent
+inserts @samp{xyzxyzxyz} in the current buffer.
If you wish to repeat an operation at regularly spaced places in the
text, define a macro and include as part of the macro the commands to move
macro as part of the process.
After you have terminated the definition of a keyboard macro, you can add
-to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent
+to the end of its definition by typing @kbd{C-u F3} or @kbd{C-u C-x (}.
+This is equivalent
to plain @kbd{C-x (} followed by retyping the whole definition so far. As
a consequence it re-executes the macro as previously defined.
@node Keyboard Macro Ring
@section The Keyboard Macro Ring
- All defined keyboard macros are recorded in the ``keyboard macro ring'',
+ All defined keyboard macros are recorded in the ``keyboard macro ring,''
a list of sequences of keys. There is only one keyboard macro ring,
shared by all buffers.
@findex kmacro-insert-counter
@kindex C-x C-k C-i
The command @kbd{C-x C-k C-i} (@code{kmacro-insert-counter}) inserts
-the current value of the keyboard macro counter and increments the
-counter by 1. You can use a numeric prefix argument to specify a
-different increment. If you just specify a @kbd{C-u} prefix, the last
-inserted counter value is repeated and the counter is not incremented.
-For example, if you enter the following sequence while defining a macro
+the current value of the current keyboard macro's counter, and
+increments the counter by 1. You can use a numeric prefix argument to
+specify a different increment. If you just specify a @kbd{C-u}
+prefix, then the increment is zero, so it repeats the last inserted
+counter value. For example, if you enter the following sequence while
+defining a macro
@example
C-x C-k C-i C-x C-k C-i C-u C-x C-k C-i C-x C-k C-i
@end example
@noindent
-the text @samp{0112} is inserted in the buffer, and for the first and
-second execution of the macro @samp{3445} and @samp{6778} are
-inserted.
+it inserts @samp{0112} in the buffer. The next two iterations
+of the macro will insert @samp{3445} and @samp{6778}.
- This command usually only makes sense while defining a keyboard macro.
-But its behavior when no keyboard macro is being defined or executed
-is predictable: it inserts and increments the counter of the head of
-the keyboard macro ring.
+ This command usually only makes sense while defining a keyboard
+macro. But its behavior when no keyboard macro is being defined or
+executed is predictable: it inserts and increments the counter of the
+macro at the head of the keyboard macro ring.
@findex kmacro-set-counter
@kindex C-x C-k C-c
- The command @kbd{C-x C-k C-c} (@code{kmacro-set-counter}) prompts
-for the initial value of the keyboard macro counter if you use it
-before you define a keyboard macro. If you use it before executing a
-keyboard macro, it resets that macro's counter. If you use it while
-defining a keyboard macro, then the macro counter gets reset to that same
-value on each repetition of the macro. Rather than having the command
-prompt for a value, you can also specify the value with a numeric
-prefix argument. If you just specify a @kbd{C-u} prefix, the counter
-is reset to the value it had prior to the current repetition of the
-macro (undoing any increments so far in this repetition). If you just
-specify a @kbd{C-u} prefix while no macro is being defined or executed,
-then the new value of the counter is essentially unpredictable.
+ The command @kbd{C-x C-k C-c} (@code{kmacro-set-counter}) sets the
+current macro counter to the value of the numeric argument. If you use
+it inside the macro, it operates on each repetition of the macro. If
+you specify just @kbd{C-u} as the prefix, while executing the macro,
+that resets the counter to the value it had at the beginning of the
+current repetition of the macro (undoing any increments so far in this
+repetition).
@findex kmacro-add-counter
@kindex C-x C-k C-a
- The command @kbd{C-x C-k C-a} (@code{kmacro-add-counter}) prompts
-for a value to add to the macro counter. You can also specify the
-value with a numeric prefix argument. If you just specify a @kbd{C-u}
-prefix, the counter is reset to the last value inserted by any
-keyboard macro. Usually, this will only make sense if that value was
-inserted during the current macro definition or repetition.
-
- This command normally only makes sense while defining a keyboard macro.
-But its behavior when no keyboard macro is being defined or executed
-is predictable: it affects the counter of the head of the keyboard
-macro ring.
+ The command @kbd{C-x C-k C-a} (@code{kmacro-add-counter}) adds the
+prefix argument to the current macro counter. With just @kbd{C-u} as
+argument, it resets the counter to the last value inserted by any
+keyboard macro. (Normally, when you use this, the last insertion
+will be in the same macro and it will be the same counter.)
@findex kmacro-set-format
@kindex C-x C-k C-f
Lisp Reference Manual}). Do not put the format string inside double
quotes when you insert it in the minibuffer.
-If you use this command while no keyboard macro is being defined or
+ If you use this command while no keyboard macro is being defined or
executed, the new format affects all subsequent macro definitions.
Existing macros continue to use the format in effect when they were
defined. If you set the format while defining a keyboard macro, this
corresponding changes during its definition, have no effect on
subsequent macros.
-The format set by @kbd{C-x C-k C-f} does not affect insertion of
+ The format set by @kbd{C-x C-k C-f} does not affect insertion of
numbers stored in registers.
@node Keyboard Macro Query
@node Save Keyboard Macro
@section Naming and Saving Keyboard Macros
-@table
+@table @kbd
@item C-x C-k n
Give a command name (for the duration of the Emacs session) to the most
recently defined keyboard macro (@code{kmacro-name-last-macro}).