man/kmacro.texi

man/kmacro.texi

[Luc Teirlinck]

I recommend the following changes to kmacro.texi:

===File ~/kmacro-diff=======================================
*** kmacro.texi	13 Aug 2004 16:24:17 -0500	1.4
--- kmacro.texi	16 Aug 2004 21:43:00 -0500	
***************
*** 1,5 ****
  @c This is part of the Emacs manual.
! @c Copyright (C) 1985,86,87,93,94,95,97,2000,2001,2002,2003
  @c  Free Software Foundation, Inc.
  @c See file emacs.texi for copying conditions.
  @node Keyboard Macros, Files, Fixit, Top
--- 1,5 ----
  @c This is part of the Emacs manual.
! @c Copyright (C) 1985,86,87,93,94,95,97,2000,2001,2002,2003,2004
  @c  Free Software Foundation, Inc.
  @c See file emacs.texi for copying conditions.
  @node Keyboard Macros, Files, Fixit, Top
***************
*** 220,225 ****
--- 220,229 ----
  desired macro is at the head of the ring.  To execute the new macro
  ring head immediately, just type @kbd{C-k}.
  
+   Note that Emacs treats the head of the macro ring as the ``last
+ defined keyboard macro''.  For instance, it is the keyboard macro that
+ @kbd{C-x e} will execute.
+ 
  @findex kmacro-view-macro-repeat
  @kindex C-x C-k C-v
  
***************
*** 264,271 ****
  macro counter is initialized to 0 when you start defining the macro,
  and incremented by 1 after each insertion of the counter value;
  that is, if you insert the macro counter twice while defining the
! macro, it will be incremented by 2 time for each repetition of the
! macro.
  
  @findex kmacro-insert-counter
  @kindex C-x C-k C-i
--- 268,274 ----
  macro counter is initialized to 0 when you start defining the macro,
  and incremented by 1 after each insertion of the counter value;
  that is, if you insert the macro counter twice while defining the
! macro, it will be incremented by 2 on each repetition of the macro.
  
  @findex kmacro-insert-counter
  @kindex C-x C-k C-i
***************
*** 362,378 ****
  @kindex C-x C-k n
    If you wish to save a keyboard macro for later use, you can give it
  a name using @kbd{C-x C-k n} (@code{name-last-kbd-macro}).
! This reads a name as an argument using the minibuffer and defines that name
! to execute the macro.  The macro name is a Lisp symbol, and defining it in
! this way makes it a valid command name for calling with @kbd{M-x} or for
! binding a key to with @code{global-set-key} (@pxref{Keymaps}).  If you
! specify a name that has a prior definition other than another keyboard
! macro, an error message is shown and nothing is changed.
  
  @cindex binding keyboard macros
  @findex kmacro-bind-to-key
  @kindex C-x C-k b
!   Rather than giving a keyboard macro a name, you can bind it to a
  key using @kbd{C-x C-k b} (@code{kmacro-bind-to-key}) followed by the
  key sequence you want the keyboard macro to be bound to.  You can
  bind to any key sequence in the global keymap, but since most key
--- 365,384 ----
  @kindex C-x C-k n
    If you wish to save a keyboard macro for later use, you can give it
  a name using @kbd{C-x C-k n} (@code{name-last-kbd-macro}).
! This reads a name as an argument using the minibuffer and defines that
! name to execute the last keyboard macro, in its current form.  (If you
! later add to the definition of the last keyboard macro, then this will
! not affect the macro stored in the name.)  The macro name is a Lisp
! symbol, and defining it in this way makes it a valid command name for
! calling with @kbd{M-x} or for binding a key to with
! @code{global-set-key} (@pxref{Keymaps}).  If you specify a name that
! has a prior definition other than another keyboard macro, an error
! message is shown and nothing is changed.
  
  @cindex binding keyboard macros
  @findex kmacro-bind-to-key
  @kindex C-x C-k b
!   Rather than giving the last keyboard macro a name, you can bind it to a
  key using @kbd{C-x C-k b} (@code{kmacro-bind-to-key}) followed by the
  key sequence you want the keyboard macro to be bound to.  You can
  bind to any key sequence in the global keymap, but since most key
***************
*** 414,425 ****
  macro will be defined each time you run Emacs.
  
    If you give @code{insert-kbd-macro} a numeric argument, it makes
! additional Lisp code to record the keys (if any) that you have bound to the
! keyboard macro, so that the macro will be reassigned the same keys when you
! load the file.
  
  @node Edit Keyboard Macro
! @section Interactively executing and editing a keyboard macro
  
  @findex kmacro-edit-macro
  @kindex C-x C-k C-e
--- 420,431 ----
  macro will be defined each time you run Emacs.
  
    If you give @code{insert-kbd-macro} a numeric argument, it makes
! additional Lisp code to record the keys (if any) that you have bound
! to @var{macroname}, so that the macro will be reassigned the same keys
! when you load the file.
  
  @node Edit Keyboard Macro
! @section Editing a keyboard macro
  
  @findex kmacro-edit-macro
  @kindex C-x C-k C-e
============================================================

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.

Re: man/kmacro.texi

[Richard Stallman]

      that is, if you insert the macro counter twice while defining the
    ! macro, it will be incremented by 2 on each repetition of the macro.

Can you rewrite that in active voice?

    ! name to execute the last keyboard macro, in its current form.  (If you
    ! later add to the definition of the last keyboard macro, then this will
    ! not affect the macro stored in the name.)

Better is

    ! name to execute the last keyboard macro, in its current form.  (If you
    ! later add to the definition of this macro, that does not alter
    ! the name's definition as a macro.)

    ! @code{global-set-key} (@pxref{Keymaps}).  If you specify a name that
    ! has a prior definition other than another keyboard macro, an error
    ! message is shown and nothing is changed.

"other than a keyboard macro"

    !   Rather than giving the last keyboard macro a name, you can bind it to a
      key using @kbd{C-x C-k b} (@code{kmacro-bind-to-key}) followed by the

Make that

    !   You can also bind the last keyboard macro to a
      key, using @kbd{C-x C-k b} (@code{kmacro-bind-to-key}) followed by the


      @node Edit Keyboard Macro
    ! @section Editing a keyboard macro

It was good to notice this was too long, and shorten it.  The file has
other long section titles that need shortening and/or changing.  For
instance, "Where previous keyboard macros are saved" should be "The
Keyboard Macro Ring".  Can you try cleaning them all up?

This and other section titles in kmacro.texi need to be capitalized
like other section titles in the Emacs manual.

Re: man/kmacro.texi

[Richard Stallman]

    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?

It must be intentional, but whether the person realized it was
different from the usual Emacs behavior is a separate question.
In any case, it seems to me that being compatible with the usual
Emacs handling of repeating for each line would be an improvement.
Would you like to change the code, and remove the word "complete"
in the manual here?

    The entire section `(emacs)Keyboard Macro Counter' is difficult to
    read.

Would you like to try to rewrite it?

    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.

The purpose is for numbering items in a table.
For instance, you could write a macro to turn

* Hello
* Thank you
* You're welcome
* Goodbye

into 

1. Hello
2. Thank you
3. You're welcome
4. Goodbye

    I would _guess_ that `kmacro-insert-counter' and `kmacro-add-counter'
    only make sense during execution of a macro...

Yes, of course.

    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.

Keyboard macros used to be documented inside Customization.
I think this chapter should be moved back there.
Also, moving some parts of it to emacs-xtra is a good idea.

Re: man/kmacro.texi

[Luc Teirlinck]

Richard Stallman wrote:
       
       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?

   It must be intentional, but whether the person realized it was
   different from the usual Emacs behavior is a separate question.
   In any case, it seems to me that being compatible with the usual
   Emacs handling of repeating for each line would be an improvement.
   Would you like to change the code, and remove the word "complete"
   in the manual here?

Do you mean that the macro should be executed for every line
containing at least one character in the region?  That would actually be
bigger departure from the current behavior than what I was proposing.
I was just saying that if you do, say `C-x h' in a buffer that does
not end in a newline, then the last line _is_ completely contained in the
region, even though it does not end in a newline, and hence
`apply-macro-to-region-lines' should operate on it.  (It does not.)

Sincerely,

Luc.

Re: man/kmacro.texi

[Luc Teirlinck]

Richard Stallman wrote:

	 @node Edit Keyboard Macro
       ! @section Editing a keyboard macro

   It was good to notice this was too long, and shorten it.  The file has
   other long section titles that need shortening and/or changing.  For
   instance, "Where previous keyboard macros are saved" should be "The
   Keyboard Macro Ring".  Can you try cleaning them all up?

   This and other section titles in kmacro.texi need to be capitalized
   like other section titles in the Emacs manual.

I already changed the two section titles discussed above.  I believe
that after that, the two title changes in the patch below should be
sufficient.  The changes make the section titles not only shorter, but
also closer to the node title.  This is useful, since most of the time
people only specify the first argument to @xref and friends, which can
lead to confusing results in hardcopy if section title and node title
are completely unrelated.  I will check whether any third arguments to
@xref and friends need to be changed.

===File ~/kmacro-diff-2=====================================
*** kmacro.texi	21 Aug 2004 20:55:02 -0500	1.5
--- kmacro.texi	21 Aug 2004 23:12:29 -0500	
***************
*** 261,267 ****
  executes the previous (rather than the head) element on the macro ring.
  
  @node Keyboard Macro Counter
! @section Inserting incrementing numbers in macros
  
    Each keyboard macro has an associated counter which is automatically
  incremented on every repetition of the keyboard macro.  Normally, the
--- 261,267 ----
  executes the previous (rather than the head) element on the macro ring.
  
  @node Keyboard Macro Counter
! @section The Keyboard Macro Counter
  
    Each keyboard macro has an associated counter which is automatically
  incremented on every repetition of the keyboard macro.  Normally, the
***************
*** 449,455 ****
  @kbd{C-x C-k l} (@code{kmacro-edit-lossage}).
  
  @node Keyboard Macro Step-Edit
! @section Interactively executing and editing a keyboard macro
  
  @findex kmacro-step-edit-macro
  @kindex C-x C-k SPC
--- 449,455 ----
  @kbd{C-x C-k l} (@code{kmacro-edit-lossage}).
  
  @node Keyboard Macro Step-Edit
! @section Stepwise Editing a Keyboard Macro
  
  @findex kmacro-step-edit-macro
  @kindex C-x C-k SPC
============================================================

Re: man/kmacro.texi

[Richard Stallman]

    Do you mean that the macro should be executed for every line
    containing at least one character in the region?  That would actually be
    bigger departure from the current behavior than what I was proposing.

That seems reasonable to me.  What do you think is better, and why
is it better?

Re: man/kmacro.texi

[Luc Teirlinck]

Richard Stallman wrote:

       Do you mean that the macro should be executed for every line
       containing at least one character in the region?  That would actually be
       bigger departure from the current behavior than what I was proposing.

   That seems reasonable to me.  What do you think is better, and why
   is it better?

The following patch implements the "at least one char in the region"
rule, with, as usual, a newline between two lines counting as part of
the previous line.

What also looks somewhat unusual is that the mark stays active after
the command in Transient Mark mode.  Is this intentional?  It could
easily be undone with a call to `deactivate-mark' at the end.  If
desired, I can install the patch below, with or without a call to
`deactivate-mark' at the end.

===File ~/macros.el-diff====================================
*** macros.el	02 Sep 2003 07:34:40 -0500	1.41
--- macros.el	25 Aug 2004 19:20:22 -0500	
***************
*** 1,6 ****
  ;;; macros.el --- non-primitive commands for keyboard macros
  
! ;; Copyright (C) 1985, 86, 87, 92, 94, 95 Free Software Foundation, Inc.
  
  ;; Maintainer: FSF
  ;; Keywords: abbrev
--- 1,6 ----
  ;;; macros.el --- non-primitive commands for keyboard macros
  
! ;; Copyright (C) 1985, 86, 87, 92, 94, 95, 04 Free Software Foundation, Inc.
  
  ;; Maintainer: FSF
  ;; Keywords: abbrev
***************
*** 240,247 ****
  
  ;;;###autoload
  (defun apply-macro-to-region-lines (top bottom &optional macro)
!   "For each complete line between point and mark, move to the beginning
! of the line, and run the last keyboard macro.
  
  When called from lisp, this function takes two arguments TOP and
  BOTTOM, describing the current region.  TOP must be before BOTTOM.
--- 240,251 ----
  
  ;;;###autoload
  (defun apply-macro-to-region-lines (top bottom &optional macro)
!   "Apply last keyboard macro to all lines in the region.
! For each line containing at least one character in the region,
! move to the beginning of the line, and run the last keyboard
! macro.  Recall that a newline is part of the line that it ends.
! Thus, if the region ends at the beginning of a line, then that
! line is not included.
  
  When called from lisp, this function takes two arguments TOP and
  BOTTOM, describing the current region.  TOP must be before BOTTOM.
***************
*** 277,310 ****
      \\C-x )
  
  and then select the region of un-tablified names and use
! `\\[apply-macro-to-region-lines]' to build the table from the names.
! "
    (interactive "r")
    (or macro
        (progn
  	(if (null last-kbd-macro)
  	    (error "No keyboard macro has been defined"))
  	(setq macro last-kbd-macro)))
!   (save-excursion
!     (let ((end-marker (progn
! 			(goto-char bottom)
! 			(beginning-of-line)
! 			(point-marker)))
! 	  next-line-marker)
!       (goto-char top)
!       (if (not (bolp))
! 	  (forward-line 1))
!       (setq next-line-marker (point-marker))
!       (while (< next-line-marker end-marker)
! 	(goto-char next-line-marker)
! 	(save-excursion
! 	  (forward-line 1)
! 	  (set-marker next-line-marker (point)))
! 	(save-excursion
! 	  (let ((mark-active nil))
! 	    (execute-kbd-macro (or macro last-kbd-macro)))))
!       (set-marker end-marker nil)
!       (set-marker next-line-marker nil))))
  
  ;;;###autoload (define-key ctl-x-map "q" 'kbd-macro-query)
  
--- 281,312 ----
      \\C-x )
  
  and then select the region of un-tablified names and use
! `\\[apply-macro-to-region-lines]' to build the table from the names."
    (interactive "r")
    (or macro
        (progn
  	(if (null last-kbd-macro)
  	    (error "No keyboard macro has been defined"))
  	(setq macro last-kbd-macro)))
!   (when (< top bottom) 
!     (save-excursion
!       (let ((end-marker (progn
! 			  (goto-char bottom)
! 			  (point-marker)))
! 	    next-line-marker)
! 	(goto-char top)
! 	(forward-line 0)
! 	(setq next-line-marker (point-marker))
! 	(while (< next-line-marker end-marker)
! 	  (goto-char next-line-marker)
! 	  (save-excursion
! 	    (forward-line 1)
! 	    (set-marker next-line-marker (point)))
! 	  (save-excursion
! 	    (let ((mark-active nil))
! 	      (execute-kbd-macro (or macro last-kbd-macro)))))
! 	(set-marker end-marker nil)
! 	(set-marker next-line-marker nil)))))
  
  ;;;###autoload (define-key ctl-x-map "q" 'kbd-macro-query)
  
============================================================