bug#16491: 24.3.50; ?REGRESSION: `defadvice' doc removed from Elisp manual

[Drew Adams <drew.adams@oracle.com>]

> >> No, we don't document everything, and since documenting is advertising
> >> we only document those things which we want people to use.
> 
> Moving the documentation to a "deprecated" section --- or even a
> separate elisp manual for deprecated functionality --- woudl be a good
> compromise.

Those were already suggested and rejected.

It should not be too difficult, and would be really helpful to users, to
extract the existing advice doc as a separate manual, and to link to (and
from) it from (and to) the new advice section in the Elisp manual.

> > How about documenting the things those people want to use?  I, for one,
> > need defadvice (in CC Mode), and the message coming out is that the
> > upcoming Emacs might not be an optimal development platform the way the
> > current Emacs is.
> >
> > Also, how are we encouraging people to convert defadvice to the new
> > replacement functions if they can't easily access the former's
> > documentation?

That was my main point: deprecation involves pointing the way forward, and
a direction implies a vector: FROM here TO there.  In *detail*, not just
"`defadvice' is gone now; `add-function' was added to replace it."

Deprecation should always either explicitly identify a specific replacement
or explicitly state that there is no replacement - for *each* thingie
deprecated and for each of its features/functionalities.

IOW, either (1) say what, in the new replaces what in the old - e.g., use
(new) B instead of (deprecated) A or else (2) state that there is nothing
in the new that replaces X of the old (a loss of functionality, which
might or might not be important).

Why?  Because during deprecation you are *still supporting* the old, and
as Alan emphasized, you are indicating how to move toward the new, which
serves as encouragement to do so.  The point of deprecation is to help
users move forward.

> What if we did it the other way around and provided a downlevel- and
> XEmacs-compatible add-function implementation written in terms of old
> defadvice?

That would be fine too - it would ensure backward compatibility, but I
do not see that happening, do you?

The attitude seems to be to simply turn a blind eye toward what has long
existed (and still exists, BTW).