* bug#17569: 24.4.50; doc of "wrapper hooks"
@ 2014-05-23 22:30 Drew Adams
2014-05-23 22:45 ` Glenn Morris
0 siblings, 1 reply; 11+ messages in thread
From: Drew Adams @ 2014-05-23 22:30 UTC (permalink / raw
To: 17569
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''
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#17569: 24.4.50; doc of "wrapper hooks"
2014-05-23 22:30 bug#17569: 24.4.50; doc of "wrapper hooks" Drew Adams
@ 2014-05-23 22:45 ` Glenn Morris
2014-05-23 22:53 ` Drew Adams
0 siblings, 1 reply; 11+ messages in thread
From: Glenn Morris @ 2014-05-23 22:45 UTC (permalink / raw
To: 17569
I documented this for an earlier release.
Then it was made obsolete, and the documentation deleted, without
cleaning up references to that documentation.
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#17569: 24.4.50; doc of "wrapper hooks"
2014-05-23 22:45 ` Glenn Morris
@ 2014-05-23 22:53 ` Drew Adams
2014-05-24 3:21 ` Stefan Monnier
0 siblings, 1 reply; 11+ messages in thread
From: Drew Adams @ 2014-05-23 22:53 UTC (permalink / raw
To: Glenn Morris, 17569
> 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.
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#17569: 24.4.50; doc of "wrapper hooks"
2014-05-23 22:53 ` Drew Adams
@ 2014-05-24 3:21 ` Stefan Monnier
2014-05-24 15:03 ` Drew Adams
2014-05-24 20:09 ` Drew Adams
0 siblings, 2 replies; 11+ messages in thread
From: Stefan Monnier @ 2014-05-24 3:21 UTC (permalink / raw
To: Drew Adams; +Cc: 17569
> 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
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#17569: 24.4.50; doc of "wrapper hooks"
2014-05-24 3:21 ` Stefan Monnier
@ 2014-05-24 15:03 ` Drew Adams
2014-05-24 15:16 ` Eli Zaretskii
2014-05-24 20:09 ` Drew Adams
1 sibling, 1 reply; 11+ messages in thread
From: Drew Adams @ 2014-05-24 15:03 UTC (permalink / raw
To: Stefan Monnier; +Cc: 17569
> > 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?
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#17569: 24.4.50; doc of "wrapper hooks"
2014-05-24 15:03 ` Drew Adams
@ 2014-05-24 15:16 ` Eli Zaretskii
0 siblings, 0 replies; 11+ messages in thread
From: Eli Zaretskii @ 2014-05-24 15:16 UTC (permalink / raw
To: Drew Adams; +Cc: 17569
> 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.
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#17569: 24.4.50; doc of "wrapper hooks"
2014-05-24 3:21 ` Stefan Monnier
2014-05-24 15:03 ` Drew Adams
@ 2014-05-24 20:09 ` Drew Adams
1 sibling, 0 replies; 11+ messages in thread
From: Drew Adams @ 2014-05-24 20:09 UTC (permalink / raw
To: Stefan Monnier; +Cc: 17569
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.
^ permalink raw reply [flat|nested] 11+ messages in thread
[parent not found: <<6907e1e1-e802-45cd-adad-917290420cf6@default>]
end of thread, other threads:[~2014-05-24 21:35 UTC | newest]
Thread overview: 11+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2014-05-23 22:30 bug#17569: 24.4.50; doc of "wrapper hooks" Drew Adams
2014-05-23 22:45 ` Glenn Morris
2014-05-23 22:53 ` Drew Adams
2014-05-24 3:21 ` Stefan Monnier
2014-05-24 15:03 ` Drew Adams
2014-05-24 15:16 ` Eli Zaretskii
2014-05-24 20:09 ` Drew Adams
[not found] <<6907e1e1-e802-45cd-adad-917290420cf6@default>
[not found] ` <<9pmwe8t8qq.fsf@fencepost.gnu.org>
[not found] ` <<17297117-eeea-4bca-a9a3-a08cd966d1fb@default>
[not found] ` <<jwvbnun50ay.fsf-monnier+emacsbugs@gnu.org>
[not found] ` <<6bad204d-c3d7-4630-aa7f-1a09288f6ad4@default>
[not found] ` <<83ppj3jjfq.fsf@gnu.org>
2014-05-24 15:57 ` Drew Adams
2014-05-24 16:21 ` Stefan Monnier
2014-05-24 20:56 ` Glenn Morris
2014-05-24 21:35 ` Stefan Monnier
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.