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

[Drew Adams]

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@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'