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

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

[Drew Adams]

Elisp manual node `Advising Emacs Lisp Functions' has been rewritten to
include the new `add-function' stuff.  It is fine to document that new
feature.

What's not fine is to simply remove all of the doc about the traditional
`defadvice' advice system.  Even if that feature is to be deprecated,
its doc should remain until it is desupported.  If this removal is not
a temporary oversight (mistake) then it is quite misguided.  It hurts
Emacs users.

The Elisp manual should continue to be usable to help users code
`defadvice' advice, in addition to `add-function' advice.  As one use
case, some users will use Emacs 24.4 to write or maintain code for
older or multiple Emacs versions.

Normally there is a reasonably long transition period before a feature,
especially a major feature such as `defadvice', is desupported.  And
until desupport, the deprecated feature remains SUPPORTED - in
particular, by continuing to provide users with its reference doc.


In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2014-01-17 on ODIEONE
Bzr revision: 116059 michael.albinus@gmx.de-20140117182409-gz695p2c951idlee
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/binary --enable-checking=yes,glyphs
 'CFLAGS=-O0 -g3' LDFLAGS=-Lc:/Devel/emacs/lib
 CPPFLAGS=-Ic:/Devel/emacs/include'

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

[Alan Mackenzie]

Drew Adams <drew.adams@oracle.com> wrote:
> Elisp manual node `Advising Emacs Lisp Functions' has been rewritten to
> include the new `add-function' stuff.  It is fine to document that new
> feature.

> What's not fine is to simply remove all of the doc about the traditional
> `defadvice' advice system.  Even if that feature is to be deprecated,
> its doc should remain until it is desupported.  If this removal is not
> a temporary oversight (mistake) then it is quite misguided.  It hurts
> Emacs users.

+1.  defadvice will remain absolutely necessary for Emacs hackers
maintaining packages with the exception of those who are only targetting
recent GNU Emacsen.

> The Elisp manual should continue to be usable to help users code
> `defadvice' advice, in addition to `add-function' advice.  As one use
> case, some users will use Emacs 24.4 to write or maintain code for
> older or multiple Emacs versions.

Not a few users, either.  Without documentation, defadvice is unusable and
packages using it are unmaintainable.  The doc string of defadvice, by
itself, is inadequate; for example, it doesn't say anything about ad-do-it.

Besides, there are 34 files in .../lisp containing the string "defadvice".
This feature is clearly widely used, even in the Emacs sources.

> Normally there is a reasonably long transition period before a feature,
> especially a major feature such as `defadvice', is desupported.  And
> until desupport, the deprecated feature remains SUPPORTED - in
> particular, by continuing to provide users with its reference doc.

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[Stefan Monnier]

>> What's not fine is to simply remove all of the doc about the traditional
>> `defadvice' advice system.

Totally agreed.  Which is why I kept the 60KB of docs in the
Commentary section of advice.el.


        Stefan

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

[Drew Adams]

> >> What's not fine is to simply remove all of the doc about
> >> the traditional `defadvice' advice system.
> 
> Totally agreed.  Which is why I kept the 60KB of docs in the
> Commentary section of advice.el.

That is not the user doc.  It is good that you at least
saved that information somewhere.  Such a concession!  60KB!

But it is not sufficient to just stuff that information into
a Lisp-file Commentary somewhere.  At the very least, it
should be available as an Info manual distributed with Emacs.

The fact that you felt it was worth mentioning how many KB
this doc weighs betrays your attitude about it, and perhaps
about user doc in general.

But you have already expressed yourself on that, stating in
the past that users don't need _any_ doc, and the code needs
no comments - the code itself suffices and is the real doc.
When will you bury all of the doc in Lisp comments?  Why
stop now with `defadvice'?

This is an anti-user attitude that is quite inappropriate,
especially for someone charged with leading Emacs development.
Too bad.

At least I know where to find the `defadvice' doc now - thank
you for that tip.  But poor Emacs.

Oh, BTW, did you give a _reason_ for carving this out of the
doc and moving it to a Lisp comment?  Did you propose that
possibility for emacs-devel discussion and present technical
or user-level arguments supporting it?

Did I miss those reasons somehow?  No?  I didn't think so.

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

[Stefan Monnier]

> At the very least, it should be available as an Info manual
> distributed with Emacs.

No, we don't document everything, and since documenting is advertising
we only document those things which we want people to use.


        Stefan

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

[Alan Mackenzie]

On Sun, Jan 19, 2014 at 09:31:07PM -0500, Stefan Monnier wrote:
> > At the very least, it [documentation of defadvice] should be
> > available as an Info manual distributed with Emacs.

> No, we don't document everything, and since documenting is advertising
> we only document those things which we want people to use.

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?

>         Stefan

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[Daniel Colascione]

On 01/22/2014 02:11 PM, Alan Mackenzie wrote:
> On Sun, Jan 19, 2014 at 09:31:07PM -0500, Stefan Monnier wrote:
>>> At the very least, it [documentation of defadvice] should be
>>> available as an Info manual distributed with Emacs.
>
>> 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.

> 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?

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?

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

[Drew Adams]

> >> 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).