(Customization): Add xref to Keyboard Macros chapter.

(Keyboard Macros): Move to new kmacro.texi file.

man/custom.texi

@@ -19,15 +19,17 @@ between sessions unless you save the customization in a file such as
 customizations for future sessions, this actually works by editing
 @file{.emacs} for you.
 
+  Another means of customization is the keyboard macro, which is a
+sequence of keystrokes to be replayed with a single command.
+@xref{Keyboard Macros}, for full instruction how to record, manage, and
+replay sequences of keys.
+
 @menu
 * Minor Modes::		Each minor mode is one feature you can turn on
 			  independently of any others.
 * Variables::		Many Emacs commands examine Emacs variables
 			  to decide what to do; by setting variables,
 			  you can control their functioning.
-* Keyboard Macros::	A keyboard macro records a sequence of
-			  keystrokes to be replayed with a single
-			  command.
 * Key Bindings::	The keymaps say what command each key runs.
 			  By changing them, you can "redefine keys".
 * Keyboard Translations::
@@ -1058,231 +1060,6 @@ value are @code{t}, @code{nil}, and anything else, just as for
 neither @code{t} nor @code{nil}, so normally Emacs does ask for
 confirmation about file settings for these variables.
 
-@node Keyboard Macros
-@section Keyboard Macros
-
-@cindex defining keyboard macros
-@cindex keyboard macro
-  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.
-
-@table @kbd
-@item C-x (
-Start defining a keyboard macro (@code{start-kbd-macro}).
-@item C-x )
-End the definition of a keyboard macro (@code{end-kbd-macro}).
-@item C-x e
-Execute the most recent keyboard macro (@code{call-last-kbd-macro}).
-@item C-u C-x (
-Re-execute last keyboard macro, then add more keys to its definition.
-@item C-x q
-When this point is reached during macro execution, ask for confirmation
-(@code{kbd-macro-query}).
-@item M-x name-last-kbd-macro
-Give a command name (for the duration of the session) to the most
-recently defined keyboard macro.
-@item M-x insert-kbd-macro
-Insert in the buffer a keyboard macro's definition, as Lisp code.
-@item C-x C-k
-Edit a previously defined keyboard macro (@code{edit-kbd-macro}).
-@item M-x apply-macro-to-region-lines
-Run the last keyboard macro on each complete line in the region.
-@end table
-
-  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.
-
-  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.
-
-@menu
-* Basic Kbd Macro::     Defining and running keyboard macros.
-* Save Kbd Macro::      Giving keyboard macros names; saving them in files.
-* Kbd Macro Query::     Making keyboard macros do different things each time.
-@end menu
-
-@node Basic Kbd Macro
-@subsection Basic Use
-
-@kindex C-x (
-@kindex C-x )
-@kindex C-x e
-@findex start-kbd-macro
-@findex end-kbd-macro
-@findex call-last-kbd-macro
-  To start defining a keyboard macro, type the @kbd{C-x (} command
-(@code{start-kbd-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{end-kbd-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{call-last-kbd-macro}), which may be given a repeat count
-as a numeric argument to execute the macro many times.  @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, @kbd{C-@key{BREAK}}).
-
-  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 C-@key{SPC} 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.
-
-@findex edit-kbd-macro
-@kindex C-x C-k
-  You can edit a keyboard macro already defined by typing @kbd{C-x C-k}
-(@code{edit-kbd-macro}).  Follow that with the keyboard input that you
-would use to invoke the macro---@kbd{C-x e} or @kbd{M-x @var{name}} or
-some other key sequence.  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 apply-macro-to-region-lines
-  The command @kbd{M-x 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 Save Kbd Macro
-@subsection Naming and Saving Keyboard Macros
-
-@cindex saving keyboard macros
-@findex name-last-kbd-macro
-  If you wish to save a keyboard macro for longer than until you define the
-next one, you must give it a name using @kbd{M-x 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.
-
-@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 Kbd Macro Query
-@subsection 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
-want.@refill
-
-  @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 Key Bindings
 @section Customizing Key Bindings
 @cindex key bindings