* bug#16959: 24.3.50; defadvice docstring out of date
@ 2014-03-07 15:00 Florian Beck
2014-03-10 18:16 ` Glenn Morris
0 siblings, 1 reply; 6+ messages in thread
From: Florian Beck @ 2014-03-07 15:00 UTC (permalink / raw)
To: 16959
The docstring of defadvice says
See Info node `(elisp)Advising Functions' for comprehensive documentation.
This is no longer true. Also, while the old advice mechanism seems to
have been be obsoleted, the help doesn't say so.
BTW, the nadvice info could use some more examples and a note on how to
transition from defadvice. Kind of obvious, I know, but only in hindsight.
--
Florian Beck
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#16959: 24.3.50; defadvice docstring out of date
2014-03-07 15:00 bug#16959: 24.3.50; defadvice docstring out of date Florian Beck
@ 2014-03-10 18:16 ` Glenn Morris
2014-03-11 5:37 ` Florian Beck
0 siblings, 1 reply; 6+ messages in thread
From: Glenn Morris @ 2014-03-10 18:16 UTC (permalink / raw)
To: Florian Beck; +Cc: 16959
Florian Beck wrote:
> The docstring of defadvice says
>
> See Info node `(elisp)Advising Functions' for comprehensive documentation.
>
> This is no longer true.
OK; removed.
> Also, while the old advice mechanism seems to have been be obsoleted,
> the help doesn't say so.
Why do you think it is obsolete?
> BTW, the nadvice info could use some more examples and a note on how
> to transition from defadvice.
I'll leave this report open till someone does that.
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#16959: 24.3.50; defadvice docstring out of date
2014-03-10 18:16 ` Glenn Morris
@ 2014-03-11 5:37 ` Florian Beck
2014-03-12 13:49 ` Stefan Monnier
0 siblings, 1 reply; 6+ messages in thread
From: Florian Beck @ 2014-03-11 5:37 UTC (permalink / raw)
To: Glenn Morris; +Cc: 16959
On 10.03.2014 19:16, Glenn Morris wrote:
> Why do you think it is obsolete?
Because every hint of its existence has been expunged from the
documentation and the new advice seems to offer the same functionality.
>> BTW, the nadvice info could use some more examples and a note on how
>> to transition from defadvice.
>
> I'll leave this report open till someone does that.
Some specifics:
- See the documentation of the old advice: it starts with "altering
the behavior of an existing function" (yeah! that's what I'm here for),
then gives a simple example, a use case ("Suppose you wanted ...").
- In contrast, the beginning of the new "Advising Functions" is a bit
confusing: appropriate setter function? set-process-filter? What are
"such hooks"?
- The difference between add-function and advice-add is not entirely
clear to me: the latter is for the "function cell of a symbol", a "named
function and macros", "macros and autoloaded functions". Which is it? I
can write
(add-function :after (symbol-function 'somefun) 'someadvice)
but should I? I have the feeling I should stick with advice-add unless
dealing with process filters.
- Indeed, it seems the documentation is in the wrong order: from a
user's perspective, advice-add is what she usually wants and
add-function is a special case.
- The docstring of advice-add is useless: it should give me the info I
need when writing an advice, which is in add-function. IMO is should be
the other way around: the fact that you need advice-add for macros, etc
should be mentioned in the docstring of add-function.
- The page title "Advising Primitives" is misleading in the context of
"Advising Functions" and "Advising Named Functions".
- Interactive functions are only discussed in the docstring of
add-function.
- Add some examples that show how arguments work for someone who is
not familiar with &rest and apply.
- How about reimplementing the two examples from the old docu ("A
Simple Advice Example" and "Around Advice")? That would also demonstrate
how to transition to the new mechanism.
--
Florian Beck
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#16959: 24.3.50; defadvice docstring out of date
2014-03-11 5:37 ` Florian Beck
@ 2014-03-12 13:49 ` Stefan Monnier
2014-03-12 16:30 ` Josh
0 siblings, 1 reply; 6+ messages in thread
From: Stefan Monnier @ 2014-03-12 13:49 UTC (permalink / raw)
To: Florian Beck; +Cc: 16959
> Some specifics:
Thanks Florian, this list is very helpful. Just one comment:
> - Indeed, it seems the documentation is in the wrong order: from a user's
> perspective, advice-add is what she usually wants and add-function
> is a special case.
Actually, add-function is likely to become more common with new hooks
using a `*-function' variable modified via add-function rather than
a `*-functions' modified via add-hook.
Stefan
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#16959: 24.3.50; defadvice docstring out of date
2014-03-12 13:49 ` Stefan Monnier
@ 2014-03-12 16:30 ` Josh
2014-03-12 18:41 ` Stefan Monnier
0 siblings, 1 reply; 6+ messages in thread
From: Josh @ 2014-03-12 16:30 UTC (permalink / raw)
To: Stefan Monnier; +Cc: Florian Beck, 16959
[-- Attachment #1: Type: text/plain, Size: 957 bytes --]
On Wed, Mar 12, 2014 at 6:49 AM, Stefan Monnier <monnier@iro.umontreal.ca>wrote:
> > Some specifics:
>
> Thanks Florian, this list is very helpful. Just one comment:
>
> > - Indeed, it seems the documentation is in the wrong order: from a
> user's
> > perspective, advice-add is what she usually wants and add-function
> > is a special case.
>
> Actually, add-function is likely to become more common with new hooks
> using a `*-function' variable modified via add-function rather than
> a `*-functions' modified via add-hook.
Somewhat relatedly, would you consider renaming advice-add to
add-advice (naturally with an alias for backward compatibility)?
It's easier to discover related functionality through tab
completion, apropos, etc. when its names share a common structure.
For example if I was looking for basename functionality and I knew
about file-name-directory, `C-h f file-name- TAB' would lead me to
`file-name-nondirectory' straightaway.
[-- Attachment #2: Type: text/html, Size: 1419 bytes --]
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#16959: 24.3.50; defadvice docstring out of date
2014-03-12 16:30 ` Josh
@ 2014-03-12 18:41 ` Stefan Monnier
0 siblings, 0 replies; 6+ messages in thread
From: Stefan Monnier @ 2014-03-12 18:41 UTC (permalink / raw)
To: Josh; +Cc: Florian Beck, 16959
> Somewhat relatedly, would you consider renaming advice-add to
> add-advice (naturally with an alias for backward compatibility)?
No, that's not an option. I could consider getting rid of the
add-function and remove-function exceptions (i.e. renaming them to
something that starts with "advice-" like everything else in
nadvice.el), but then their "natural" name would probably be
advice-function-add and advice-function-remove, neither of which please
me very much. Especially given the intention to see `add-function' as
a brother to `add-hook'.
Stefan
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2014-03-12 18:41 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-03-07 15:00 bug#16959: 24.3.50; defadvice docstring out of date Florian Beck
2014-03-10 18:16 ` Glenn Morris
2014-03-11 5:37 ` Florian Beck
2014-03-12 13:49 ` Stefan Monnier
2014-03-12 16:30 ` Josh
2014-03-12 18:41 ` Stefan Monnier
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).