Re: Incorporate package macrostep into Emacs core

[Eshel Yaron <me@eshelyaron.com>]

Hello Jeremy,

Jeremy Bryant <jb@jeremybryant.net> writes:

> ...attached is the revised patch I have worked on.

A few minor comments:

> From 0ed5971e7a54abe299386ce53e681b16cdb135c5 Mon Sep 17 00:00:00 2001
> From: Jeremy Bryant <jb@jeremybryant.net>
> Date: Tue, 23 Apr 2024 22:21:07 +0100
> Subject: [PATCH] Add Macrostep section in manual
>
> Macrostep is an Emacs Lisp macro-expander useful for exploring and
> writing macros.  This is based on Jonathan's Oddie's documentation
> in the macrostep package.
>
>       * doc/emacs/programs.texi (Programs): Add Macrostep section.
>       * doc/emacs/emacs.texi (Top):   Add detailed menu reference.
> ---
>  doc/emacs/emacs.texi    |  3 ++
>  doc/emacs/programs.texi | 61 +++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 64 insertions(+)
>
> diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
> index 7d77f13ab21..d4d0a753576 100644
> --- a/doc/emacs/emacs.texi
> +++ b/doc/emacs/emacs.texi
> @@ -694,6 +694,9 @@ Top
>  @ifnottex
>  * Fortran::             Fortran mode and its special features.
>  @end ifnottex
> +@ifnottex
> +* Macrostep::           Interactive Lisp macro-expander.

IIUC, this is specific to Emacs Lisp, right?  If so, I suggest writing
"Elisp" or "Emacs Lisp" instead of "Lisp" here, for clarity.

> +@end ifnottex
>
>  Top-Level Definitions, or Defuns
>
> diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
> index de28a9f1dd4..15cfffc289b 100644
> --- a/doc/emacs/programs.texi
> +++ b/doc/emacs/programs.texi
> @@ -45,6 +45,10 @@ Programs
>  @ifnottex
>  * Fortran::             Fortran mode and its special features.
>  @end ifnottex
> +@ifnottex
> +* Macrostep::           Interactive Lisp macro-expander.

Likewise here.

> +@end ifnottex
> +
>  @end menu
>
>  @node Program Modes
> @@ -2235,3 +2239,60 @@ Asm Mode
>  @ifnottex
>  @include fortran-xtra.texi
>  @end ifnottex
> +
> +@ifnottex
> +@node Macrostep
> +@section Macrostep: interactive Lisp macro-expander
> +

I'd open with a few more words of motivation, e.g. "Emacs Lisp code that
you read and write often makes use of macros (@pxref{Macros,,,elisp})."

> +You can use @code{macrostep-mode} to explore Lisp macro definitions, and
> +help write new macros...

Since macrostep-mode is not intended to be enabled directly, I suggest
putting less emphasis on the minor mode and more on the feature itself,
so maybe something like "Emacs comes with a feature called
@dfn{Macrostep} that helps you explore and write new macros"

> ...using @kbd{M-x macrostep-expand} when point is
> +over a macro.

Here I think that "when point is over a macro" could be made a little
more precise.  How about "when point is inside a macro form" or
something along these lines?

> +@kbd{macrostep} is a minor mode for interactively stepping through the
> +expansion of macros in Emacs Lisp source code.

"Macrostep lets you step through the expansion of macros interactively."

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

Maybe add a reference to Edebug?

> Single-stepping through
> +the expansion is particularly useful for debugging macros that expand
> +into another macro form.  These can be difficult to debug with
> +@code{macroexpand}, which continues expansion until the top-level form
> +is no longer a macro call.

The comparison with macroexpand seems a bit like a straw-man argument in
favor of Macrostep, what about macroexpand-1?  IMO, we can just remove
these two sentences.  The utility of Macrostep is clear enough as is.

> +
> +The standard keybindings in @code{macrostep-mode} are the following:
> +@table @kbd
> +@item e
> +@itemx =
> +@itemx RET
> +@findex macrostep-expand
> +Expand the macro form following point one step (@code{macrostep-expand}).

"following point"?  ISTM that this command expands the first macro form
containing point, no?

> +@item c
> +@itemx u
> +@itemx DEL
> +@findex macrostep-collapse
> +Collapse the form following point (@code{macrostep-collapse}).

Likewise.

> +@item n
> +@itemx TAB
> +@findex macrostep-next-macro
> +Jump to the next macro form in the expansion (@code{macrostep-next-macro}).
> +@item p
> +@itemx M-TAB
> +@findex macrostep-previous-macro
> +Jump to the previous macro form in the expansion (@code{macrostep-previous-macro}).
> +@item q
> +@itemx C-c C-c
> +@findex macrostep-collapse-all
> +Collapse all expanded forms and exit macrostep-mode (@code{macrostep-collapse-all}).
> +@end table
> +
> +It's not very useful to enable and disable macrostep-mode directly.

This sentence isn't necessary IMO.

> +Instead, bind @code{macrostep-expand} to a key in
> +@code{emacs-lisp-mode-map}, for example @kbd{C-c e}.

Maybe add example code for how to do that?  Or just refer to some
relevant part of the manual for defining key bindings.
> +
> +You can then enter @code{macrostep-mode} and expand a macro form
> +completely by typing @kbd{C-c e e e@dots{}} as many times as necessary.
> +
> +Exit macrostep-mode by typing @kbd{q} or @kbd{C-c C-c}, or by
> +successively typing @kbd{c} to collapse all surrounding expansions.
> +@end ifnottex


Best regards,

Eshel