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: Thu, 18 Apr 2024 22:19:36 +0100 [thread overview]
Message-ID: <87plume5cn.fsf@jeremybryant.net> (raw)
In-Reply-To: <86sf0n4sfq.fsf@gnu.org> (Eli Zaretskii's message of "Mon, 18 Mar 2024 14:48:09 +0200")
[-- Attachment #1: Type: text/plain, Size: 474 bytes --]
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.
[-- 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
next prev parent reply other threads:[~2024-04-18 21:19 UTC|newest]
Thread overview: 50+ 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 [this message]
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
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=87plume5cn.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).