From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Jeremy Bryant Newsgroups: gmane.emacs.devel Subject: Re: Incorporate package macrostep into Emacs core Date: Tue, 23 Apr 2024 22:37:50 +0100 Message-ID: <875xw7ep5d.fsf@jeremybryant.net> References: <87zfvl8r4e.fsf@jeremybryant.net> <874jdspsqb.fsf@bernoul.li> <877cio8fzf.fsf@jeremybryant.net> <87y1b46vhg.fsf@jeremybryant.net> <878r336lvb.fsf@jeremybryant.net> <86y1b1p1ni.fsf@gnu.org> <87y1b0mi4b.fsf@jeremybryant.net> <8734sobkdj.fsf@jeremybryant.net> <86sf0n4sfq.fsf@gnu.org> <87plume5cn.fsf@jeremybryant.net> <867cgtdfhg.fsf@gnu.org> <87edb1duax.fsf@jeremybryant.net> <86pluka80r.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="15563"; mail-complaints-to="usenet@ciao.gmane.io" Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Tue Apr 23 23:38:48 2024 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1rzNqh-0003lE-4b for ged-emacs-devel@m.gmane-mx.org; Tue, 23 Apr 2024 23:38:47 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rzNpx-00072l-J1; Tue, 23 Apr 2024 17:38:01 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rzNpv-00072O-RQ for emacs-devel@gnu.org; Tue, 23 Apr 2024 17:37:59 -0400 Original-Received: from out-170.mta1.migadu.com ([2001:41d0:203:375::aa]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rzNpt-00045v-5F for emacs-devel@gnu.org; Tue, 23 Apr 2024 17:37:59 -0400 X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jeremybryant.net; s=key1; t=1713908273; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=CnpuMbul8r2QPUy7+h2LYw97qCgYkSNEiqnlPfpHrqQ=; b=mfHLnYPkw91sAHSyTuloWkvY+TzinHZ0frU5+uM8tGRdRf0rL5ICemqH2aZ6FkDFwjMWq+ NYzlmC+wuaklsxp2moAjpjWRpF6U5shRo9KCqhEGuPZA/eMfqH5nA+JLHRgEIctxBgVZic 0wdxtP/P9X+aHTJ449Nfks8Oe+FXGv96sMjPpHQBgmfX+xewpLN91PCxjPUrbPTZJLKsAj ap9GhHgodV0hqeopVI7m3asZdsChPUfAWjmywmfPozTlVkmWI4PDaV48QdoBc9w7oefLJe Z2doxEEup2mMc1r7yk0Ka7pLFwLIdPz7j7VQcPkPAYbiS8Au/8FESXVLDaCiJA== In-Reply-To: <86pluka80r.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 20 Apr 2024 09:00:04 +0300") X-Migadu-Flow: FLOW_OUT Received-SPF: pass client-ip=2001:41d0:203:375::aa; envelope-from=jb@jeremybryant.net; helo=out-170.mta1.migadu.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:318015 Archived-At: --=-=-= Content-Type: text/plain Eli Zaretskii writes: >> From: Jeremy Bryant >> 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. --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=0001-Add-new-manual-section-on-macrostep.patch >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 --=-=-=--