[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Emacs-diffs] emacs-26 9a53b6d: Say how to override a primitive inte
From: |
Karl Fogel |
Subject: |
Re: [Emacs-diffs] emacs-26 9a53b6d: Say how to override a primitive interactive spec |
Date: |
Sun, 24 Jun 2018 22:47:18 -0500 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) |
Eli Zaretskii <address@hidden> writes:
>No, I meant the former: your original addition.
>
>"Internals" is where the reader learns how to write Emacs primitives
>and how some features work internally. It is a place where Lisp
>programmers seldom if ever look for stuff that's important for writing
>Lisp programs. Your text is for those Lisp programmers, so IMO it
>doesn't belong where you put it.
In your post [1] that I reference from the commit message, you seemed to have a
different opinion (which is fine, of course -- one's opinion can change). I'd
stated my intention to document this potential use of `interactive-form', there
in "@item interactive" in doc/lispref/internals.texi, and your reply suggested
doing it as a cross-reference. That's basically what my change is, though with
a sentence discussing the motivation for why one might want to. I took your
reply as indicating agreement, or at the very least non-objection, to an
addition along these lines.
Anyway, here's why I think the addition is useful:
If someone who normally writes Emacs Lisp and hasn't had much exposure to the C
code finds herself wanting to override the interactive form of a primitive
function, there are several places she might go in the documentation, depending
on what research path she takes. In most of those places, we already document
or refer to this technique, so no change is necessary for them. But she might
say to herself "Aha, the function I'm overriding is a primitive, so I'd better
go look at how primitives are defined. Maybe that will teach me how to
override a primitive's interactive spec, which I obviously can't do by just
editing and re-evaluating a Lisp `defun' the way one normally would". In that
case, she would end up in the place that I modified, and the question she's
interested in would now be addressed there (by flagging itself as her use case
and then referring her to a more complete description in another part of the
documentation).
I see your point about how this part of the documentation is really focused on
how Emacs works internally, though. This is always a tricky issue in
documentation: how much to keep to tight topic discipline versus how much to
anticipate potential use cases in a more directly utilitarian fashion (which
inevitably means loosening the topic discipline).
I welcome your thoughts, now that I've laid out the best argument I can above.
One route might be to just put a "(@pxref{Using interactive})" at the end of
the sentence...
This is an interactive specification, a string such as might be used
as the argument of ‘interactive’ in a Lisp function.
...instead of my larger change, which I'd be happy to do; maybe that's the kind
of thing you had mind by "cross-reference" in the first place.
Best regards,
-Karl
[1] https://lists.gnu.org/archive/html/emacs-devel/2018-03/msg00923.html
- Re: `interactive-form` symbol property (was: [Emacs-diffs] emacs-26 9a53b6d: Say how to override a primitive interactive spec), (continued)
- Re: `interactive-form` symbol property, Basil L. Contovounesios, 2018/06/24
- Re: `interactive-form` symbol property, Stefan Monnier, 2018/06/24
- Re: `interactive-form` symbol property, Eli Zaretskii, 2018/06/24
- Re: `interactive-form` symbol property, Stefan Monnier, 2018/06/25
- Re: `interactive-form` symbol property, Eli Zaretskii, 2018/06/25
- Re: `interactive-form` symbol property, Stefan Monnier, 2018/06/25
Re: [Emacs-diffs] emacs-26 9a53b6d: Say how to override a primitive interactive spec, Eli Zaretskii, 2018/06/24