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

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

[Allen Li]

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).

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.

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

[Eli Zaretskii]

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

Thanks.

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.

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

[Eli Zaretskii]

> From: Allen Li <darkfeline@felesatra.moe>
> Date: Thu, 31 Jan 2019 13:41:41 -0800
> Cc: 34263@debbugs.gnu.org
> 
> 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.

How do you suggest to define "previous" to avoid the confusion?  That
was the reason for bug#31243.  We must add to the documentation the
definition of "previous" that would be clear and unequivocal.

Thanks.

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

[Eli Zaretskii]

> Date: Fri, 01 Feb 2019 12:00:09 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: 34263@debbugs.gnu.org
> 
> How do you suggest to define "previous" to avoid the confusion?  That
> was the reason for bug#31243.  We must add to the documentation the
> definition of "previous" that would be clear and unequivocal.

Never mind, I think I found a good way of explaining what is the
"previous" counter value, and fixed the docs accordingly.  Take a look
at the emacs-26 branch.

Thanks.