changeset 68692:06780217e0ec

(Keyboard Macro Counter): Rewrite for clarity. (Keyboard Macros): Avoid "the user".

--- a/man/kmacro.texi	Tue Feb 07 23:54:00 2006 +0000
+++ b/man/kmacro.texi	Tue Feb 07 23:55:42 2006 +0000
@@ -10,7 +10,7 @@
   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
@@ -303,54 +303,43 @@
 @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
@@ -364,7 +353,7 @@
 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
@@ -375,7 +364,7 @@
 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