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

Previous Next

Full log

View this message in rfc822 format

From: Drew Adams <drew.adams <at> oracle.com>
To: 17569 <at> debbugs.gnu.org
Subject: bug#17569: 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''

Previous Next

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