GNU bug report logs - #15020
24.3.50; `kmacro-view-ring-2nd' wrong arg, confusion, more

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 15020 in the body.
You can then email your comments to 15020 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: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.3.50; `kmacro-view-ring-2nd' wrong arg, confusion, more
Date: Sat, 3 Aug 2013 20:21:02 -0700 (PDT)

1. This call in  `kmacro-view-ring-2nd' is wrong:

   (kmacro-display (car (car kmacro-ring)) "2nd macro")

   It seems to be missing argument TRUNC between the two args it has.

2. The `kmacro-view-ring-2nd' doc string is wrong when it refers to "the
   current head of".  It should say "the second macro in", just as do
   the doc strings of `kmacro-call-ring-2nd' and
   `kmacro-call-ring-2nd-repeat'.  The car of `kmacro-ring' is really
   the second ring item, not the head.

   The doc and commentary is a bit confused about this.  The doc string
   of `kmacro-ring-head' calls the head a "pseudo head".  Pick one
   coherent terminology and stick with it: either `last-kbd-macro', aka
   the "current" macro, is the first macro in the ring or it is not in
   the ring of macros at all.

   There is confusion between the concrete list used to represent part
   of the ring, and which holds the second and subsequent ring elements,
   and the abstract ring itself, which holds all of the ring elements,
   including the head element, `kmacro-ring-head'.

   Present something coherent to the user, including the reader of the
   code, comments, and doc strings.  Example: `kmacro-ring-max' refers
   not to the max length of the "macro ring", as it says, but to the max
   length of list `kmacro-ring'.  Example: `kmacro-pop-ring' does not
   pop the ring.  It pops the list `kmacro-ring', moving the second item
   of the ring to the head of the ring.  Contrast such terminology with
   that of `kmacro-ring-empty-p', which tests the abstract ring, not
   just the list `kmacro-ring'.

   There is plenty of confusion here, with "the ring" meaning sometimes
   the list `kmacro-ring' (an unfortunate name) and sometimes the
   abstract ring, whose first macro is `last-kbd-macro' and whose first
   element is `kmacro-ring-head'.

3. Please provide doc strings for these functions:

    kmacro-keyboard-quit
    kmacro-split-ring-element
    kmacro-get-repeat-prefix
    kmacro-execute-from-register
    kmacro-step-edit-prompt
    kmacro-step-edit-query
    kmacro-step-edit-insert
    kmacro-step-edit-pre-command
    kmacro-step-edit-minibuf-setup
    kmacro-step-edit-post-command

   Some of those have the longest code in the file.

4. Please document the undocumente parameters in these functions:

    kmacro-display-counter (uppercase)
    kmacro-add-counter (uppercase)
    kmacro-repeat-on-last-key (uppercase)
    kmacro-exec-ring-item - no ARG description
    kmacro-call-ring-2nd - no ARG description
    kmacro-call-ring-2nd-repeat - no ARG description
    kmacro-cycle-ring-next - no _ARG description (say it is unused & why
                             it is there at all)
    kmacro-cycle-ring-previous - no _ARG description (say...)
    kmacro-delete-ring-head - no _ARG description (say...)
    kmacro-end-macro (uppercase)
    kmacro-call-macro - no ARG, no NO-REPEAT, no END-MACRO
    kmacro-end-or-call-macro - no NO-REPEAT
    kmacro-end-or-call-macro-repeat - no ARG
    kmacro-end-and-call-macro - no NO-REPEAT
    kmacro-end-call-mouse - no EVENT
    kmacro-lambda-form - none of the parameters are documented:
                    MAC, COUNTER, or FORMAT
    kmacro-extract-lambda - no MAC
    kmacro-bind-to-key - no _ARG description (say...)
    kmacro-view-macro - no _ARG description (say...)
    kmacro-view-macro-repeat - no ARG
    kmacro-edit-macro-repeat - no ARG
    kmacro-edit-macro - no ARG (and put `kmacro-repeat' between `...')
    

In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2013-07-21 on ODIEONE
Bzr revision: 113485 lekktu <at> gmail.com-20130722012547-e3b7qxn1dba5vf20
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/binary --enable-checking=yes,glyphs
 CFLAGS=-O0 -g3 LDFLAGS=-Lc:/Devel/emacs/lib
 CPPFLAGS=-Ic:/Devel/emacs/include'

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 15020 <at> debbugs.gnu.org
Subject: Re: bug#15020: 24.3.50;
 `kmacro-view-ring-2nd' wrong arg, confusion, more
Date: Fri, 29 Apr 2016 15:23:51 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

> 1. This call in  `kmacro-view-ring-2nd' is wrong:
>
>    (kmacro-display (car (car kmacro-ring)) "2nd macro")
>
>    It seems to be missing argument TRUNC between the two args it has.

I've now pushed a fix.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 15020 <at> debbugs.gnu.org
Subject: Re: bug#15020: 24.3.50; `kmacro-view-ring-2nd' wrong arg,
 confusion, more
Date: Sun, 30 May 2021 08:10:57 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

> 2. The `kmacro-view-ring-2nd' doc string is wrong when it refers to "the
>    current head of".  It should say "the second macro in", just as do
>    the doc strings of `kmacro-call-ring-2nd' and
>    `kmacro-call-ring-2nd-repeat'.  The car of `kmacro-ring' is really
>    the second ring item, not the head.

Now fixed in Emacs 28.

> 3. Please provide doc strings for these functions:

[...]

> 4. Please document the undocumente parameters in these functions:

They seem to be internalish functions, so that doesn't seem
appropriate.  Closing.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

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