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

[Kim F. Storm]

Index: emacs/man/custom.texi
diff -c emacs/man/custom.texi:1.57 emacs/man/custom.texi:1.58
*** emacs/man/custom.texi:1.57  Wed Jun  4 05:26:06 2003
--- emacs/man/custom.texi       Sun Aug 17 18:26:42 2003
***************
*** 19,33 ****
  customizations for future sessions, this actually works by editing
  @file{.emacs} for you.
  
  @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::
--- 19,35 ----
  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.
  * Key Bindings::      The keymaps say what command each key runs.
                          By changing them, you can "redefine keys".
  * Keyboard Translations::
***************
*** 1057,1287 ****
  @code{enable-local-variables}.  The default is @code{maybe}, which is
  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, @address@hidden).
- 
-   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.
- 
- @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 address@hidden 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
- 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 Key Bindings
  @section Customizing Key Bindings
--- 1059,1064 ----