kmacro?

[Drew Adams]

Wanting to remind myself about some stuff about keyboard macros, I looked
for such info in the Emacs manual and the Elisp manual.

I came across kmacro in the Emacs manual, but not in the Elisp manual (with
the exception of a passing mention of `kmacro-start-macro'). Perhaps the
latter is normal; I don't know, but I might have expected at least a mention
of `kmacro-ring'.

It looks as if there is in progress a switch to kmacro.el from macros.el,
but it is not yet complete. In the Emacs manual (and in Emacs), `C-x (' is
no longer `start-kbd-macro', but it is now `kmacro-start-macro', and so on.
But in the Elisp manual, the "old" start and end commands are mentioned, as
well as `kmacro-start-macro', but `kmacro-end-macro' is not even mentioned.
Offhand, it looks as though the Elisp manual was not completely updated when
things were switched in favor of kmacro.

On the other hand, though the Emacs manual privileges kmacro over macros.el
and the built-in commands (e.g. `start-kbd-macro'), the Commentary of
kmacro.el says that it is "an alternative user interface to emacs' keyboard
macro functionality". The Commentary also seems ambiguous wrt the key
bindings `C-x (' etc., saying that these are not so useful, and saying that
"the following key bindings" are made by kmacros.el, with no mention of `C-x
(' etc.

So, I guess I'm a bit confused. Is kmacro an alternative or is it the new
standard, conventional way to do things? Alternative libraries don't usually
define the default set of bindings, and they are not usually presented in
the Emacs manual as the main or the only way to do things.

The doc strings for commands such as `name-last-kbd-macro' and
`kmacro-name-last-macro' do not make clear what the differences or relative
advantages are. A user finding these commands via `apropos' will in fact
find that their doc strings are _identical_. That's not very helpful. The
code for these functions is essentially the same also. In that case, why
wasn't an alias created? That would at least make clear that the two are
essentially the same.

Kmacro is apparently new for Emacs 22. The NEWS item introducing it doesn't
say clearly whether it is meant to replace what has existed before, but it
does mention the key-binding changes.

I think kmacro needs a better presentation in the doc, with some explanation
of the relation to the formerly standard way of doing things (macros.el and
the built-ins). If kmacro is meant to replace macros.el and the built-in
commands, then that should be done completely. If it is meant to be only an
alternative, then it shouldn't take over the bindings used up till now for
built-in commands such as `start-kbd-macro'. If macros.el is meant not to be
replaced but to be kept as an alternative to a new standard, kmacros, then
that should be made clear. For now, it seems as if Emacs is "entre deux
chaises" between the two approaches.

In sum, the doc should be improved to make clear what the relationship is
between a) the built-in commands such as `start-kbd-macro' and the macros.el
stuff, on the one hand, and b) the kmacros.el stuff, on the other hand.