From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#24540: 25.1; doc of `abbrev-expand-function(s)', "wrapper hooks",... Date: Mon, 26 Sep 2016 19:04:04 +0300 Message-ID: <83d1jqd4wb.fsf@gnu.org> References: <39d1a887-a19f-40ba-9b00-84e27f2606ce@default> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1474905921 10946 195.159.176.226 (26 Sep 2016 16:05:21 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 26 Sep 2016 16:05:21 +0000 (UTC) Cc: 24540-done@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Sep 26 18:05:16 2016 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1boYP5-000244-0Q for geb-bug-gnu-emacs@m.gmane.org; Mon, 26 Sep 2016 18:05:15 +0200 Original-Received: from localhost ([::1]:45519 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1boYP2-0003AG-Ga for geb-bug-gnu-emacs@m.gmane.org; Mon, 26 Sep 2016 12:05:12 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:56059) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1boYOw-00038C-JI for bug-gnu-emacs@gnu.org; Mon, 26 Sep 2016 12:05:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1boYOs-0003M3-2b for bug-gnu-emacs@gnu.org; Mon, 26 Sep 2016 12:05:05 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:58635) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1boYOr-0003Ls-Vr for bug-gnu-emacs@gnu.org; Mon, 26 Sep 2016 12:05:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1boYOr-0003DN-Pi for bug-gnu-emacs@gnu.org; Mon, 26 Sep 2016 12:05:01 -0400 Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-To: bug-gnu-emacs@gnu.org Resent-Date: Mon, 26 Sep 2016 16:05:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: cc-closed 24540 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Mail-Followup-To: 24540@debbugs.gnu.org, eliz@gnu.org, drew.adams@oracle.com Original-Received: via spool by 24540-done@debbugs.gnu.org id=D24540.147490587012309 (code D ref 24540); Mon, 26 Sep 2016 16:05:01 +0000 Original-Received: (at 24540-done) by debbugs.gnu.org; 26 Sep 2016 16:04:30 +0000 Original-Received: from localhost ([127.0.0.1]:36591 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1boYOL-0003CS-SP for submit@debbugs.gnu.org; Mon, 26 Sep 2016 12:04:30 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:36722) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1boYOK-0003CF-2O for 24540-done@debbugs.gnu.org; Mon, 26 Sep 2016 12:04:28 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1boYOB-00036w-Lp for 24540-done@debbugs.gnu.org; Mon, 26 Sep 2016 12:04:22 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:46771) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1boYOB-00036X-Iz; Mon, 26 Sep 2016 12:04:19 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:1278 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1boYO8-0008JV-U4; Mon, 26 Sep 2016 12:04:18 -0400 In-reply-to: <39d1a887-a19f-40ba-9b00-84e27f2606ce@default> (message from Drew Adams on Sun, 25 Sep 2016 07:53:30 -0700 (PDT)) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.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" Xref: news.gmane.org gmane.emacs.bugs:123702 Archived-At: > Date: Sun, 25 Sep 2016 07:53:30 -0700 (PDT) > From: Drew Adams > > Let's check the doc, starting with `expand-abbrev': > > "Calls `abbrev-expand-function' with no argument to do the work, and > returns whatever it does." Actually, it says this: "Expand the abbrev before point, if there is an abbrev there. Effective when explicitly called even when `abbrev-mode' is nil. Before doing anything else, runs `pre-abbrev-expand-hook'. Calls `abbrev-expand-function' with no argument to do the work, and returns whatever it does. (This should be the abbrev symbol if expansion occurred, else nil.)" IOW, it (1) describes what the command does, (2) mentions the function it calls to do the actual work, and (3) explains what "whatever" means. Quite a lot less mysterious than what the single sentence you presented might convey, IMO. > (It should say that it calls the _value of variable_ > `abbrev-expand-function'.) Yes, fixed. > So we look at `abbrev-expand-function', which tells us that the default > value is `abbrev--default-expand'. Given the above description, I see no reason for looking at abbrev-expand-function at all, as no information is missing. But let's play along nonetheless. > (Why the default value of such a presumably user-modifiable variable > should be considered an "internal" function is a mystery.) Why not? It's just a value, right? The user-modifiable part is not the value, it's the variable abbrev-expand-function, which is not internal. > So we look at `abbrev--default-expand', which tells us this: > > "This respects the wrapper hook `abbrev-expand-functions'." No, it tells this: "Default function to use for `abbrev-expand-function'. This respects the wrapper hook `abbrev-expand-functions'. Calls `abbrev-insert' to insert any expansion, and returns what it does." So it mentions the (non-obsolete) variable abbrev-expand-function, and only then tells you that it _also_ respects the obsolete hook abbrev-expand-functions. Again, quite a different picture. (I fixed the doc string to say "also" and "obsolete" explicitly.) > So the doc tells us about a "wrapper hook", which is presumably > something like a hook, which is something that users can use. But the > wrapper hook we are pointed to is "obsolete", and we are told to instead > use a different variable (sans "s") - which was the one we started with! Not quite accurate, to say the least. In particular, the non-obsolete variable was mentioned _before_ the obsolete one in the first place. > Now what about the mysterious term "wrapper hook", apparently introduced > fairly recently? Searching for it in the Emacs manual shows nothing. > > Searching for it in the Elisp manual shows only mentions of particular > "obsolete" wrapper hooks - no explanation of what is meant by a "wrapper > hook". It isn't documented in the manuals because it's an obsolete feature. I added references to with-wrapper-hook to the few doc strings that were referencing wrapper hooks (there were just 4 of them in all of Emacs). (The text of your report was repeated 3 times for some reason.)