bug#31243: 26.1; kmacro-insert-counter increments incorrectly

[Allen Li <darkfeline@felesatra.moe>]

On Sun, Apr 22, 2018 at 9:56 PM, Phil Sainty <psainty@orcon.net.nz> wrote:
> Not a bug?  I believe your expectations are incorrect.
>
>> C-u <f3> ;; kmacro-start-macro-or-insert-counter
>
>
> This insert the *previous* macro counter.  Which is sort of "undefined" for
> the first iteration, but zero in practice.

Ah, I see.  I guess what I'm looking for is C-u 0 <f3> (or
alternatively C-u <f3> the second time rather than the first time).

I don't think the documentaton is very clear, because the meaning of
"previous" is ambiguous:

With C-u, inserts previous ‘kmacro-counter’ (but do not modify counter).

I interpreted this to mean "Insert the counter that was
used last time" (which is redundant since there's only one counter),
rather than "Insert the value of the counter before the last time the
counter was changed".  The fact that the previous value of the counter
is saved is mentioned nowhere except implicitly implied by this single
word in the documentation.

I think the The Keyboard Macro Counter page should have a standalone
paragraph explaining this, such as:

Whenever the value of `kmacro-counter' is modified (by
`kmacro-insert-counter', `kmacro-set-counter' or
`kmacro-add-counter'), the previous value of the counter is saved in
`kmacro-last-counter'.  This value can be inserted by C-u <f3> or C-u
C-x C-k C-i.

And a similar addendum in the docstrings.

>
> => 0
>
>> <f3> ;; kmacro-start-macro-or-insert-counter
>
>
> Insert the current macro counter (which is also zero, because inserting the
> previous counter does not touch the current counter).
>
> => 0
>
> Then the counter is incremented -- so the current counter is set to 1, and
> the previous counter is set to 0.
>
> Hence when you trigger the next iteration, you insert 0 and 1; etc...
>
>