From: Karl Fogel <kfogel@red-bean.com>
To: Eli Zaretskii <eliz@gnu.org>
Cc: monnier@IRO.UMontreal.CA, emacs-devel@gnu.org
Subject: Re: [Emacs-diffs] emacs-26 9a53b6d: Say how to override a primitive interactive spec
Date: Sun, 24 Jun 2018 22:47:18 -0500 [thread overview]
Message-ID: <87y3f3a5o9.fsf@red-bean.com> (raw)
In-Reply-To: 83tvprsig4.fsf@gnu.org
Eli Zaretskii <eliz@gnu.org> 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
next prev parent reply other threads:[~2018-06-25 3:47 UTC|newest]
Thread overview: 18+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <20180624121111.28772.8847@vcs0.savannah.gnu.org>
[not found] ` <20180624121113.215CF206CC@vcs0.savannah.gnu.org>
2018-06-24 13:42 ` [Emacs-diffs] emacs-26 9a53b6d: Say how to override a primitive interactive spec Stefan Monnier
2018-06-24 13:54 ` `interactive-form` symbol property (was: [Emacs-diffs] emacs-26 9a53b6d: Say how to override a primitive interactive spec) Stefan Monnier
2018-06-24 15:27 ` Drew Adams
2018-06-24 15:48 ` `interactive-form` symbol property Stefan Monnier
2018-06-24 17:19 ` Drew Adams
2018-06-24 21:57 ` `interactive-form` symbol property (was: [Emacs-diffs] emacs-26 9a53b6d: Say how to override a primitive interactive spec) Radon Rosborough
2018-06-24 15:40 ` `interactive-form` symbol property Basil L. Contovounesios
2018-06-24 15:56 ` Stefan Monnier
2018-06-24 16:20 ` Eli Zaretskii
2018-06-25 12:32 ` Stefan Monnier
2018-06-25 15:19 ` Eli Zaretskii
2018-06-25 20:22 ` Stefan Monnier
2018-06-24 14:44 ` [Emacs-diffs] emacs-26 9a53b6d: Say how to override a primitive interactive spec Eli Zaretskii
2018-06-24 22:09 ` Karl Fogel
2018-06-25 2:34 ` Eli Zaretskii
2018-06-25 3:47 ` Karl Fogel [this message]
2018-06-25 12:43 ` Karl Fogel
2018-06-25 14:41 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87y3f3a5o9.fsf@red-bean.com \
--to=kfogel@red-bean.com \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
--cc=monnier@IRO.UMontreal.CA \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.