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

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

[Stefan Monnier]

> +If you wish to override a primitive interactive specification, just
> +set the @code{interactive-form} property of the primitive function's
> +symbol (@pxref{Using Interactive}).  There is no need to edit C code
> +and recompile Emacs.

You can also use advice-add for the same purpose (it's more
complicated, but it's arguably better behaved).


        Stefan

`interactive-form` symbol property (was: [Emacs-diffs] emacs-26 9a53b6d: Say how to override a primitive interactive spec)

[Stefan Monnier]

>> +If you wish to override a primitive interactive specification, just
>> +set the @code{interactive-form} property of the primitive function's
>> +symbol (@pxref{Using Interactive}).  There is no need to edit C code
>> +and recompile Emacs.
> You can also use advice-add for the same purpose (it's more
> complicated, but it's arguably better behaved).

And a quick search seems to indicate that this `interactive-form`
property is not used anywhere (not within Emacs, not within GNU ELPA,
and not within the few other Elisp packages I had lying around for
a quick search).

Maybe, rather than document it, we should obsolete it?


        Stefan

RE: `interactive-form` symbol property (was: [Emacs-diffs] emacs-26 9a53b6d: Say how to override a primitive interactive spec)

[Drew Adams]

> >> +If you wish to override a primitive interactive specification, just
> >> +set the @code{interactive-form} property of the primitive function's
> >> +symbol (@pxref{Using Interactive}).  There is no need to edit C code
> >> +and recompile Emacs.
> > You can also use advice-add for the same purpose (it's more
> > complicated, but it's arguably better behaved).
> 
> And a quick search seems to indicate that this `interactive-form`
> property is not used anywhere (not within Emacs, not within GNU ELPA,
> and not within the few other Elisp packages I had lying around for
> a quick search).
> 
> Maybe, rather than document it, we should obsolete it?

Why?  Is the existence of this property causing some problem?

Seems like it could be useful (and simple to use) in code
generation or manipulation.  You can't advise a function
that doesn't exist yet.

(To be clear, I haven't used this property.  I have used
the function of the same name, however.)

---

BTW, in the Elisp manual we have 2 index entries for this,
with pretty much the same text (shared prefix) and different
targets.  If we want two entries, for the different targets,
perhaps the entries should not be so similar?

* interactive-form property:         Defining Commands.   (line  16)
* interactive-form, symbol property: Using Interactive.   (line  21)

There is even a third entry, which might appear to fall into
the same boat, but it in fact refers to the function of the
same name:

* interactive-form:                  Using Interactive.   (line 129)

If we want to distinguish function from property in the index
entries, then perhaps the function entry should be something
like `interactive-form, function'.

Re: `interactive-form` symbol property

[Stefan Monnier]

> You can't advise a function that doesn't exist yet.

Yes, you can.

> (To be clear, I haven't used this property.  I have used
> the function of the same name, however.)

The function of the same name is "unrelated" in the sense that I am
definitely not suggesting we obsolete the `interactive-form` function.


        Stefan

RE: `interactive-form` symbol property

[Drew Adams]

> > You can't advise a function that doesn't exist yet.
> Yes, you can.

True; forgot that.  Subtract one from the reasons not
to deprecate it. ;-)

> > (To be clear, I haven't used this property.
> > I have used the function of the same name, however.)
> 
> The function of the same name is "unrelated" in the sense that I am
> definitely not suggesting we obsolete the `interactive-form` function.

Understood.

On the other hand, if we changed `interactive' to always
set the property then that function would be redundant,
even if convenient for mapping, `funcall' etc.  And no,
I'm not suggesting we do that and then deprecate the
function. ;-)  I think both can be useful.

Re: `interactive-form` symbol property (was: [Emacs-diffs] emacs-26 9a53b6d: Say how to override a primitive interactive spec)

[Radon Rosborough]

> You can't advise a function that doesn't exist yet.

Actually, you can. Check it out:

    (advice-add #'nonexistent-function :before
                (lambda ()
                  (message "The advice works!")))

    (defun nonexistent-function ()
      (message "The original function was called."))

    (nonexistent-function)

Re: `interactive-form` symbol property

[Basil L. Contovounesios]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

>>> +If you wish to override a primitive interactive specification, just
>>> +set the @code{interactive-form} property of the primitive function's
>>> +symbol (@pxref{Using Interactive}).  There is no need to edit C code
>>> +and recompile Emacs.
>> You can also use advice-add for the same purpose (it's more
>> complicated, but it's arguably better behaved).
>
> And a quick search seems to indicate that this `interactive-form`
> property is not used anywhere (not within Emacs, not within GNU ELPA,
> and not within the few other Elisp packages I had lying around for
> a quick search).
>
> Maybe, rather than document it, we should obsolete it?

FWIW, I use it in a handful of places in my user-init-file to avoid
copying the interactive spec of some command I'm mimicking.  As a poor
example, I've written a couple of commands akin to browse-url, whose
interactive-form I set to the value of (interactive-form 'browse-url).

This is obviously no reason to hold back on obsoleting the property, but
I'm still curious whether there's another way to be as lazy as I
currently am about copying interactive specs in this way.

-- 
Basil

Re: `interactive-form` symbol property

[Stefan Monnier]

> FWIW, I use it in a handful of places in my user-init-file to avoid
> copying the interactive spec of some command I'm mimicking.  As a poor
> example, I've written a couple of commands akin to browse-url, whose
> interactive-form I set to the value of (interactive-form 'browse-url).

Interesting case, indeed.

You can do

    (defun my-foo ()
      (interactive (advice-eval-interactive-spec
                    (cadr (interactive-form 'bar))))
      ...)

Maybe we should promote `advice-eval-interactive-spec` to
`eval-interactive-spec`?


        Stefan

Re: `interactive-form` symbol property

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Date: Sun, 24 Jun 2018 11:56:15 -0400
> Cc: Karl Fogel <kfogel@red-bean.com>, emacs-devel@gnu.org
> 
> > FWIW, I use it in a handful of places in my user-init-file to avoid
> > copying the interactive spec of some command I'm mimicking.  As a poor
> > example, I've written a couple of commands akin to browse-url, whose
> > interactive-form I set to the value of (interactive-form 'browse-url).
> 
> Interesting case, indeed.
> 
> You can do
> 
>     (defun my-foo ()
>       (interactive (advice-eval-interactive-spec
>                     (cadr (interactive-form 'bar))))
>       ...)
> 
> Maybe we should promote `advice-eval-interactive-spec` to
> `eval-interactive-spec`?

Any reason you dislike the interactive-form property so much that you
are willing to promote anything else instead? ;-)

Re: `interactive-form` symbol property

[Stefan Monnier]

>> Interesting case, indeed.
>> 
>> You can do
>> 
>>     (defun my-foo ()
>>       (interactive (advice-eval-interactive-spec
>>                     (cadr (interactive-form 'bar))))
>>       ...)
>> 
>> Maybe we should promote `advice-eval-interactive-spec` to
>> `eval-interactive-spec`?
> Any reason you dislike the interactive-form property so much that you
> are willing to promote anything else instead? ;-)

The main reason is NIH, of course.

But more generally when we have a mechanism (advice) that provides
a superset of the other (interactive-form), I think it's always
worthwhile to try and see if we really need to keep both.


        Stefan

Re: `interactive-form` symbol property

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Cc: contovob@tcd.ie, kfogel@red-bean.com, emacs-devel@gnu.org
> Date: Mon, 25 Jun 2018 08:32:45 -0400
> 
> > Any reason you dislike the interactive-form property so much that you
> > are willing to promote anything else instead? ;-)
> 
> The main reason is NIH, of course.

Of course ;-)

> But more generally when we have a mechanism (advice) that provides
> a superset of the other (interactive-form), I think it's always
> worthwhile to try and see if we really need to keep both.

Supersets frequently impose overhead, because they try to solve a more
general problem.  Don't we have some overhead of this kind in this
case?

Re: `interactive-form` symbol property

[Stefan Monnier]

> Supersets frequently impose overhead, because they try to solve a more
> general problem.  Don't we have some overhead of this kind in this
> case?

Yes, there can be many reasons to keep more than one mechanism.

I'm not sure exactly what prompted me to grep for it, but I was actually
very surprised to see 0 uses of it.

It is this utter lack of use which made me feel that we should probably
obsolete the mechanism, because even if it may be more convenient for
some corner cases, these corner cases are negligible.


        Stefan

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Date: Sun, 24 Jun 2018 09:42:39 -0400
> Cc: Karl Fogel <kfogel@red-bean.com>
> 
> > +If you wish to override a primitive interactive specification, just
> > +set the @code{interactive-form} property of the primitive function's
> > +symbol (@pxref{Using Interactive}).  There is no need to edit C code
> > +and recompile Emacs.
> 
> You can also use advice-add for the same purpose (it's more
> complicated, but it's arguably better behaved).

And I wonder whether this text belongs to the "Internals" appendix.  I
think its discoverability there will be too low.  Why not put it in
"Using Interactive", instead of cross-referencing there?

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

[Karl Fogel]

Eli Zaretskii <eliz@gnu.org> writes:
>> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
>> Date: Sun, 24 Jun 2018 09:42:39 -0400
>> Cc: Karl Fogel <kfogel@red-bean.com>
>> 
>> > +If you wish to override a primitive interactive specification, just
>> > +set the @code{interactive-form} property of the primitive function's
>> > +symbol (@pxref{Using Interactive}).  There is no need to edit C code
>> > +and recompile Emacs.
>> 
>> You can also use advice-add for the same purpose (it's more
>> complicated, but it's arguably better behaved).
>
>And I wonder whether this text belongs to the "Internals" appendix.  I
>think its discoverability there will be too low.  Why not put it in
>"Using Interactive", instead of cross-referencing there?

When you say "this text", are you referring to the new text I just added on the emacs-26 branch in commit 9a53b6d426 (quoted above), or to Stefan's proposed new text (not yet written) about recommending `advice-add' instead?

I'm pretty sure you meant the latter, but I wanted to make sure of that before commenting further.

Best regards,
-Karl

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

[Eli Zaretskii]

> From: Karl Fogel <kfogel@red-bean.com>
> Cc: Stefan Monnier <monnier@IRO.UMontreal.CA>,  emacs-devel@gnu.org
> Date: Sun, 24 Jun 2018 17:09:51 -0500
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> >> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> >> Date: Sun, 24 Jun 2018 09:42:39 -0400
> >> Cc: Karl Fogel <kfogel@red-bean.com>
> >> 
> >> > +If you wish to override a primitive interactive specification, just
> >> > +set the @code{interactive-form} property of the primitive function's
> >> > +symbol (@pxref{Using Interactive}).  There is no need to edit C code
> >> > +and recompile Emacs.
> >> 
> >> You can also use advice-add for the same purpose (it's more
> >> complicated, but it's arguably better behaved).
> >
> >And I wonder whether this text belongs to the "Internals" appendix.  I
> >think its discoverability there will be too low.  Why not put it in
> >"Using Interactive", instead of cross-referencing there?
> 
> When you say "this text", are you referring to the new text I just added on the emacs-26 branch in commit 9a53b6d426 (quoted above), or to Stefan's proposed new text (not yet written) about recommending `advice-add' instead?
> 
> I'm pretty sure you meant the latter, but I wanted to make sure of that before commenting further.

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.

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

[Karl Fogel]

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

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

[Karl Fogel]

I wrote:
>One route might be to just put a "(@pxref{Using interactive})" at the
>end of the sentence [...] 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.

Slept on it and realized that's a better solution (and also likely what you originally meant).  Eli, if this looks like a good doc patch to you I'll install it:

--- doc/lispref/internals.texi
+++ doc/lispref/internals.texi
@@ -726,7 +726,8 @@ Writing Emacs Primitives
 @cindex interactive specification in primitives
 @item interactive
 This is an interactive specification, a string such as might be used
-as the argument of @code{interactive} in a Lisp function.  In the case
+as the argument of @code{interactive} in a Lisp function 
+(@pxref{Using Interactive}).  In the case
 of @code{or}, it is 0 (a null pointer), indicating that @code{or}
 cannot be called interactively.  A value of @code{""} indicates a
 function that should receive no arguments when called interactively.
@@ -743,11 +744,6 @@ Writing Emacs Primitives
 @end group
 @end example
 
-If you wish to override a primitive interactive specification, just
-set the @code{interactive-form} property of the primitive function's
-symbol (@pxref{Using Interactive}).  There is no need to edit C code
-and recompile Emacs.
-
 @item doc
 This is the documentation string.  It uses C comment syntax rather
 than C string syntax because comment syntax requires nothing special

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

[Eli Zaretskii]

> From: Karl Fogel <kfogel@red-bean.com>
> Cc: monnier@IRO.UMontreal.CA,  emacs-devel@gnu.org
> Date: Mon, 25 Jun 2018 07:43:58 -0500
> 
> I wrote:
> >One route might be to just put a "(@pxref{Using interactive})" at the
> >end of the sentence [...] 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.
> 
> Slept on it and realized that's a better solution (and also likely what you originally meant).  Eli, if this looks like a good doc patch to you I'll install it:

Yes, thank you very much.