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: Thu, 18 Apr 2024 22:19:36 +0100 Message-ID: <87plume5cn.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> 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="5370"; 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 Thu Apr 18 23:20:35 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 1rxZBK-0001GB-ND for ged-emacs-devel@m.gmane-mx.org; Thu, 18 Apr 2024 23:20:35 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rxZAg-0007Zj-0N; Thu, 18 Apr 2024 17:19:54 -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 1rxZAd-0007Z7-OZ for emacs-devel@gnu.org; Thu, 18 Apr 2024 17:19:51 -0400 Original-Received: from out-181.mta1.migadu.com ([2001:41d0:203:375::b5]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rxZAb-0001G9-I2 for emacs-devel@gnu.org; Thu, 18 Apr 2024 17:19:51 -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=1713475178; 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=j5Wg+Vd1D2PCA+C3kZBQvC5tieekL7XZxytKqxs4KxE=; b=Ww9MIQHtpYRKWIXpbOXFwxbJgwLgOE1TbygN/XgbM5mnb5cHm3iR/fqUOyUDRXygY5yqan pAkatZOU8XR3acLfIyyNDW3gC/W9xBqixiT3ThU/NMvJSqpHFceq7Nci1+pFwyp8XUZL9Q wkBWbGqMjvFp2q0Pli+Dz1u5GCB3Hz9nxGMPso2lw0IIvPt0WJHw1k3/t6P3WjVfIWMYF1 oRXaoe9/edN7H3V8gf8j/7YPM+kLGUHTdb7CXkRw86EgLe/e8BuxAaMK3swg2qWjToozVl xe/Npl9JdZVd3T5dxs01GITqaRt1OxL4v4VBVXFWWSFCQgJZCFwMG9O8jV/Qeg== In-Reply-To: <86sf0n4sfq.fsf@gnu.org> (Eli Zaretskii's message of "Mon, 18 Mar 2024 14:48:09 +0200") X-Migadu-Flow: FLOW_OUT Received-SPF: pass client-ip=2001:41d0:203:375::b5; envelope-from=jb@jeremybryant.net; helo=out-181.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:317828 Archived-At: --=-=-= Content-Type: text/plain Eli Zaretskii writes: >> From: Jeremy Bryant >> 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. --=-=-= 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 --=-=-=--