From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#17569: 24.4.50; doc of "wrapper hooks" Date: Fri, 23 May 2014 15:30:29 -0700 (PDT) Message-ID: <6907e1e1-e802-45cd-adad-917290420cf6@default> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1400884357 18277 80.91.229.3 (23 May 2014 22:32:37 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 23 May 2014 22:32:37 +0000 (UTC) To: 17569@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat May 24 00:32:28 2014 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Wny0q-0003u8-9f for geb-bug-gnu-emacs@m.gmane.org; Sat, 24 May 2014 00:32:28 +0200 Original-Received: from localhost ([::1]:45913 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Wny0p-0007rO-N9 for geb-bug-gnu-emacs@m.gmane.org; Fri, 23 May 2014 18:32:27 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:37517) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Wny0c-0007qF-Li for bug-gnu-emacs@gnu.org; Fri, 23 May 2014 18:32:25 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Wny0R-0003J2-4A for bug-gnu-emacs@gnu.org; Fri, 23 May 2014 18:32:14 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:59438) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Wny0R-0003Ix-0t for bug-gnu-emacs@gnu.org; Fri, 23 May 2014 18:32:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1Wny0Q-0007YM-P9 for bug-gnu-emacs@gnu.org; Fri, 23 May 2014 18:32:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 23 May 2014 22:32:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 17569 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.140088427028942 (code B ref -1); Fri, 23 May 2014 22:32:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 23 May 2014 22:31:10 +0000 Original-Received: from localhost ([127.0.0.1]:58314 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1Wnxza-0007Wh-5U for submit@debbugs.gnu.org; Fri, 23 May 2014 18:31:10 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:35572) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WnxzW-0007W8-NX for submit@debbugs.gnu.org; Fri, 23 May 2014 18:31:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WnxzH-00032C-BF for submit@debbugs.gnu.org; Fri, 23 May 2014 18:31:01 -0400 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:49794) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WnxzH-000328-7q for submit@debbugs.gnu.org; Fri, 23 May 2014 18:30:51 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:37275) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Wnxz8-0007ms-Eh for bug-gnu-emacs@gnu.org; Fri, 23 May 2014 18:30:51 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Wnxyz-0002yY-Li for bug-gnu-emacs@gnu.org; Fri, 23 May 2014 18:30:42 -0400 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:30492) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Wnxyz-0002yT-Bv for bug-gnu-emacs@gnu.org; Fri, 23 May 2014 18:30:33 -0400 Original-Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id s4NMUW4V022683 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Fri, 23 May 2014 22:30:32 GMT Original-Received: from userz7022.oracle.com (userz7022.oracle.com [156.151.31.86]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s4NMUVGv004219 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Fri, 23 May 2014 22:30:31 GMT Original-Received: from abhmp0003.oracle.com (abhmp0003.oracle.com [141.146.116.9]) by userz7022.oracle.com (8.14.5+Sun/8.14.4) with ESMTP id s4NMUTYc006547 for ; Fri, 23 May 2014 22:30:30 GMT X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6691.5000 (x86)] X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:89426 Archived-At: 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 -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=3D/c/Devel/emacs/snapshot/trunk --enable-checking=3Dyes,glyphs 'CFLAGS=3D-O0 -g3' LDFLAGS=3D-Lc:/Devel/emacs/lib 'CPPFLAGS=3D-DGC_MCHECK=3D1 -Ic:/Devel/emacs/include''