From: Eshel Yaron <me@eshelyaron.com>
To: Jeremy Bryant <jb@jeremybryant.net>
Cc: Eli Zaretskii <eliz@gnu.org>,
monnier@iro.umontreal.ca, emacs-devel@gnu.org
Subject: Re: Incorporate package macrostep into Emacs core
Date: Fri, 26 Apr 2024 10:15:12 +0200 [thread overview]
Message-ID: <m17cgkilpr.fsf@dazzs-mbp.kpn> (raw)
In-Reply-To: <87ttjpceub.fsf@jeremybryant.net> (Jeremy Bryant's message of "Thu, 25 Apr 2024 22:27:56 +0100")
Hello Jeremy,
Jeremy Bryant <jb@jeremybryant.net> writes:
> ...attached is the revised patch I have worked on.
A few minor comments:
> 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.
IIUC, this is specific to Emacs Lisp, right? If so, I suggest writing
"Elisp" or "Emacs Lisp" instead of "Lisp" here, for clarity.
> +@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.
Likewise here.
> +@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
> +
I'd open with a few more words of motivation, e.g. "Emacs Lisp code that
you read and write often makes use of macros (@pxref{Macros,,,elisp})."
> +You can use @code{macrostep-mode} to explore Lisp macro definitions, and
> +help write new macros...
Since macrostep-mode is not intended to be enabled directly, I suggest
putting less emphasis on the minor mode and more on the feature itself,
so maybe something like "Emacs comes with a feature called
@dfn{Macrostep} that helps you explore and write new macros"
> ...using @kbd{M-x macrostep-expand} when point is
> +over a macro.
Here I think that "when point is over a macro" could be made a little
more precise. How about "when point is inside a macro form" or
something along these lines?
> +@kbd{macrostep} is a minor mode for interactively stepping through the
> +expansion of macros in Emacs Lisp source code.
"Macrostep lets you step through the expansion of macros interactively."
> 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.
Maybe add a reference to Edebug?
> 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 comparison with macroexpand seems a bit like a straw-man argument in
favor of Macrostep, what about macroexpand-1? IMO, we can just remove
these two sentences. The utility of Macrostep is clear enough as is.
> +
> +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}).
"following point"? ISTM that this command expands the first macro form
containing point, no?
> +@item c
> +@itemx u
> +@itemx DEL
> +@findex macrostep-collapse
> +Collapse the form following point (@code{macrostep-collapse}).
Likewise.
> +@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.
This sentence isn't necessary IMO.
> +Instead, bind @code{macrostep-expand} to a key in
> +@code{emacs-lisp-mode-map}, for example @kbd{C-c e}.
Maybe add example code for how to do that? Or just refer to some
relevant part of the manual for defining key bindings.
> +
> +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
Best regards,
Eshel
next prev parent reply other threads:[~2024-04-26 8:15 UTC|newest]
Thread overview: 86+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <RT-Ticket-2038816@rt.gnu.org>
[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
[not found] ` <jwvsf0wqrqg.fsf-monnier+emacs@gnu.org>
[not found] ` <87r0fugl5o.fsf@jeremybryant.net>
[not found] ` <jwvle613zk7.fsf-monnier+emacs@gnu.org>
[not found] ` <rt-4.2.16-14-g9a593ee-16065-1711725597-1342.2038816-6-0@rt.gnu.org>
[not found] ` <87h6g6jthh.fsf@jeremybryant.net>
[not found] ` <rt-4.2.16-14-g9a593ee-24903-1712948497-1603.2038816-5-0@rt.gnu.org>
[not found] ` <jwvjzl25qpv.fsf-monnier+emacs@gnu.org>
2024-02-04 22:02 ` bug#68929: [PATCH] Copy which-key from GNU ELPA into core Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-05 2:15 ` Justin Burkett
2024-02-05 3:08 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-05 12:32 ` Eli Zaretskii
2024-02-06 2:51 ` Justin Burkett
2024-02-07 21:53 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-08 6:09 ` Eli Zaretskii
2024-02-08 22:25 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-11 21:32 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-15 8:29 ` Eli Zaretskii
2024-02-17 13:10 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-17 16:58 ` Eli Zaretskii
2024-02-07 22:01 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-08 6:16 ` Eli Zaretskii
2024-02-08 15:42 ` Justin Burkett
2024-02-08 16:10 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-08 16:54 ` Eli Zaretskii
2024-02-08 22:27 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-09 6:51 ` Eli Zaretskii
2024-02-07 8:20 ` Philip Kaludercic
2024-02-07 21:48 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-08 6:03 ` Eli Zaretskii
2024-03-01 23:08 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-03-02 9:33 ` Philip Kaludercic
[not found] ` <87r0faibbg.fsf@jeremybryant.net>
2024-04-12 20:40 ` bug#68929: which-key tests " Philip Kaludercic
[not found] ` <87wmp2ibjj.fsf@jeremybryant.net>
2024-04-14 9:21 ` bug#68929: [PATCH] Copy which-key " Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-04-14 10:13 ` Eli Zaretskii
2024-04-14 21:52 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-04-15 11:13 ` Eli Zaretskii
2024-04-29 21:00 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-05-01 7:31 ` Philip Kaludercic
2024-02-23 23:07 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-04-14 21:56 ` bug#68929: Fwd: Re: bug#68929: which-key tests " Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-04-15 8:39 ` Mattias Engdegård
2024-03-02 6:51 ` Incorporate package macrostep into Emacs or NonGNU ELPA? 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 [this message]
2024-04-27 9:52 ` Eli Zaretskii
2024-04-29 21:38 ` Jeremy Bryant
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
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=m17cgkilpr.fsf@dazzs-mbp.kpn \
--to=me@eshelyaron.com \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
--cc=jb@jeremybryant.net \
--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 external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.