man/kmacro.texi

[Luc Teirlinck]

Apart from the issues I took care of with my patch, I have the
following remarks and questions about man/kmacro.texi:

>From `(emacs)Basic Keyboard Macro':

       Alternatively, you can use `C-x C-k C-s' to start a keyboard macro,
    and `C-x C-k C-k...' to end and execute it.

`end _and_ execute' makes it sound like the macro will be executed
twice, like with `C-x ( C-x e'.  This is apparently not the case.
No advantage to using this alternate method is given.  Is it even
worth mentioning?  (If yes, it should be reformulated.)

>From `(emacs)Basic Keyboard Macro':

       The command `C-x C-k r' (`apply-macro-to-region-lines') repeats the
    last defined keyboard macro on each complete line within the current
    region.  It does this line by line, by moving point to the beginning
    of the line and then executing the macro.

What is a complete line?  I would say, a line terminated by a newline
_or_ the end of the buffer.  For `apply-macro-to-region-lines' it
means "terminated by a newline" with no "or".  This is ambiguous and
should be mentioned _if_ this is intended.  But _is_ it intentional?
For instance, after marking the entire buffer with `C-x h',
`apply-macro-to-region-lines' will apply the last keyboard macro to
all lines in the buffer, except the last line, if the buffer does not
end in a newline.

The entire section `(emacs)Keyboard Macro Counter' is difficult to
read.  I am pretty sure that it must be very useful for _something_,
but it is not obvious what that is.  Note that this is part of the
_Emacs_ manual, which is supposed to be understandable by beginners.
Maybe the entire section could be moved to emacs-xtra or a similar
place.  Then it could actually be expanded and an example of use could
be given.  That node could be referenced from the Emacs manual with an
@inforef.

I would _guess_ that `kmacro-insert-counter' and `kmacro-add-counter'
only make sense during execution of a macro, but it would be better if
this were clarified.  If the material got moved to emacs-xtra or such,
one would also have enough room to mention `C-u C-x C-k C-a'.
Currently it seems like this would add 4, which is not the case.

       The command `C-x C-k C-f' (`kmacro-set-format') prompts for the
    format to use when inserting the macro counter.  The default format is
    `%d'.  If you set the counter format before you define a macro, that
    format is restored before each repetition of the macro.  Consequently,
    any changes you make to the macro counter format while defining a
    macro are only active for the rest of the macro.

This seems to assume that every reader of the Emacs manual is familiar
with `format' and knows the alternatives to "%d".  If this were
emacs-xtra or such, there would be place enough to mention the
alternatives that are potentially useful in this context, as well as
give references. 

It is not clear what happens if we do _not_ set the format _before_
defining the macro and set it while defining the macro.  Does the
default %d get restored before repetition or not?

As a last remark, this chapter seems to come rather early in the Emacs
manual.  Section `(emacs)Save Keyboard Macro' seems to assume a
non-trivial level of knowledge about key bindings, like the difference
between local and global bindings, whereas the reader may not have any
knowledge at all about binding keys at that stage.  The material in
`(emacs)Save Keyboard Macro', like the entire chapter, originally
occurred a lot later in the manual.

Sincerely,

Luc.