Re: Incorporate package macrostep into Emacs core

[Jeremy Bryant <jb@jeremybryant.net>]

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

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Jeremy Bryant <jb@jeremybryant.net>
>> Cc: monnier@iro.umontreal.ca,  emacs-devel@gnu.org
>> Date: Tue, 23 Apr 2024 22:37:50 +0100
>> 
>> 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.
>
> Thanks, but it looks like you attached the wrong patch?  It seems like
> it's the same patch you sent the first time, not a revised one after
> all the comments above, where we agreed to have this in the Emacs user
> manual instead.

Absolutely, sorry, attached is the revised patch I have worked on.


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

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.
+@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.
+@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
+
+You can use @code{macrostep-mode} to explore Lisp macro definitions, and
+help write new macros, using @kbd{M-x macrostep-expand} when point is
+over a macro.
+
+@kbd{macrostep} is a 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 usual.  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:
+@table @kbd
+@item e
+@itemx =
+@itemx RET
+@findex macrostep-expand
+Expand the macro form following point one step (@code{macrostep-expand}).
+@item c
+@itemx u
+@itemx DEL
+@findex macrostep-collapse
+Collapse the form following point (@code{macrostep-collapse}).
+@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.
+Instead, bind @code{macrostep-expand} to a key in
+@code{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