Re: Incorporate package macrostep into Emacs core

[Eli Zaretskii <eliz@gnu.org>]

> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: monnier@iro.umontreal.ca,  emacs-devel@gnu.org
> Date: Thu, 18 Apr 2024 22:19:36 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Jeremy Bryant <jb@jeremybryant.net>
> >> Cc: monnier@iro.umontreal.ca,  emacs-devel@gnu.org,  j.j.oddie@gmail.com,
> >>   stefan@marxist.se,  stefankangas@gmail.com,  jonas@bernoul.li
> >> Date: Sun, 17 Mar 2024 21:48:08 +0000
> >> 
> >> Manual?
> >> Should the documentation for macrostep be included in the Emacs Lisp
> >> manual section Macros?
> >
> > Yes, I think so.
> >
> 
> Please find attached a patch for the manual.
> Any comments welcome.

Thanks, see below.

> * doc/lispref/macros.texi (Macros):
> Describe macrostep's usage to explore and write macros.

This is filled sub-optimally; please use change-log-mode to help you
fill better.

> This is based on Jonathan's Oddie's documentation in the macrostep package

Likewise here: this line is too long.

> -* Simple Macro::            A basic example.
> -* Expansion::               How, when and why macros are expanded.
> -* Compiling Macros::        How macros are expanded by the compiler.
> -* Defining Macros::         How to write a macro definition.
> -* Problems with Macros::    Don't evaluate the macro arguments too many times.
> +* Simple Macro::                A basic example.
> +* Expansion::                   How, when and why macros are expanded.
> +* Compiling Macros::            How macros are expanded by the compiler.
> +* Defining Macros::             How to write a macro definition.
> +* Problems with Macros::        Don't evaluate the macro arguments too many times.
>                                Don't hide the user's variables.
> -* Indenting Macros::        Specifying how to indent macro calls.
> +* Indenting Macros::            Specifying how to indent macro calls.
> +* macrostep: interactive macro-expander::

I'd prefer not to change whitespace here.  I see no reason for it in
this case.

Also, any change in the menus requires a corresponding change in
elisp.texi, where we have the @detailmenu.

>  @menu
> -* Wrong Time::             Do the work in the expansion, not in the macro.
> -* Argument Evaluation::    The expansion should evaluate each macro arg once.
> -* Surprising Local Vars::  Local variable bindings in the expansion
> +* Wrong Time::                  Do the work in the expansion, not in the macro.
> +* Argument Evaluation::         The expansion should evaluate each macro arg once.
> +* Surprising Local Vars::       Local variable bindings in the expansion
>                                require special care.
> -* Eval During Expansion::  Don't evaluate them; put them in the expansion.
> -* Repeated Expansion::     Avoid depending on how many times expansion is done.
> +* Eval During Expansion::       Don't evaluate them; put them in the expansion.
> +* Repeated Expansion::          Avoid depending on how many times expansion is done.

Unnecessary whitespace changes again.

> +@node macrostep: interactive macro-expander
> +@section macrostep: interactive macro-expander
> +
> +You can use the package @code{macrostep} to explore macro definitions, and
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
"You can use the @code{macrostep} package" is better.

Alternatively, say "@code{macrostep-mode}" instead; no need to mention
that it's a package.

> +help write new macros, using @kbd{M-x macrostep-expand}.
> +
> +@ifnottex

This @ifnottex makes this section very small in the printed manual,
which I think is undesirable.  Instead, I'd move the sentence above to
the parent chapter, and have the entire section be inside @ifnottex
(also in menus).

> +@kbd{macrostep} is an Emacs minor mode for interactively stepping

There's no point of having "Emacs" there, since this manual is about
Emacs Lisp.

> +through the expansion of macros in Emacs Lisp source code.  It lets you
> +see exactly what happens at each step of the expansion process by
> +pretty-printing the expanded forms inline in the source buffer, which is
> +temporarily read-only while macro expansions are visible.  You can
> +expand and collapse macro forms one step at a time, and evaluate or
> +instrument the expansions for debugging with Edebug as normal.
                                                       ^^^^^^^^^
"as usual"

> +The standard keybindings in @code{macrostep-mode} are the following:
> +
> +@itemize @minus
> +@item
> +e, =, RET : expand the macro form following point one step

This will produce sub-optimal markup.  I suggest to use "@table @kbd"
instead.

Also, our style is to mention the command bound to the keys in
parentheses, and also index each such command.

> +It's not very useful to enable and disable macrostep-mode directly.
> +Instead, bind `macrostep-expand' to a key in `emacs-lisp-mode-map',
                 ^^^^^^^^^^^^^^^^^^             ^^^^^^^^^^^^^^^^^^^^^
These two should be in @code instead of in quotes `like this'.

> +by typing @kbd{C-c e e e}@dots as many times as necessary.

@dots{} (not "@dots") should be inside @kbd.

And finally, two more questions:

  . should this be in the user manual instead? it sounds like a
    user-level feature, not Lisp programming level feature
  . how is this mode different from "C-x C-k SPC", which is already
    described in the user manual as a similar feature?