[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Incorporate package macrostep into Emacs core
From: |
Eli Zaretskii |
Subject: |
Re: Incorporate package macrostep into Emacs core |
Date: |
Fri, 19 Apr 2024 09:38:19 +0300 |
> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
> Date: Thu, 18 Apr 2024 22:19:36 +0100
>
> Eli Zaretskii <eliz@gnu.org> writes:
>
> >> From: Jeremy Bryant <jb@jeremybryant.net>
> >> 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?
- Re: Incorporate package macrostep into Emacs core, Jeremy Bryant, 2024/04/18
- Re: Incorporate package macrostep into Emacs core,
Eli Zaretskii <=
- Re: Incorporate package macrostep into Emacs core, Eli Zaretskii, 2024/04/20
- Re: Incorporate package macrostep into Emacs core, Jeremy Bryant, 2024/04/23
- Re: Incorporate package macrostep into Emacs core, Eli Zaretskii, 2024/04/25
- Re: Incorporate package macrostep into Emacs core, Jeremy Bryant, 2024/04/25
- Re: Incorporate package macrostep into Emacs core, Eshel Yaron, 2024/04/26
- Re: Incorporate package macrostep into Emacs core, Eli Zaretskii, 2024/04/27