[Emacs-diffs] Changes to emacs/man/kmacro.texi [lexbind]

[Miles Bader]

Index: emacs/man/kmacro.texi
diff -c /dev/null emacs/man/kmacro.texi:1.3.2.1
*** /dev/null   Tue Oct 14 18:56:33 2003
--- emacs/man/kmacro.texi       Tue Oct 14 18:56:24 2003
***************
*** 0 ****
--- 1,522 ----
+ @c This is part of the Emacs manual.
+ @c Copyright (C) 1985,86,87,93,94,95,97,2000,2001,2002,2003
+ @c  Free Software Foundation, Inc.
+ @c See file emacs.texi for copying conditions.
+ @node Keyboard Macros, Files, Fixit, Top
+ @chapter Keyboard Macros
+ @cindex defining keyboard macros
+ @cindex keyboard macro
+ 
+   In this chapter we describe how a sequence of editing commands can
+ be recorded and repeated multiple times.
+ 
+   A @dfn{keyboard macro} is a command defined by the user to stand for
+ another sequence of keys.  For example, if you discover that you are
+ about to type @kbd{C-n C-d} forty times, you can speed your work by
+ defining a keyboard macro to do @kbd{C-n C-d} and calling it with a
+ repeat count of forty.
+ 
+   You define a keyboard macro while executing the commands which are the
+ definition.  Put differently, as you define a keyboard macro, the
+ definition is being executed for the first time.  This way, you can see
+ what the effects of your commands are, so that you don't have to figure
+ them out in your head.  When you are finished, the keyboard macro is
+ defined and also has been, in effect, executed once.  You can then do the
+ whole thing over again by invoking the macro.
+ 
+   Keyboard macros differ from ordinary Emacs commands in that they are
+ written in the Emacs command language rather than in Lisp.  This makes it
+ easier for the novice to write them, and makes them more convenient as
+ temporary hacks.  However, the Emacs command language is not powerful
+ enough as a programming language to be useful for writing anything
+ intelligent or general.  For such things, Lisp must be used.
+ 
+ @menu
+ * Basic Keyboard Macro::     Defining and running keyboard macros.
+ * Keyboard Macro Ring::      Where previous keyboard macros are saved.
+ * Keyboard Macro Counter::   Inserting incrementing numbers in macros.
+ * Keyboard Macro Query::     Making keyboard macros do different things each 
time.
+ * Save Keyboard Macro::      Giving keyboard macros names; saving them in 
files.
+ * Edit Keyboard Macro::      Editing keyboard macros.
+ * Keyboard Macro Step-Edit::   Interactively executing and editing a keyboard 
macro.
+ @end menu
+ 
+ @node Basic Keyboard Macro
+ @section Basic Use
+ 
+ @table @kbd
+ @item C-x (
+ Start defining a keyboard macro (@code{kmacro-start-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 C-u C-x (
+ Re-execute last keyboard macro, then add more keys to its definition.
+ @item C-u C-u C-x (
+ Add more keys to the last keyboard macro without re-executing it.
+ @item C-x q
+ When this point is reached during macro execution, ask for confirmation
+ (@code{kbd-macro-query}).
+ @item C-x C-k n
+ Give a command name (for the duration of the session) to the most
+ recently defined keyboard macro (@code{name-last-kbd-macro}).
+ @item C-x C-k b
+ Bind the most recently defined keyboard macro to a key sequence (for
+ the duration of the session) (@code{kmacro-bind-to-key}).
+ @item M-x insert-kbd-macro
+ Insert in the buffer a keyboard macro's definition, as Lisp code.
+ @item C-x C-k e
+ Edit a previously defined keyboard macro (@code{edit-kbd-macro}).
+ @item C-x C-k r
+ Run the last keyboard macro on each complete line in the region
+ (@code{apply-macro-to-region-lines}).
+ @end table
+ 
+ @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
+ (@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
+ definition (without becoming part of it!).  For example,
+ 
+ @example
+ C-x ( M-f foo C-x )
+ @end example
+ 
+ @noindent
+ defines a macro to move forward a word and then insert @samp{foo}.
+ 
+   The macro thus defined can be invoked again with the @kbd{C-x e}
+ command (@code{kmacro-end-and-call-macro}), which may be given a
+ repeat count as a numeric argument to execute the macro many times.
+ If you enter @kbd{C-x e} while defining a macro, the macro is
+ terminated and executed immediately.
+ 
+   After executing the macro with @kbd{C-x e}, you can use @kbd{e}
+ repeatedly to immediately repeat the macro one or more times.  For example,
+ 
+ @example
+ C-x ( xyz C-x e e e
+ @end example
+ 
+ @noindent
+ inserts @samp{xyzxyzxyzxyz} in the current buffer.
+ 
+   @kbd{C-x )} can also be given a repeat count as an argument, in
+ which case it repeats the macro that many times right after defining
+ it, but defining the macro counts as the first repetition (since it is
+ executed as you define it).  Therefore, giving @kbd{C-x )} an argument
+ of 4 executes the macro immediately 3 additional times.  An argument
+ of zero to @kbd{C-x e} or @kbd{C-x )} means repeat the macro
+ indefinitely (until it gets an error or you type @kbd{C-g} or, on
+ MS-DOS, @address@hidden).
+ 
+ @kindex C-x C-k C-s
+ @kindex C-x C-k C-k
+ Alternatively, you can use @kbd{C-x C-k C-s} to start a keyboard macro,
+ and @kbd{C-x C-k C-k...} to end and execute it.
+ 
+   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
+ to the next place you want to use it.  For example, if you want to change
+ each line, you should position point at the start of a line, and define a
+ macro to change that line and leave point at the start of the next line.
+ Then repeating the macro will operate on successive lines.
+ 
+   When a command reads an argument with the minibuffer, your
+ minibuffer input becomes part of the macro along with the command.  So
+ when you replay the macro, the command gets the same argument as
+ when you entered the macro.  For example,
+ 
+ @example
+ C-x ( C-a address@hidden C-n M-w C-x b f o o @key{RET} C-y C-x b @key{RET} 
C-x )
+ @end example
+ 
+ @noindent
+ defines a macro that copies the current line into the buffer
+ @samp{foo}, then returns to the original buffer.
+ 
+   You can use function keys in a keyboard macro, just like keyboard
+ keys.  You can even use mouse events, but be careful about that: when
+ the macro replays the mouse event, it uses the original mouse position
+ of that event, the position that the mouse had while you were defining
+ the macro.  The effect of this may be hard to predict.  (Using the
+ current mouse position would be even less predictable.)
+ 
+   One thing that doesn't always work well in a keyboard macro is the
+ command @kbd{C-M-c} (@code{exit-recursive-edit}).  When this command
+ exits a recursive edit that started within the macro, it works as you'd
+ expect.  But if it exits a recursive edit that started before you
+ invoked the keyboard macro, it also necessarily exits the keyboard 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 plain @kbd{C-x (} followed by retyping the whole definition so far.  As
+ a consequence it re-executes the macro as previously defined.
+ 
+   You can also add to the end of the definition of the last keyboard
+ macro without re-execuing it by typing @kbd{C-u C-u C-x (}.
+ 
+   The variable @code{kmacro-execute-before-append} specifies whether
+ a single @kbd{C-u} prefix causes the existing macro to be re-executed
+ before appending to it.
+ 
+ @findex apply-macro-to-region-lines
+ @kindex C-x C-k r
+   The command @kbd{C-x C-k r} (@code{apply-macro-to-region-lines})
+ repeats the last defined keyboard macro on each complete line within
+ the current region.  It does this line by line, by moving point to the
+ beginning of the line and then executing the macro.
+ 
+ @node Keyboard Macro Ring
+ @section Where previous keyboard macros are saved
+ 
+   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.
+ 
+   All commands which operates on the keyboard macro ring use the
+ same @kbd{C-x C-k} prefix.  Most of these commands can be executed and
+ repeated immediately after each other without repeating the @kbd{C-x
+ C-k} prefix.  For example,
+ 
+ @example
+ C-x C-k C-p C-p C-k C-k C-k C-n C-n C-k C-p C-k C-d
+ @end example
+ 
+ @noindent
+ will rotate the keyboard macro ring to the ``second previous'' macro,
+ execute the resulting head macro three times, rotate back to the
+ original head macro, execute that once, rotate to the ``previous''
+ macro, execute that, and finally delete it from the macro ring.
+ 
+ @findex kmacro-end-or-call-macro-repeat
+ @kindex C-x C-k C-k
+   The command @kbd{C-x C-k C-k} (@code{kmacro-end-or-call-macro-repeat})
+ executes the keyboard macro at the head of the macro ring.  You can
+ repeat the macro immediately by typing another @kbd{C-k}, or you can
+ rotate the macro ring immediately by typing @kbd{C-n} or @kbd{C-p}.
+ 
+ @findex kmacro-cycle-ring-next
+ @kindex C-x C-k C-n
+ @findex kmacro-cycle-ring-previous
+ @kindex C-x C-k C-p
+   The commands @kbd{C-x C-k C-n} (@code{kmacro-cycle-ring-next}) and
+ @kbd{C-x C-k C-p} (@code{kmacro-cycle-ring-previous}) rotates the
+ macro ring, bringing the next or previous keyboard macro to the head
+ of the macro ring.  The definition of the new head macro is displayed
+ in the echo area.  You can continue to rotate the macro ring
+ immediately by repeating just @kbd{C-n} and @kbd{C-p} until the
+ desired macro is at the head of the ring.  To execute the new macro
+ ring head immediately, just type @kbd{C-k}.  
+ 
+ @findex kmacro-view-macro-repeat
+ @kindex C-x C-k C-v
+ 
+   The commands @kbd{C-x C-k C-v} (@code{kmacro-view-macro-repeat})
+ displays the last keyboard macro, or when repeated (with @kbd{C-v}),
+ it displays the previous macro on the macro ring, just like @kbd{C-x
+ C-k C-p}, but without actually rotating the macro ring.  If you enter
+ @kbd{C-k} immediately after displaying a macro from the ring, that
+ macro is executed, but still without altering the macro ring.
+ 
+   So while e.g. @kbd{C-x C-k C-p C-p C-k C-k} makes the 3rd previous
+ macro the current macro and executes it twice, @kbd{C-x C-k C-v C-v
+ C-v C-k C-k} will display and execute the 3rd previous macro once and
+ then the current macro once.
+ 
+ @findex kmacro-delete-ring-head
+ @kindex C-x C-k C-d
+ 
+   The commands @kbd{C-x C-k C-d} (@code{kmacro-delete-ring-head})
+ removes and deletes the macro currently at the head of the macro
+ ring.  You can use this to delete a macro that didn't work as
+ expected, or which you don't need anymore.
+ 
+ @findex kmacro-swap-ring
+ @kindex C-x C-k C-t
+ 
+   The commands @kbd{C-x C-k C-t} (@code{kmacro-swap-ring})
+ interchanges the head of the macro ring with the previous element on
+ the macro ring.
+ 
+ @findex kmacro-call-ring-2nd-repeat
+ @kindex C-x C-k C-l
+ 
+   The commands @kbd{C-x C-k C-l} (@code{kmacro-call-ring-2nd-repeat})
+ executes the previous (rather than the head) element on the macro ring.
+ 
+ @node Keyboard Macro Counter
+ @section Inserting incrementing numbers in macros
+ 
+   Each keyboard macro has an associated counter which is automatically
+ incremented on every repetition of the keyboard macro.  Normally, the
+ macro counter is initialized to 0 when you start defining the macro,
+ and incremented by 1 after each insertion of the counter value;
+ that is, if you insert the macro counter twice while defining the
+ macro, it will be incremented by 2 time for each repetition of the
+ macro.
+ 
+ @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 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
+ 
+ @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.
+ 
+ @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 while defining a
+ keyboard macro, you set the macro counter to the same (initial) value
+ on each repetition of the macro.  If you 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).
+ 
+ @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.
+ 
+ @findex kmacro-set-format
+ @kindex C-x C-k C-f
+   The command @kbd{C-x C-k C-f} (@code{kmacro-set-format}) prompts
+ for the format to use when inserting the macro counter.  The default
+ format is @samp{%d}.  If you set the counter format before you define a
+ macro, that format is restored before each repetition of the macro.
+ Consequently, any changes you make to the macro counter format while
+ defining a macro are only active for the rest of the macro.
+ 
+ @node Keyboard Macro Query
+ @section Executing Macros with Variations
+ 
+ @kindex C-x q
+ @findex kbd-macro-query
+   Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect
+ similar to that of @code{query-replace}, where the macro asks you each
+ time around whether to make a change.  While defining the macro,
+ type @kbd{C-x q} at the point where you want the query to occur.  During
+ macro definition, the @kbd{C-x q} does nothing, but when you run the
+ macro later, @kbd{C-x q} asks you interactively whether to continue.
+ 
+   The valid responses when @kbd{C-x q} asks are @key{SPC} (or @kbd{y}),
+ @key{DEL} (or @kbd{n}), @key{RET} (or @kbd{q}), @kbd{C-l} and @kbd{C-r}.
+ The answers are the same as in @code{query-replace}, though not all of
+ the @code{query-replace} options are meaningful.
+ 
+   These responses include @key{SPC} to continue, and @key{DEL} to skip
+ the remainder of this repetition of the macro and start right away with
+ the next repetition.  @key{RET} means to skip the remainder of this
+ repetition and cancel further repetitions.  @kbd{C-l} redraws the screen
+ and asks you again for a character to say what to do.
+ 
+   @kbd{C-r} enters a recursive editing level, in which you can perform
+ editing which is not part of the macro.  When you exit the recursive
+ edit using @kbd{C-M-c}, you are asked again how to continue with the
+ keyboard macro.  If you type a @key{SPC} at this time, the rest of the
+ macro definition is executed.  It is up to you to leave point and the
+ text in a state such that the rest of the macro will do what you
+ address@hidden
+ 
+   @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument,
+ performs a completely different function.  It enters a recursive edit
+ reading input from the keyboard, both when you type it during the
+ definition of the macro, and when it is executed from the macro.  During
+ definition, the editing you do inside the recursive edit does not become
+ part of the macro.  During macro execution, the recursive edit gives you
+ a chance to do some particularized editing on each repetition.
+ @xref{Recursive Edit}.
+ 
+   Another way to vary the behavior of a keyboard macro is to use a
+ register as a counter, incrementing it on each repetition of the macro.
+ @xref{RegNumbers}.
+ 
+ @node Save Keyboard Macro
+ @section Naming and Saving Keyboard Macros
+ 
+ @cindex saving keyboard macros
+ @findex name-last-kbd-macro
+ @kindex C-x C-k n
+   If you wish to save a keyboard macro for later use, you can give it
+ a name using @kbd{C-x C-k n} (@code{name-last-kbd-macro}). 
+ This reads a name as an argument using the minibuffer and defines that name
+ to execute the macro.  The macro name is a Lisp symbol, and defining it in
+ this way makes it a valid command name for calling with @kbd{M-x} or for
+ binding a key to with @code{global-set-key} (@pxref{Keymaps}).  If you
+ specify a name that has a prior definition other than another keyboard
+ macro, an error message is shown and nothing is changed.
+ 
+ @cindex binding keyboard macros
+ @findex kmacro-bind-to-key
+ @kindex C-x C-k b
+   Rather than giving a keyboard macro a name, you can bind it to a
+ key using @kbd{C-x C-k b} (@code{kmacro-bind-to-key}) followed by the
+ key sequence you want the keyboard macro to be bound to.  You can
+ bind to any key sequence in the global keymap, but since most key
+ sequences already have other bindings, you should select the key
+ sequence carefylly.  If you try to bind to a key sequence with an
+ existing binding (in any keymap), you will be asked if you really
+ want to replace the existing binding of that key.
+ 
+ To avoid problems caused by overriding existing bindings, the key
+ sequences @kbd{C-x C-k 0} through @kbd{C-x C-k 9} and @kbd{C-x C-k A}
+ through @kbd{C-x C-k Z} are reserved for your own keyboard macro
+ bindings.  In fact, to bind to one of these key sequences, you only
+ need to type the digit or letter rather than the whole key sequences.
+ For example,
+ 
+ @example
+ C-x C-k b 4
+ @end example
+ 
+ @noindent
+ will bind the last keyboard macro to the key sequence @kbd{C-x C-k 4}.
+ 
+ @findex insert-kbd-macro
+   Once a macro has a command name, you can save its definition in a file.
+ Then it can be used in another editing session.  First, visit the file
+ you want to save the definition in.  Then use this command:
+ 
+ @example
+ M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET}
+ @end example
+ 
+ @noindent
+ This inserts some Lisp code that, when executed later, will define the
+ same macro with the same definition it has now.  (You need not
+ understand Lisp code to do this, because @code{insert-kbd-macro} writes
+ the Lisp code for you.)  Then save the file.  You can load the file
+ later with @code{load-file} (@pxref{Lisp Libraries}).  If the file you
+ save in is your init file @file{~/.emacs} (@pxref{Init File}) then the
+ macro will be defined each time you run Emacs.
+ 
+   If you give @code{insert-kbd-macro} a numeric argument, it makes
+ additional Lisp code to record the keys (if any) that you have bound to the
+ keyboard macro, so that the macro will be reassigned the same keys when you
+ load the file.
+ 
+ @node Edit Keyboard Macro
+ @section Interactively executing and editing a keyboard macro
+ 
+ @findex kmacro-edit-macro
+ @kindex C-x C-k C-e
+ @kindex C-x C-k RET
+   You can edit the last keyboard macro by typing @kbd{C-x C-k C-e} or
+ @kbd{C-x C-k RET} (@code{kmacro-edit-macro}).  This formats the macro
+ definition in a buffer and enters a specialized major mode for editing
+ it.  Type @kbd{C-h m} once in that buffer to display details of how to
+ edit the macro.  When you are finished editing, type @kbd{C-c C-c}.
+ 
+ @findex edit-kbd-macro
+ @kindex C-x C-k e
+   You can edit a named keyboard macro or a macro bound to a key by typing
+ @kbd{C-x C-k e} (@code{edit-kbd-macro}).  Follow that with the
+ keyboard input that you would use to invoke the address@hidden e} or
+ @kbd{M-x @var{name}} or some other key sequence.
+ 
+ @findex kmacro-edit-lossage
+ @kindex C-x C-k l
+   You can edit the last 100 keystrokes as a macro by typing
+ @kbd{C-x C-k l} (@code{kmacro-edit-lossage}).
+ 
+ @node Keyboard Macro Step-Edit
+ @section Interactively executing and editing a keyboard macro
+ 
+ @findex kmacro-step-edit-macro
+ @kindex C-x C-k SPC
+   You can interactively and stepwise replay and edit the last keyboard
+ macro one command at a time by typing @kbd{C-x C-k SPC} 
+ (@code{kmacro-step-edit-macro}).  Unless you quit the macro using
+ @kbd{q} or @kbd{C-g}, the edited macro replaces the last macro on the
+ macro ring.
+ 
+ This shows the last macro in the minibuffer together with the first
+ (or next) command to be executed, and prompts you for an action.
+ You can enter @kbd{?} to get a command summary.
+ 
+ The following commands are available in the step-edit mode and relate
+ to the first (or current) command in the keyboard macro:
+ 
+ @itemize @bullet{}
+ @item
+ @kbd{SPC} and @kbd{y} execute the current command, and advance to the
+ next command in the keyboard macro.
+ @item
+ @kbd{n}, @kbd{d}, and @kbd{DEL} skip and delete the current command.
+ @item
+ @kbd{f} skips the current command in this execution of the keyboard
+ macro, but doesn't delete it from the macro.
+ @item
+ @kbd{TAB} executes the current command, as well as all similar
+ commands immediately following the current command; for example, TAB
+ may be used to insert a sequence of characters (corresponding to a
+ sequence of @code{self-insert-command} commands).
+ @item
+ @kbd{c} continues execution (without further editing) until the end of
+ the keyboard macro.  If execution terminates normally, the edited
+ macro replaces the original keyboard macro.
+ @item
+ @kbd{C-k} skips and deletes the rest of the keyboard macro,
+ terminates step-editing, and replaces the original keyboard macro
+ with the edited macro.
+ @item
+ @kbd{q} and @kbd{C-g} cancels the step-editing of the keyboard macro;
+ discarding any changes made to the keyboard macro.
+ @item
+ @kbd{i KEY... C-j} reads and executes a series of key sequences (not
+ including the final @kbd{C-j}), and inserts them before the current
+ command in the keyboard macro, without advancing over the current
+ command.
+ @item
+ @kbd{I KEY...} reads one key sequence, executes it, and inserts it
+ before the current command in the keyboard macro, without advancing
+ over the current command.
+ @item
+ @kbd{r KEY... C-j} reads and executes a series of key sequences (not
+ including the final @kbd{C-j}), and replaces the current command in
+ the keyboard macro with them, advancing over the inserted key
+ sequences.
+ @item
+ @kbd{R KEY...} reads one key sequence, executes it, and replaces the
+ current command in the keyboard macro with that key sequence,
+ advancing over the inserted key sequence.
+ @item
+ @kbd{a KEY... C-j} executes the current command, then reads and
+ executes a series of key sequences (not including the final
+ @kbd{C-j}), and inserts them after the current command in the keyboard
+ macro; it then advances over the current command and the inserted key
+ sequences.
+ @item
+ @kbd{A KEY... C-j} executes the rest of the commands in the keyboard
+ macro, then reads and executes a series of key sequences (not
+ including the final @kbd{C-j}), and appends them at the end of the
+ keyboard macro; it then terminates the step-editing and replaces the
+ original keyboard macro with the edited macro.
+ @end itemize
+ 
+ @ignore
+    arch-tag: c1b0dd3b-3159-4c08-928f-52e763953e9c
+ @end ignore