bug#17569: 24.4.50; doc of "wrapper hooks"

bug#17569: 24.4.50; doc of "wrapper hooks"

[Drew Adams]

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

bug#17569: 24.4.50; doc of "wrapper hooks"

[Glenn Morris]

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

bug#17569: 24.4.50; doc of "wrapper hooks"

[Drew Adams]

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

bug#17569: 24.4.50; doc of "wrapper hooks"

[Stefan Monnier]

> 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

bug#17569: 24.4.50; doc of "wrapper hooks"

[Drew Adams]

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

bug#17569: 24.4.50; doc of "wrapper hooks"

[Eli Zaretskii]

> Date: Sat, 24 May 2014 08:03:26 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 17569@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.

bug#17569: 24.4.50; doc of "wrapper hooks"

[Drew Adams]

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

bug#17569: 24.4.50; doc of "wrapper hooks"

[Stefan Monnier]

> 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

bug#17569: 24.4.50; doc of "wrapper hooks"

[Drew Adams]

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.

bug#17569: 24.4.50; doc of "wrapper hooks"

[Glenn Morris]

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.

bug#17569: 24.4.50; doc of "wrapper hooks"

[Stefan Monnier]

> 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