all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#16491: 24.3.50; REGRESSION: `defadvice' doc removed from Elisp manual
@ 2014-01-19  6:45 ` Drew Adams
  2014-01-19 16:58   ` bug#16491: 24.3.50; ?REGRESSION: " Alan Mackenzie
  0 siblings, 1 reply; 8+ messages in thread
From: Drew Adams @ 2014-01-19  6:45 UTC (permalink / raw)
  To: 16491

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'





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#16491: 24.3.50; ?REGRESSION: `defadvice' doc removed from Elisp manual
  2014-01-19  6:45 ` bug#16491: 24.3.50; REGRESSION: `defadvice' doc removed from Elisp manual Drew Adams
@ 2014-01-19 16:58   ` Alan Mackenzie
  2014-01-19 20:40     ` Stefan Monnier
  0 siblings, 1 reply; 8+ messages in thread
From: Alan Mackenzie @ 2014-01-19 16:58 UTC (permalink / raw)
  To: gnu-emacs-bug

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






^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#16491: 24.3.50; ?REGRESSION: `defadvice' doc removed from Elisp manual
  2014-01-19 16:58   ` bug#16491: 24.3.50; ?REGRESSION: " Alan Mackenzie
@ 2014-01-19 20:40     ` Stefan Monnier
  2014-01-19 22:32       ` Drew Adams
  0 siblings, 1 reply; 8+ messages in thread
From: Stefan Monnier @ 2014-01-19 20:40 UTC (permalink / raw)
  To: Alan Mackenzie; +Cc: 16491-done

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#16491: 24.3.50; ?REGRESSION: `defadvice' doc removed from Elisp manual
  2014-01-19 20:40     ` Stefan Monnier
@ 2014-01-19 22:32       ` Drew Adams
  2014-01-20  2:31         ` Stefan Monnier
  0 siblings, 1 reply; 8+ messages in thread
From: Drew Adams @ 2014-01-19 22:32 UTC (permalink / raw)
  To: Stefan Monnier, Alan Mackenzie; +Cc: 16491-done

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#16491: 24.3.50; ?REGRESSION: `defadvice' doc removed from Elisp manual
  2014-01-19 22:32       ` Drew Adams
@ 2014-01-20  2:31         ` Stefan Monnier
  2014-01-22 22:11           ` Alan Mackenzie
  0 siblings, 1 reply; 8+ messages in thread
From: Stefan Monnier @ 2014-01-20  2:31 UTC (permalink / raw)
  To: Drew Adams; +Cc: Alan Mackenzie, 16491-done

> 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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#16491: 24.3.50; ?REGRESSION: `defadvice' doc removed from Elisp manual
  2014-01-20  2:31         ` Stefan Monnier
@ 2014-01-22 22:11           ` Alan Mackenzie
  2014-01-22 22:20             ` Daniel Colascione
  0 siblings, 1 reply; 8+ messages in thread
From: Alan Mackenzie @ 2014-01-22 22:11 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: 16491

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#16491: 24.3.50; ?REGRESSION: `defadvice' doc removed from Elisp manual
  2014-01-22 22:11           ` Alan Mackenzie
@ 2014-01-22 22:20             ` Daniel Colascione
  2014-01-22 22:42               ` Drew Adams
  0 siblings, 1 reply; 8+ messages in thread
From: Daniel Colascione @ 2014-01-22 22:20 UTC (permalink / raw)
  To: Alan Mackenzie, Stefan Monnier; +Cc: 16491

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?





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#16491: 24.3.50; ?REGRESSION: `defadvice' doc removed from Elisp manual
  2014-01-22 22:20             ` Daniel Colascione
@ 2014-01-22 22:42               ` Drew Adams
  0 siblings, 0 replies; 8+ messages in thread
From: Drew Adams @ 2014-01-22 22:42 UTC (permalink / raw)
  To: Daniel Colascione, Alan Mackenzie, Stefan Monnier; +Cc: 16491

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2014-01-22 22:42 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
     [not found] <mailman.12294.1390113984.10748.bug-gnu-emacs@gnu.org>
2014-01-19  6:45 ` bug#16491: 24.3.50; REGRESSION: `defadvice' doc removed from Elisp manual Drew Adams
2014-01-19 16:58   ` bug#16491: 24.3.50; ?REGRESSION: " Alan Mackenzie
2014-01-19 20:40     ` Stefan Monnier
2014-01-19 22:32       ` Drew Adams
2014-01-20  2:31         ` Stefan Monnier
2014-01-22 22:11           ` Alan Mackenzie
2014-01-22 22:20             ` Daniel Colascione
2014-01-22 22:42               ` Drew Adams

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.