From cef9258e824d7a20c8364417c9debd8b2d5133fe Mon Sep 17 00:00:00 2001 From: Jeremy Bryant 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 --- 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