kmacro?

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.

Re: kmacro?

[Kim F. Storm]

"Drew Adams" <drew.adams@oracle.com> writes:

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

The Elisp manual describes the C-primitives (start-kbd-macro etc), and
the basic support functions defined in macro.el.

The Emacs manual decribes how the user uses keyboard macros for editing.
Whether that is based on the built-in commands, the commands in macro.el,
or commands in kmacro.el is a technical detail which I don't see can be
of much intest to the user.

In Emacs 22, keyboard macros are more advanced than previous Emacs releases,
since it includes -and uses- the new kmacro.el package.  The Emacs manual
correctly describes the new interface.

I don't really see the problem.

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

What part is missing?  Is there something which doesn't work as documented?

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

RE: kmacro?

[Drew Adams]

> I don't really see the problem.
>
> > 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.
>
> What part is missing?  Is there something which doesn't work as
> documented?

I think I was clear enough in my first message - see that for details.
Whether kmacro is an alternative to the convention or is the new convention
is not clear. I suggest clearing up the doc and the source-file Commentary a
bit. If you don't find the suggestion useful, ignore it, as always.

Re: kmacro?

[Kim F. Storm]

"Drew Adams" <drew.adams@oracle.com> writes:

>> What part is missing?  Is there something which doesn't work as
>> documented?
>
> I think I was clear enough in my first message - see that for details.

It was rather long....   (as usual).

> Whether kmacro is an alternative to the convention or is the new convention
> is not clear. I suggest clearing up the doc and the source-file Commentary a
> bit. If you don't find the suggestion useful, ignore it, as always.

Thank you for the summary ...  I have made some changes to clear things up.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk