From 6c6b540711d0dd8a8eac9547968ed4dfb493fd1c Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 1 Feb 2019 17:34:23 +0200 Subject: [PATCH] Correct the docs of inserting kmacro counter * doc/emacs/kmacro.texi (Keyboard Macro Counter): Correct the description of the affect "C-u" has on inserting the macro counter. Define "previous counter value". * lisp/kmacro.el (kmacro-insert-counter) (kmacro-start-macro-or-insert-counter): Fix the doc strings regarding the effect of "C-u". (Bug#34263) --- doc/emacs/kmacro.texi | 19 +++++++++++++------ lisp/kmacro.el | 12 ++++++++---- 2 files changed, 21 insertions(+), 10 deletions(-) diff --git a/doc/emacs/kmacro.texi b/doc/emacs/kmacro.texi index a7d849a7f0d..65387ae783c 100644 --- a/doc/emacs/kmacro.texi +++ b/doc/emacs/kmacro.texi @@ -241,10 +241,17 @@ determined by the customizable variable @code{kmacro-ring-max}. @section The Keyboard Macro Counter Each keyboard macro has an associated counter, which is initialized -to 0 when you start defining the macro. This counter allows you to -insert a number into the buffer that depends on the number of times -the macro has been called. The counter is incremented each time its -value is inserted into the buffer. +to 0 when you start defining the macro. This @dfn{current counter} +allows you to insert a number into the buffer that depends on the +number of times the macro has been called. The counter is normally +incremented each time its value is inserted into the buffer. + +In addition to the current counter, keyboard macros also maintain the +@dfn{previous counter}, which records the value the current counter +had last time it was incremented or set. Note that incrementing the +current counter by zero, e.g., with @w{@kbd{C-u 0 C-x C-k C-i}}, also +records the value of the current counter as the previous counter +value. @table @kbd @item @key{F3} @@ -270,8 +277,8 @@ value of the keyboard macro's counter into the buffer, and increments the counter by 1. (If you are not defining a macro, @key{F3} begins a macro definition instead. @xref{Basic Keyboard Macro}.) You can use a numeric prefix argument to specify a different increment. If you -just specify a @kbd{C-u} prefix, that is the same as an increment of -zero: it inserts the current counter value without changing it. +just specify a @kbd{C-u} prefix, that inserts the previous counter +value, and doesn't change the current value. As an example, let us show how the keyboard macro counter can be used to build a numbered list. Consider the following key sequence: diff --git a/lisp/kmacro.el b/lisp/kmacro.el index f9d00a5603f..72d7091df17 100644 --- a/lisp/kmacro.el +++ b/lisp/kmacro.el @@ -263,7 +263,10 @@ Can be set directly via `kmacro-set-format', which see.") (defun kmacro-insert-counter (arg) "Insert current value of `kmacro-counter', then increment it by ARG. Interactively, ARG defaults to 1. With \\[universal-argument], insert -current value of `kmacro-counter', but do not increment it." +the previous value of `kmacro-counter', and do not increment the +current value. +The previous value of the counter is the one it had before +the last increment." (interactive "P") (if kmacro-initial-counter-value (setq kmacro-counter kmacro-initial-counter-value @@ -692,9 +695,10 @@ the current value of `kmacro-counter'). When used during defining/executing a macro, inserts the current value of `kmacro-counter' and increments the counter value by ARG (or by 1 if no -prefix argument). With just \\[universal-argument], inserts the current value -of `kmacro-counter', but does not modify the counter; this is the -same as incrementing the counter by zero. +prefix argument). With just \\[universal-argument], inserts the previous +value of `kmacro-counter', and does not modify the counter; this is +different from incrementing the counter by zero. (The previous value +of the counter is the one it had before the last increment.) The macro counter can be set directly via \\[kmacro-set-counter] and \\[kmacro-add-counter]. The format of the inserted value of the counter can be controlled -- 2.39.5