Emacs manual desribes keyboard macros in the wrong section.

Emacs manual desribes keyboard macros in the wrong section.

[Kim F. Storm]

The keyboard macro feature is currently described under customizations
(in custom.texi), but IMO keyboard macros are not customizations
(unless you name them etc. which I believe is not the typical use of
keyboard macros).  In my experience, the typical use of keyboard
macros is for doing repeated editing similar to "search and replace".

Therefore, I suggest moving the section on keyboard macro feature into
a separate chapter after the three chapters: "Searching and
Replacement", "Replacement Commands", and "Commands for Fixing Typos",
as yet another (generic and powerful) way of doing "mass editing".

I'm currently working on documenting the enhanced kmacro commands
(ready in 1-2 weeks), and the text will grow quite a lot compared to
the current text.  This could also indicate that a separate chapter
on the topic would be better.

WDYT?

Re: Emacs manual desribes keyboard macros in the wrong section.

[Luc Teirlinck]

Kim Storm wrote:

   The keyboard macro feature is currently described under customizations
   (in custom.texi), but IMO keyboard macros are not customizations
   (unless you name them etc. which I believe is not the typical use of
   keyboard macros).  In my experience, the typical use of keyboard
   macros is for doing repeated editing similar to "search and replace".

In my opinion it would certainly be appropriate to give keyboard
macros their own chapter once their discussion has reached an
appropriate size.  They are important enough to motivate that.
However, I do not believe that the above is an accurate statement.  It
describes your typical use of keyboard macros.  Actually, it also
describes my own typical use and probably that of most people who know
Elisp.  However, most Emacs users are not Elisp programmers.  For
somebody who does not know Elisp, keyboard macros are an important
customization and extension tool.  Keyboard macros used as such tend
to get named and saved in .emacs.  (All of this is irrelevant to the
separate chapter issue, but it could potentially be relevant to other
issues related to keyboard macros.)

Sincerely,

Luc.

Re: Emacs manual desribes keyboard macros in the wrong section.

[Kim F. Storm]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> Kim Storm wrote:
> 
>    The keyboard macro feature is currently described under customizations
>    (in custom.texi), but IMO keyboard macros are not customizations
>    (unless you name them etc. which I believe is not the typical use of
>    keyboard macros).  In my experience, the typical use of keyboard
>    macros is for doing repeated editing similar to "search and replace".
> 
> In my opinion it would certainly be appropriate to give keyboard
> macros their own chapter once their discussion has reached an
> appropriate size.  They are important enough to motivate that.

> ... most Emacs users are not Elisp programmers.  For
> somebody who does not know Elisp, keyboard macros are an important
> customization and extension tool.  

I agree, and moving it out of the customization chapter which talks
about variables and other "lisp-like" stuff will probably make more
non-Elisp programmers aware of it.

>                                    Keyboard macros used as such tend
> to get named and saved in .emacs. 

I could still add directions to the section on .emacs to describe how
one can save keyboard macros in .emacs (either as named commands or
as key bindings).

Re: Emacs manual desribes keyboard macros in the wrong section.

[Richard Stallman]

    I'm currently working on documenting the enhanced kmacro commands
    (ready in 1-2 weeks), and the text will grow quite a lot compared to
    the current text.  This could also indicate that a separate chapter
    on the topic would be better.

If it gets a lot bigger, we might want to put that in a separate
manual, rather than print it in the Emacs manual.

Re: Emacs manual desribes keyboard macros in the wrong section.

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

>     I'm currently working on documenting the enhanced kmacro commands
>     (ready in 1-2 weeks), and the text will grow quite a lot compared to
>     the current text.  This could also indicate that a separate chapter
>     on the topic would be better.
> 
> If it gets a lot bigger, we might want to put that in a separate
> manual, rather than print it in the Emacs manual.

Are you suggesting that we do not mention keyboard macros in the Emacs manual;
that would be very bad IMO.

In any case, I do not expect that the text is going to be so big that
it doesn't fit in the Emacs manual; maybe about the size of the search
and replace chapter.

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

Re: Emacs manual desribes keyboard macros in the wrong section.

[Robert J. Chassell]

   >     I'm currently working on documenting the enhanced kmacro commands
   >     (ready in 1-2 weeks), ...

On a related issue:

A decade or more ago, Emacs possessed a command that would convert a
keyboard macro to an Emacs Lisp program starting with `defun'.  Does
this program still exist?  If so what is it called?  I cannot find it.

Here is what I mean.  As the manual says,

       C-x ( C-a C-<SPC> C-n M-w C-x b f o o <RET> C-y C-x b <RET> C-x )

    defines a macro that copies the current line into the buffer
    `foo', then returns to the original buffer.

The old function, which may have been part of an early version of
Emacs Calc, would have produced a `defun' like this
(the optional doc string was in the wrong place):

    (defun sample-kmacro () ""
      (interactive)
      (beginning-of-line)
      (set-mark-command)
      (next-line)
      (kill-ring-save)
      (switch-to-buffer "foo")
      (yank)
      (switch-to-buffer (other-buffer)))
                                        
Does the old function still exist?  I would like to see it.

I cannot find the old function, and have always thought it interesting
as well as useful both in practice and as a teaching tool.

Currently, `insert-kbd-macro' produces this:

  (fset 'sample-kmacro
     [?\C-a ?\C-  ?\C-n ?\M-w ?\C-x ?b ?f ?o ?o return ?\C-y ?\C-x ?b return])

Also, the `Keyboard Macro Editor' in the current distribution, in
`....emacs/lisp/edmacro.el', produces this when you type `C-x C-k RET'
(kmacro-edit-macro):

    ;; Keyboard Macro Editor.  Press C-c C-c to finish;
    ;; Press C-x k RET to cancel.
    ;; Original keys: C-a C-SPC C-n M-w C-x b foo RET C-y C-x b RET

    Command: last-kbd-macro
    Key: none

    Macro:

    C-a                 ;; beginning-of-line
    C-SPC               ;; set-mark-command
    C-n                 ;; next-line
    M-w                 ;; kill-ring-save
    C-x b               ;; switch-to-buffer
    foo                 ;; self-insert-command * 3
    RET                 ;; newline
    C-y                 ;; yank
    C-x b               ;; switch-to-buffer
    RET                 ;; newline

As is, the current `insert-kbd-macro' and `kmacro-edit-macro' are
fine; but they are not as helpful as a program that converts
keystrokes to a `defun'.

--
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                             bob@rattlesnake.com

Re: Emacs manual desribes keyboard macros in the wrong section.

[Richard Stallman]

    In any case, I do not expect that the text is going to be so big that
    it doesn't fit in the Emacs manual;

The word "fit" suggests an inappropriate model of what the issue is.
The issue is that the Emacs manual is already too big.  Adding pages
to it is a problem.  Adding a little material is ok; adding a lot
is not.