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

[Stefan Monnier]

> A rationale to explain why the existing advice package needs changing
> would also be helpful.

Here are some of the reasons:
- I implemented add-function, which is a different feature not provided
  by advice.el.
- implementing advice-add on top of the add-function code takes just 8KB.
- by contrast advice.el was 150KB (now reduced to 130KB by using nadvice.el).
- once add-function is documented, documenting advice-add is similarly
  much simpler than defadvice.
- advice-add fixes several problems in defadvice:
  - the fact that defadvice does not expand macros in its code unless
    you explicitly ask for the advice to be compiled.
  - the fact that defadvice only compiles either too early (via the
    "precompilation", which is rarely used and rightly so) or too late
    (when activating the advice), so you typically won't get any
    byte-compiler warnings.
  - ad-do-it and ad-return-value in `around' advice don't work the way
    people intuitively expect them to.
  - ad-activate and ad-deactivate have global effects (i.e. they affect
    all advices applied to that symbol), so any use of those within
    a package is a bug in the waiting.
  - the distinction between enabling/disabling and
    activating/deactivating is "too subtle" for the users of defadvice:
    it's really just a reflection of the underlying implementation.
  - advice.el is much too large to be preloaded, so for example debug.el
    refrained from using it.
    
> As an aside, storing raw bytecode in advice--where-alist seems hackish.

Agreed.

> Is it not possible to construct this byte code from something more
> human readable at compile time ?

It's possible, but the pre-existing code which does something like that
is in the byte-compiler and does not provide quite the right feature.
It didn't seem worth the trouble to restructure that code just for that
one use.


        Stefan