bug#16402: 24.3.50; Document nadvice.el stuff in Elisp manual before Emacs 24.4

[Drew Adams]

> >> As the author of nadvice.el, I would have thought that it was
> >> incumbent upon you to provide adequate documentation. A rationale
> >> to explain why the existing advice package needs changing would
> >> also be helpful.
> >
> > In Stefan's defence this is him saying help me out. I am sure as
> > the maintainer of emacs he has plenty in his plate that some
> > lower-priority tasks may have to fall in others hands ;)
> 
> It'd be easier to document nadvice if there were a clear reason for
> it to exist. Regular advice works fine and has for a long time. It's
> very well documented has many useful features. It integrates with
> help.  It supports various interactive commands. I have no plans
> to use nadvice myself any time soon and oppose deprecating regular
> advice.

1. I suspect that there is some misunderstanding here.  Let me try
to clear some of it up, if so.

I filed the bug report, because Stefan often suggests to people to
use the new advice system provided by nadvice.el.  He tells them
that the "old", `defadvice' system is on the way out (will be
deprecated at some point).  I noticed that currently the only
advice system documented in the Elisp manual is the "old" one,
and there is no mention of it becoming deprecated, and there is
no mention of any other (e.g. nadvice.el) advice system.
The purpose of the bug was to get the new policy reflected in the
Elisp manual.

Glenn closed the bug, reminding me that this new feature is
flagged in the NEWS file as something that needs to be documented
before the Emacs 24.4 release.  IOW, the bug report was not needed
(so it is noise) - the feature is anyway slated to be documented.

Does that help clarify things?  The use of nadvice functionality
does need to be documented in the Elisp manual for 24.4, but they
already plan to do that.  If someone wants to help by submitting
a patch to the manual, they are welcome to do so.  That,
apparently, is Stefan's message here.

2. As far as I know (but someone will correct me if I'm wrong),
Stefan has already decided to deprecate the use of defadvice, like
it or not.  I have filed other bugs for defadvice, and he has made
it clear for at least some that they won't be fixed, saying:
"I have no interest in improving advice.el."

In sum, it seems clear that they do not intend to fix at least
some defadvice problems, since defadvice is anyway on its way out.

Some defadvice bugs I reported recently:

* #14070 - a defadvice doc bug.

* #14130 - another defadvice doc bug.

* #14734 - inability now to update the doc of an advised function
(the new doc is available only by way of a link from the original
doc now).

* #15666 - you can no longer advise a special form.
(You could do that in the past, but that was a while ago - this
regression is unrelated to the move to nadvice.)