GNU bug report logs - #34263
26.1; documentation for kmacro-insert-counter C-u is wrong

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 34263 in the body.
You can then email your comments to 34263 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Allen Li <darkfeline <at> felesatra.moe>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.1; documentation for kmacro-insert-counter C-u is wrong
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).

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.

Message #8 received at 34263 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Allen Li <darkfeline <at> felesatra.moe>
Cc: 34263 <at> debbugs.gnu.org
Subject: Re: bug#34263: 26.1;
 documentation for kmacro-insert-counter C-u is wrong
Date: Thu, 31 Jan 2019 17:21:13 +0200

> From: Allen Li <darkfeline <at> 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.

Message #11 received at 34263 <at> debbugs.gnu.org (full text, mbox):

From: Allen Li <darkfeline <at> felesatra.moe>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 34263 <at> debbugs.gnu.org
Subject: Re: bug#34263: 26.1;
 documentation for kmacro-insert-counter C-u is wrong
Date: Thu, 31 Jan 2019 13:41:41 -0800

On Thu, Jan 31, 2019 at 7:21 AM Eli Zaretskii <eliz <at> gnu.org> wrote:
>
> > From: Allen Li <darkfeline <at> 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.

Message #14 received at 34263 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Allen Li <darkfeline <at> felesatra.moe>
Cc: 34263 <at> debbugs.gnu.org
Subject: Re: bug#34263: 26.1;
 documentation for kmacro-insert-counter C-u is wrong
Date: Fri, 01 Feb 2019 12:00:09 +0200

> From: Allen Li <darkfeline <at> felesatra.moe>
> Date: Thu, 31 Jan 2019 13:41:41 -0800
> Cc: 34263 <at> debbugs.gnu.org
> 
> On Thu, Jan 31, 2019 at 7:21 AM Eli Zaretskii <eliz <at> gnu.org> wrote:
> >
> > > From: Allen Li <darkfeline <at> 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.

Message #19 received at 34263-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: darkfeline <at> felesatra.moe
Cc: 34263-done <at> debbugs.gnu.org
Subject: Re: bug#34263: 26.1;
 documentation for kmacro-insert-counter C-u is wrong
Date: Fri, 01 Feb 2019 17:36:48 +0200

> Date: Fri, 01 Feb 2019 12:00:09 +0200
> From: Eli Zaretskii <eliz <at> gnu.org>
> Cc: 34263 <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.