From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Incorporate package macrostep into Emacs core Date: Fri, 19 Apr 2024 09:38:19 +0300 Message-ID: <867cgtdfhg.fsf@gnu.org> 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> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="34870"; mail-complaints-to="usenet@ciao.gmane.io" Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org To: Jeremy Bryant Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Apr 19 08:39:15 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 1rxhty-0008rY-PZ for ged-emacs-devel@m.gmane-mx.org; Fri, 19 Apr 2024 08:39:15 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rxhtH-0006hx-GC; Fri, 19 Apr 2024 02:38:31 -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 1rxht9-0006hT-UG for emacs-devel@gnu.org; Fri, 19 Apr 2024 02:38:25 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rxht7-0000Be-GI; Fri, 19 Apr 2024 02:38:21 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=LnzHonXc+4SilisMkD7UZQhxFT5bBgDqLJZ5zaBmvRU=; b=Wb0uN0SF4t/n Q4NdQqmrVLNPGYViOl/00tYPfpv8+FfCGjo9RZSsldwMf/KsbF+daHZBORTBU5ZdmPzoCe0O3kXLp ySxNQVds6uN/Pfm5qu/isr5gZQSjciU1dyYJC2BvtDzjyY1Feo1FaW6kkX+4YJkua2ACwflwhvhdg eVc0JepbXWiBzq4mX+S2D0JzXGNEfJ2TOmyBZqsVL1BTGQOHXnBJ0LbtBRJBbcReVXHKHJOQujny/ 4hHKtFMTKCWo8EH6f2CHlnW6R7ZFNg0E5Tl07t1mQi3CtBp6QS3jjmWI8sSdn/+0TaZZQvVp375hd SXImqjUFChjDpPgBD7EYcg==; In-Reply-To: <87plume5cn.fsf@jeremybryant.net> (message from Jeremy Bryant on Thu, 18 Apr 2024 22:19:36 +0100) 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:317834 Archived-At: > From: Jeremy Bryant > Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org > Date: Thu, 18 Apr 2024 22:19:36 +0100 > > 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. Thanks, see below. > * doc/lispref/macros.texi (Macros): > Describe macrostep's usage to explore and write macros. This is filled sub-optimally; please use change-log-mode to help you fill better. > This is based on Jonathan's Oddie's documentation in the macrostep package Likewise here: this line is too long. > -* 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:: I'd prefer not to change whitespace here. I see no reason for it in this case. Also, any change in the menus requires a corresponding change in elisp.texi, where we have the @detailmenu. > @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. Unnecessary whitespace changes again. > +@node macrostep: interactive macro-expander > +@section macrostep: interactive macro-expander > + > +You can use the package @code{macrostep} to explore macro definitions, and ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ "You can use the @code{macrostep} package" is better. Alternatively, say "@code{macrostep-mode}" instead; no need to mention that it's a package. > +help write new macros, using @kbd{M-x macrostep-expand}. > + > +@ifnottex This @ifnottex makes this section very small in the printed manual, which I think is undesirable. Instead, I'd move the sentence above to the parent chapter, and have the entire section be inside @ifnottex (also in menus). > +@kbd{macrostep} is an Emacs minor mode for interactively stepping There's no point of having "Emacs" there, since this manual is about Emacs Lisp. > +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. ^^^^^^^^^ "as usual" > +The standard keybindings in @code{macrostep-mode} are the following: > + > +@itemize @minus > +@item > +e, =, RET : expand the macro form following point one step This will produce sub-optimal markup. I suggest to use "@table @kbd" instead. Also, our style is to mention the command bound to the keys in parentheses, and also index each such command. > +It's not very useful to enable and disable macrostep-mode directly. > +Instead, bind `macrostep-expand' to a key in `emacs-lisp-mode-map', ^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^ These two should be in @code instead of in quotes `like this'. > +by typing @kbd{C-c e e e}@dots as many times as necessary. @dots{} (not "@dots") should be inside @kbd. And finally, two more questions: . should this be in the user manual instead? it sounds like a user-level feature, not Lisp programming level feature . how is this mode different from "C-x C-k SPC", which is already described in the user manual as a similar feature?