Re: Incorporate package macrostep into Emacs core

[Jeremy Bryant <jb@jeremybryant.net>]

[-- Attachment #1: Type: text/plain, Size: 858 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Jeremy Bryant <jb@jeremybryant.net>
>> Cc: monnier@iro.umontreal.ca,  emacs-devel@gnu.org
>> Date: Fri, 19 Apr 2024 20:30:30 +0100
>> 
>> >   . should this be in the user manual instead? it sounds like a
>> >     user-level feature, not Lisp programming level feature
>> 
>> Sure, perhaps this is more suited.
>> 
>> I initially followed your confirmation to write in the Emacs Lisp manual
>> (top of this message), but indeed this may belong more appropriately in
>> the Emacs manual.  How about in "(emacs) Programs"?
>
> Yes, a section under "Programs" sounds good.
>
> Thanks.

Please find attached a revised patch for consideration.  Any feedback on
style and conventions welcome.

Text is adapted from the macrostep package - I believe Jonathan's FSF
paperwork is still outstanding but is expected soon.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-new-manual-section-on-macrostep.patch --]
[-- Type: text/x-diff, Size: 4750 bytes --]

From cef9258e824d7a20c8364417c9debd8b2d5133fe Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <jb@jeremybryant.net>
Date: Thu, 18 Apr 2024 21:03:30 +0100
Subject: [PATCH] Add new manual section on macrostep

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

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

Co-authored-by: Jonathan Oddie <j.j.oddie@gmail.com>
---
 doc/lispref/macros.texi | 69 ++++++++++++++++++++++++++++++++++-------
 1 file changed, 58 insertions(+), 11 deletions(-)

diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi
index 659dba17524..06e098a8389 100644
--- a/doc/lispref/macros.texi
+++ b/doc/lispref/macros.texi
@@ -23,13 +23,14 @@ Macros
 instead.  @xref{Inline Functions}.
 
 @menu
-* 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::
 @end menu
 
 @node Simple Macro
@@ -262,12 +263,12 @@ Problems with Macros
 trouble, and rules to follow to avoid trouble.
 
 @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.
 @end menu
 
 @node Wrong Time
@@ -640,3 +641,49 @@ Indenting Macros
 number, @kbd{C-M-q} need not recalculate indentation for the following
 lines until the end of the list.
 @end table
+
+
+@node macrostep: interactive macro-expander
+@section macrostep: interactive macro-expander
+
+You can use the package @code{macrostep} to explore macro definitions, and
+help write new macros, using @kbd{M-x macrostep-expand}.
+
+@ifnottex
+@kbd{macrostep} is an Emacs minor mode for interactively stepping
+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.
+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 standard keybindings in @code{macrostep-mode} are the following:
+
+@itemize @minus
+@item
+e, =, RET : expand the macro form following point one step
+@item
+c, u, DEL : collapse the form following point
+@item
+q, C-c C-c: collapse all expanded forms and exit macrostep-mode
+@item
+n, TAB    : jump to the next macro form in the expansion
+@item
+p, M-TAB  : jump to the previous macro form in the expansion
+@end itemize
+
+It's not very useful to enable and disable macrostep-mode directly.
+Instead, bind `macrostep-expand' to a key in `emacs-lisp-mode-map',
+for example @kbd{C-c e}.
+
+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
-- 
2.42.0