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

[Eli Zaretskii <eliz@gnu.org>]

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