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

[Karl Fogel]

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