bug#34263: 26.1; documentation for kmacro-insert-counter C-u is wrong

[Allen Li]

On Thu, Jan 31, 2019 at 7:21 AM Eli Zaretskii <eliz@gnu.org> wrote:
>
> > From: Allen Li <darkfeline@felesatra.moe>
> > Date: Thu, 31 Jan 2019 09:54:28 +0000
> >
> > The documentation for the behavior of C-u argument to
> > kmacro-insert-counter is wrong everywhere (both in the docstring and
> > manual, and also for kmacro-start-macro-or-insert-counter).
>
> Isn't this the same issue as the one you raised in bug#31243?  Which
> is already solved in the Git repository for Emacs 26.2?
>
> > It says that supplying C-u is the same as supplying C-u 0.  This is
> > completely wrong, and has caused confusion for multiple users (I can
> > dig up some links if desired).  C-u 0 inserts the current value of the
> > kmacro counter without incrementing it.  C-u inserts the *previous*
> > value of the kmacro counter, which is usually one less than the
> > current value.
>
> Please look at the documentation on the emacs-26 branch and tell what
> exactly is wrong/unclear/confusing there.

On both the master branch and emacs-26:

    (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."

This is still wrong, C-u inserts the *previous* value of kmacro-counter.

    (defun kmacro-start-macro-or-insert-counter (arg)
      "Record subsequent keyboard input, defining a keyboard macro.
    The commands are recorded even as they are executed.

    Initializes the macro's `kmacro-counter' to ARG (or 0 if no prefix arg)
    before defining the macro.

    With \\[universal-argument], appends to current keyboard macro (keeping
    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.

This is still wrong. C-u is NOT the same as incrementing the counter
by zero.  C-u 0 inserts the *current* value of the counter, C-u inserts
the *previous* value of the counter.

    @findex kmacro-insert-counter
    @kindex C-x C-k C-i
      When you are defining a keyboard macro, the command @key{F3}
    (@code{kmacro-start-macro-or-insert-counter}) inserts the current
    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.

This is still wrong. C-u is NOT the same as incrementing the counter
by zero.  C-u 0 inserts the *current* value of the counter, C-u inserts
the *previous* value of the counter.

>
> Thanks.