GNU bug report logs - #17569
24.4.50; doc of "wrapper hooks"

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 17569 in the body.
You can then email your comments to 17569 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.4.50; doc of "wrapper hooks"
Date: Fri, 23 May 2014 15:30:29 -0700 (PDT)

At least two places in the Elisp manual describe a variable as a
"wrapper hook", and send readers off to node `Running Hooks' for more
information.  Alas, there is nothing in that node either about what a
"wrapper hook" is or how it works.

And there is no index entry that matches "wrapper".  OK, so grepping
the Lisp sources for, say, `filter-buffer-substring-functions', one
of the vars whose doc tells you it is a "wrapper hook", gets you to
the Lisp definition of `buffer-substring--filter', a so-called
"internal" function.  And there you discover a macro called
`with-wrapper-hook'.

Finally, the doc for that macro tells you something useful about
"wrapper hooks" (without using the term, however).

It would be helpful to Elisp users to document this macro in the
Elisp manual.  Alas, what else do we read in its doc string?

  This macro is obsolete since 24.4;
  use a <foo>-function variable modified by `add-function'.

On n'arrete pas le progres !  Introduced in Emacs 23.  Never
documented in the manual, and made obsolete in Emacs 24.

Please index and document the concept of "wrapper hook", in the
Elisp manual.  Or whatever this month's fashionable replacement
is for this. Readers of the doc about `abbrev-expand-functions'
or `filter-buffer-substring-functions' should not have to go
fishing into the source code to understand what the doc means
when it says that such a var is a "wrapper hook".

In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-05-17 on ODIEONE
Bzr revision: 117119 eggert <at> cs.ucla.edu-20140517081131-ugu7ociaoec2xk7y
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

Message #8 received at 17569 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: 17569 <at> debbugs.gnu.org
Subject: Re: bug#17569: 24.4.50; doc of "wrapper hooks"
Date: Fri, 23 May 2014 18:45:17 -0400

I documented this for an earlier release.
Then it was made obsolete, and the documentation deleted, without
cleaning up references to that documentation.

Message #11 received at 17569 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Glenn Morris <rgm <at> gnu.org>, 17569 <at> debbugs.gnu.org
Subject: RE: bug#17569: 24.4.50; doc of "wrapper hooks"
Date: Fri, 23 May 2014 15:53:46 -0700 (PDT)

> I documented this for an earlier release.
> Then it was made obsolete, and the documentation deleted, without
> cleaning up references to that documentation.

OK, thanks for the history.  But if those variables whose doc
refers to "wrapper hook" still have values that are a list of
functions that are, in fact, wrapper hooks, then the concept
still needs to be explained, one way or another.

Message #14 received at 17569 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Glenn Morris <rgm <at> gnu.org>, 17569 <at> debbugs.gnu.org
Subject: Re: bug#17569: 24.4.50; doc of "wrapper hooks"
Date: Fri, 23 May 2014 23:21:49 -0400

> OK, thanks for the history.  But if those variables whose doc
> refers to "wrapper hook" still have values that are a list of
> functions that are, in fact, wrapper hooks, then the concept
> still needs to be explained, one way or another.

No, such vars should be obsolete as well (and hence removed from the
doc).


        Stefan

Message #17 received at 17569 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Glenn Morris <rgm <at> gnu.org>, 17569 <at> debbugs.gnu.org
Subject: RE: bug#17569: 24.4.50; doc of "wrapper hooks"
Date: Sat, 24 May 2014 08:03:26 -0700 (PDT)

> > OK, thanks for the history.  But if those variables whose doc
> > refers to "wrapper hook" still have values that are a list of
> > functions that are, in fact, wrapper hooks, then the concept
> > still needs to be explained, one way or another.
> 
> No, such vars should be obsolete as well (and hence removed
> from the doc).

So not only is something like `buffer-substring-filters' to be
considered obsolete (the case since Emacs 24), but also a var
like `filter-buffer-substring', whose doc refers to the fact
(since Emacs 24) that it uses "obsolete variable
`buffer-substring-filters'."

And what about a function, such as `filter-buffer-substring',
whose implementation and doc string makes use of such a var?
What is being recommended now for someone who wants the
functionality of `filter-buffer-substring' - just roll your own?

Message #20 received at 17569 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 17569 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#17569: 24.4.50; doc of "wrapper hooks"
Date: Sat, 24 May 2014 18:16:41 +0300

> Date: Sat, 24 May 2014 08:03:26 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 17569 <at> debbugs.gnu.org
> 
> And what about a function, such as `filter-buffer-substring',
> whose implementation and doc string makes use of such a var?
> What is being recommended now for someone who wants the
> functionality of `filter-buffer-substring' - just roll your own?

Using obsolete variables or functions doesn't automatically make their
users obsolete.  It just means they need to be fixed by changing their
implementation to use the alternative non-obsolete replacements.
Therefore, there's no need to stop using those APIs that use obsolete
vars.

Message #23 received at 17569 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 17569 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: RE: bug#17569: 24.4.50; doc of "wrapper hooks"
Date: Sat, 24 May 2014 08:57:52 -0700 (PDT)

> > And what about a function, such as `filter-buffer-substring',
> > whose implementation and doc string makes use of such a var?
> > What is being recommended now for someone who wants the
> > functionality of `filter-buffer-substring' - just roll your own?
> 
> Using obsolete variables or functions doesn't automatically make their
> users obsolete.  It just means they need to be fixed by changing their
> implementation to use the alternative non-obsolete replacements.
> Therefore, there's no need to stop using those APIs that use obsolete
> vars.

Yes, we know that.  And you'll notice that I didn't say anything about
the many callers of `filter-buffer-substring' or about code that uses
`filter-buffer-substring-functions'.

However, I see now that I was mistaken about `filter-buffer-substring'
using obsolete variable `filter-buffer-substring-functions'.  It uses
the replacement function `filter-buffer-substring-function' (no `s')
instead.

That was my main concern: what was being recommended as a replacement
for `filter-buffer-substring'.  I see now that it is not being made
obsolete by making `filter-buffer-substring-functions' obsolete.

Message #28 received at 17569-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: 17569-done <at> debbugs.gnu.org
Subject: Re: bug#17569: 24.4.50; doc of "wrapper hooks"
Date: Sat, 24 May 2014 12:21:51 -0400

> However, I see now that I was mistaken about `filter-buffer-substring'
> using obsolete variable `filter-buffer-substring-functions'.  It uses
> the replacement function `filter-buffer-substring-function' (no `s')
> instead.

Thanks, closing,


        Stefan

Message #31 received at 17569 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Glenn Morris <rgm <at> gnu.org>, 17569 <at> debbugs.gnu.org
Subject: RE: bug#17569: 24.4.50; doc of "wrapper hooks"
Date: Sat, 24 May 2014 13:09:03 -0700 (PDT)

s> such vars should be obsolete as well (and hence removed
s> from the doc).

You closed the bug.  Has this been removed from the doc?

g> I documented this for an earlier release.
g> Then it was made obsolete, and the documentation deleted,
g> without cleaning up references to that documentation.

Have such references been cleaned up now?

When closing a bug, it's good to mention whether it has in fact
been fixed.

Message #34 received at 17569 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: 17569 <at> debbugs.gnu.org
Cc: monnier <at> iro.umontreal.ca
Subject: Re: bug#17569: 24.4.50; doc of "wrapper hooks"
Date: Sat, 24 May 2014 16:56:40 -0400

Stefan Monnier wrote:

> Thanks, closing,

-- Variable: filter-buffer-substring-functions
     This variable is a wrapper hook (*note Running Hooks::), whose

-- Variable: abbrev-expand-functions
     This is a wrapper hook (*note Running Hooks::) run around the


Since you deleted the explanation of wrapper hooks, these xrefs are
pointless. Perhaps you want to delete the documentation of the obsolete
wrapper hooks too. (Though in general I don't understand why you delete
documentation of obsolete features, rather than simply adding a "The
following refers to an obsolete feature. In new code, use FOO" or
somesuch at the start.)

filter-buffer-substring-function, completion-in-region-function,
abbrev-expand-function don't seem to be documented. Only the obsolete
forms are documented.

Message #37 received at 17569 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 17569 <at> debbugs.gnu.org
Subject: Re: bug#17569: 24.4.50; doc of "wrapper hooks"
Date: Sat, 24 May 2014 17:35:13 -0400

> wrapper hooks too. (Though in general I don't understand why you delete
> documentation of obsolete features, rather than simply adding a "The
> following refers to an obsolete feature. In new code, use FOO" or
> somesuch at the start.)

I don't think it's worth documenting that which we discourage.  But if
you want to document how to replace such code with the new feature,
that's fine.

> filter-buffer-substring-function, completion-in-region-function,
> abbrev-expand-function don't seem to be documented.

`completion-in-region-function' is probably not worth documenting.
But the filter-buffer-substring-functions and abbrev-expand-functions
documentation should be changed indeed to document
filter-buffer-substring-function and abbrev-expand-function instead.


        Stefan

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.