From: Jeremy Bryant <jb@jeremybryant.net>
To: Eli Zaretskii <eliz@gnu.org>
Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
Subject: Re: Incorporate package macrostep into Emacs core
Date: Mon, 29 Apr 2024 22:38:27 +0100 [thread overview]
Message-ID: <878r0valyk.fsf@jeremybryant.net> (raw)
In-Reply-To: <868r0zw2si.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 27 Apr 2024 12:52:29 +0300")
[-- Attachment #1: Type: text/plain, Size: 1680 bytes --]
Eli Zaretskii <eliz@gnu.org> writes:
>> From: Jeremy Bryant <jb@jeremybryant.net>
>> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
>> Date: Thu, 25 Apr 2024 22:27:56 +0100
>>
>> Absolutely, sorry, attached is the revised patch I have worked on.
>
> Thanks, a few minor comments below.
>
>> 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.
> ^^^^^^^ ^^^
> Those TABs should not be there in the commit log message.
>
>> +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.
>
> We say "when point is in a macro". "Over" is reserved for mouse
> pointer.
>
>> +@kbd{macrostep} is a minor mode for interactively stepping through the
> ^^^^^^^^^
> "macrostep-mode", I guess? And why @kbd? is that something the user
> is supposed to type?
>
>> +The standard keybindings in @code{macrostep-mode} are the following:
>> +@table @kbd
>> +@item e
>> +@itemx =
>> +@itemx RET
>> +@findex macrostep-expand
>
> Please move the index entries to _before_ the corresponding @item's,
> so that following the index entry lands you on the @item, not after
> it.
>
> Otherwise, this LGTM, thanks.
OK - Attached is a revised patch incorporating the ideas above (as well as a
refinement from Eshel on clarifying this is for Emacs Lisp).
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-Macrostep-section-in-manual.patch --]
[-- Type: text/x-diff, Size: 3743 bytes --]
From 4be7abaa0af33936b62119732609a1d4ff8ee1b4 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..2ce47dd6e5e 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 Emacs Lisp macro-expander.
+@end ifnottex
Top-Level Definitions, or Defuns
diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index de28a9f1dd4..8c8542cc374 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 Emacs 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 Emacs 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
+in a macro.
+
+@code{macrostep-mode} 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
+@findex macrostep-expand
+@item e
+@itemx =
+@itemx RET
+Expand the macro form following point one step (@code{macrostep-expand}).
+@findex macrostep-collapse
+@item c
+@itemx u
+@itemx DEL
+Collapse the form following point (@code{macrostep-collapse}).
+@findex macrostep-next-macro
+@item n
+@itemx TAB
+Jump to the next macro form in the expansion (@code{macrostep-next-macro}).
+@findex macrostep-previous-macro
+@item p
+@itemx M-TAB
+Jump to the previous macro form in the expansion (@code{macrostep-previous-macro}).
+@findex macrostep-collapse-all
+@item q
+@itemx C-c C-c
+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
next prev parent reply other threads:[~2024-04-29 21:38 UTC|newest]
Thread overview: 52+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <87zfvl8r4e.fsf@jeremybryant.net>
[not found] ` <874jdspsqb.fsf@bernoul.li>
2024-02-28 20:56 ` Incorporate package macrostep into Emacs or NonGNU ELPA? Jeremy Bryant via Emacs development discussions.
2024-02-28 21:16 ` Stefan Monnier
2024-02-28 23:04 ` Jeremy Bryant
2024-02-29 20:44 ` Jeremy Bryant
2024-03-01 4:15 ` Adam Porter
2024-03-01 23:26 ` Stefan Monnier
2024-03-02 21:50 ` Jeremy Bryant
2024-03-02 22:51 ` Stefan Monnier
2024-03-03 7:26 ` Adam Porter
2024-03-03 7:51 ` Eli Zaretskii
2024-03-03 7:53 ` Adam Porter
2024-03-03 8:57 ` Eli Zaretskii
2024-03-03 14:28 ` Stefan Monnier
2024-03-04 11:25 ` Ihor Radchenko
2024-03-04 15:35 ` Stefan Monnier
2024-03-03 22:40 ` Jeremy Bryant
2024-03-04 12:00 ` Eli Zaretskii
2024-03-11 22:47 ` Jeremy Bryant
2024-03-02 6:51 ` Eli Zaretskii
2024-03-02 21:36 ` Jeremy Bryant
2024-03-17 21:48 ` Incorporate package macrostep into Emacs core Jeremy Bryant via Emacs development discussions.
2024-03-18 9:09 ` Philip Kaludercic
2024-03-18 23:03 ` Jeremy Bryant
2024-03-19 6:36 ` Philip Kaludercic
2024-03-19 7:11 ` Gerd Möllmann
2024-03-19 7:26 ` Philip Kaludercic
2024-03-19 7:30 ` Gerd Möllmann
2024-03-19 9:33 ` Philip Kaludercic
2024-03-19 9:48 ` Gerd Möllmann
2024-03-19 17:03 ` Jonathan Oddie
2024-03-19 21:57 ` Jeremy Bryant via Emacs development discussions.
2024-03-22 20:47 ` Jeremy Bryant
2024-03-22 20:50 ` Stefan Monnier
2024-03-18 12:48 ` Eli Zaretskii
2024-03-18 13:22 ` Stefan Monnier
2024-03-18 22:58 ` Jeremy Bryant
2024-03-19 12:26 ` Eli Zaretskii
2024-04-18 21:19 ` Jeremy Bryant
2024-04-19 6:38 ` Eli Zaretskii
2024-04-19 19:30 ` Jeremy Bryant
2024-04-19 22:26 ` Stefan Monnier
2024-04-20 6:07 ` Eli Zaretskii
2024-04-20 17:14 ` Adam Porter
2024-04-20 6:00 ` Eli Zaretskii
2024-04-23 21:37 ` Jeremy Bryant
2024-04-25 15:30 ` Eli Zaretskii
2024-04-25 21:27 ` Jeremy Bryant
2024-04-26 8:15 ` Eshel Yaron
2024-04-27 9:52 ` Eli Zaretskii
2024-04-29 21:38 ` Jeremy Bryant [this message]
2024-05-02 9:32 ` Eli Zaretskii
2024-05-02 22:03 ` Jeremy Bryant
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=878r0valyk.fsf@jeremybryant.net \
--to=jb@jeremybryant.net \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
--cc=monnier@iro.umontreal.ca \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).