Re: [Emacs-diffs] emacs-26 9a53b6d: Say how to override a primitive interactive spec

[Karl Fogel <kfogel@red-bean.com>]

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