From debbugs-submit-bounces@debbugs.gnu.org Sun Sep 25 10:53:50 2016 Received: (at submit) by debbugs.gnu.org; 25 Sep 2016 14:53:50 +0000 Received: from localhost ([127.0.0.1]:35683 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1boAoP-0002iO-MG for submit@debbugs.gnu.org; Sun, 25 Sep 2016 10:53:50 -0400 Received: from eggs.gnu.org ([208.118.235.92]:43113) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1boAoN-0002i8-Le for submit@debbugs.gnu.org; Sun, 25 Sep 2016 10:53:49 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1boAoH-0001sA-BT for submit@debbugs.gnu.org; Sun, 25 Sep 2016 10:53:42 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: * X-Spam-Status: No, score=1.3 required=5.0 tests=BAYES_50,RCVD_IN_SORBS_SPAM autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:48060) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1boAoH-0001rs-8K for submit@debbugs.gnu.org; Sun, 25 Sep 2016 10:53:41 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:34067) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1boAoE-0001UJ-Ax for bug-gnu-emacs@gnu.org; Sun, 25 Sep 2016 10:53:39 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1boAoA-0001rF-5n for bug-gnu-emacs@gnu.org; Sun, 25 Sep 2016 10:53:37 -0400 Received: from userp1040.oracle.com ([156.151.31.81]:21078) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1boAo9-0001qw-TW for bug-gnu-emacs@gnu.org; Sun, 25 Sep 2016 10:53:34 -0400 Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id u8PErVYs023050 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Sun, 25 Sep 2016 14:53:31 GMT Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by aserv0022.oracle.com (8.14.4/8.14.4) with ESMTP id u8PErU13004420 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Sun, 25 Sep 2016 14:53:31 GMT Received: from abhmp0006.oracle.com (abhmp0006.oracle.com [141.146.116.12]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id u8PErUhG006431 for ; Sun, 25 Sep 2016 14:53:30 GMT MIME-Version: 1.0 Message-ID: <39d1a887-a19f-40ba-9b00-84e27f2606ce@default> Date: Sun, 25 Sep 2016 07:53:30 -0700 (PDT) From: Drew Adams To: bug-gnu-emacs@gnu.org Subject: 25.1; doc of `abbrev-expand-function(s)', "wrapper hooks",... X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9 (901082) [OL 12.0.6753.5000 (x86)] Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Source-IP: aserv0022.oracle.com [141.146.126.234] 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: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -3.5 (---) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.5 (---) 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." (It should say that it calls the _value of variable_ `abbrev-expand-function'.) So we look at `abbrev-expand-function', which tells us that the default value is `abbrev--default-expand'. (Why the default value of such a presumably user-modifiable variable should be considered an "internal" function is a mystery.) So we look at `abbrev--default-expand', which tells us this: "This respects the wrapper hook `abbrev-expand-functions'." Hm. So we look at `abbrev-expand-functions', to see what this "wrapper hook" is all about. It tells us this: "Wrapper hook around =E2=80=98abbrev--default-expand=E2=80=99." OK. It's a "wrapper hook", whatever that is. This doesn't tell us anything more. But `C-h v abbrev-expand-functions' also tells us this, which is interesting: "This variable is obsolete since 24.4; use =E2=80=98abbrev-expand-function= =E2=80=99 instead." 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! Round and round we go... 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 looks as though a new term ("wrapper hook") was introduced to the Emacs vocabulary in Emacs 23, and then removed (deprecated?) soon thereafter. What is this all about? What is a poor user to understand about all of this? One could forgive a user for being confused, or totally lost, in this swamp. Please consider clearing away some of the brambles. In GNU Emacs 25.1.1 (x86_64-w64-mingw32) of 2016-09-17 built on LAPHROAIG Windowing system distributor 'Microsoft Corp.', version 6.1.7601 Configured using: 'configure --without-dbus --without-compress-install CFLAGS=3D-static' 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." So we look at `abbrev-expand-function', which tells us that the default value is `abbrev--default-expand'. (Why the default value of such a user-modifiable variable should be considered an "internal" function is a mystery.) So we look at `abbrev--default-expand', which tells us this: "This respects the wrapper hook `abbrev-expand-functions'." Hm. So we look at `abbrev-expand-functions', to see what this "wrapper hook" is all about. It tells us this: "Wrapper hook around =E2=80=98abbrev--default-expand=E2=80=99." OK. It's a "wrapper hook", whatever that is. This doesn't tell us anything more. But `C-h v abbrev--default-expand' also tells us this, which is interesting: "This variable is obsolete since 24.4; use =E2=80=98abbrev-expand-function= =E2=80=99 instead." 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! Round and round we go. So 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 looks as though a new term ("wrapper hook") was introduced to the Emacs vocabulary recently, and then removed (deprecated?) almost immediately. What is this all about? What is a poor user to understand about all of this? One could forgive a user for being confused, or totally lost, in this swamp. In GNU Emacs 25.1.1 (x86_64-w64-mingw32) of 2016-09-17 built on LAPHROAIG Windowing system distributor 'Microsoft Corp.', version 6.1.7601 Configured using: 'configure --without-dbus --without-compress-install CFLAGS=3D-static' So we look at `abbrev-expand-function', which tells us that the default value is `abbrev--default-expand'. (Why the default value of such a user-modifiable variable should be considered an "internal" function is a mystery.) So we look at `abbrev--default-expand', which tells us this: "This respects the wrapper hook `abbrev-expand-functions'." Hm. So we look at `abbrev-expand-functions', to see what this "wrapper hook" is all about. It tells us this: "Wrapper hook around =E2=80=98abbrev--default-expand=E2=80=99." OK. It's a "wrapper hook", whatever that is. This doesn't tell us anything more. But `C-h v abbrev--default-expand' also tells us this, which is interesting: "This variable is obsolete since 24.4; use =E2=80=98abbrev-expand-function= =E2=80=99 instead." 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! Round and round we go. So 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 looks as though a new term ("wrapper hook") was introduced to the Emacs vocabulary recently, and then removed (deprecated?) almost immediately. What is this all about? What is a poor user to understand about all of this? One could forgive a user for being confused, or totally lost, in this swamp. In GNU Emacs 25.1.1 (x86_64-w64-mingw32) of 2016-09-17 built on LAPHROAIG Windowing system distributor 'Microsoft Corp.', version 6.1.7601 Configured using: 'configure --without-dbus --without-compress-install CFLAGS=3D-static' From debbugs-submit-bounces@debbugs.gnu.org Sun Sep 25 11:26:29 2016 Received: (at submit) by debbugs.gnu.org; 25 Sep 2016 15:26:29 +0000 Received: from localhost ([127.0.0.1]:35700 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1boBK0-0003Y2-QP for submit@debbugs.gnu.org; Sun, 25 Sep 2016 11:26:28 -0400 Received: from eggs.gnu.org ([208.118.235.92]:48397) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1boBJz-0003Xp-1I for submit@debbugs.gnu.org; Sun, 25 Sep 2016 11:26:27 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1boBJt-0002CB-19 for submit@debbugs.gnu.org; Sun, 25 Sep 2016 11:26:21 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: * X-Spam-Status: No, score=1.3 required=5.0 tests=BAYES_50,RCVD_IN_SORBS_SPAM autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:46834) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1boBJs-0002Bz-UJ for submit@debbugs.gnu.org; Sun, 25 Sep 2016 11:26:20 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:39351) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1boBJq-00023X-Hi for bug-gnu-emacs@gnu.org; Sun, 25 Sep 2016 11:26:19 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1boBJl-0002B0-Fi for bug-gnu-emacs@gnu.org; Sun, 25 Sep 2016 11:26:17 -0400 Received: from mout.kundenserver.de ([212.227.126.134]:64404) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1boBJl-0002Aq-5y for bug-gnu-emacs@gnu.org; Sun, 25 Sep 2016 11:26:13 -0400 Received: from [192.168.178.35] ([77.12.34.13]) by mrelayeu.kundenserver.de (mreue005) with ESMTPSA (Nemesis) id 0MfDvq-1bcZgV26x8-00Olfp; Sun, 25 Sep 2016 17:26:05 +0200 Subject: Re: bug#24540: 25.1; doc of `abbrev-expand-function(s)', "wrapper hooks",... To: bug-gnu-emacs@gnu.org References: <39d1a887-a19f-40ba-9b00-84e27f2606ce@default> From: =?UTF-8?Q?Andreas_R=c3=b6hler?= Message-ID: <8c315f6a-53ba-4b7c-7be1-050955e5ad58@easy-emacs.de> Date: Sun, 25 Sep 2016 17:33:13 +0200 User-Agent: Mozilla/5.0 (X11; Linux i686; rv:45.0) Gecko/20100101 Icedove/45.2.0 MIME-Version: 1.0 In-Reply-To: <39d1a887-a19f-40ba-9b00-84e27f2606ce@default> Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit X-Provags-ID: V03:K0:Mc6eApSBS6Ru+SxeX0PxsTYYVttiPLOuXndm5+yZCKlaTy5gxqS Le+AbKjdEDGhpqXglaoqX0QxAXeGwgWjjBxHhVde4jSQ1iams0PClMGHqL78mnUqSRfSxuq Wd45YmL3Z5GVW+BKuxMrLlXlRwxNWYw08B3vBIFRvcZTC+a9U5ySUqIdkET3jAeOAf72eCo ZIvHJooaMrm4zBRvxuYPg== X-UI-Out-Filterresults: notjunk:1;V01:K0:b5zwt5ZASvY=:ATFE+/ZVltKGuUzw4JzU43 groiMYigzSZWgEweh3Gyqy52EJSWa1g/ALbmNgiX89J4Y/AYFZBjYRArfrdHDjcL3dIlgApMn 9fzuqJd3iz4KUZ5pejNxv6KCbUEBk+rXDQtfihmrE60BMjwvJfit92+T3fH/JdVbTDkRLhLNC 2+P3Yl0LSbolV/dvXIi406ukL4Q92ZZEOKw58Wq2J5aKFJubQf+9o63wf/OTL9pAfIrikXJy5 clwgEVz+9DUc1i3+YSD7jhgpPtWxPwNbwjSdfEfZAGgdVpMmdft3dHMVmMG+t5PZpMlDnMW9t Jyw9hJGd02n9UlbKPUchoKT468ibuMr8A0xHdmi6suvVLxnBrOEV/Cv3sPTLAth2tzF3JPHcB gyC5wFfq0KnSINjkRIvqrf03u6Ao7R+/2Z+I4rEsm8PrkyCZ1Mu/po4V+6ouNtLFAwON+fUxb gH0J7QEJ6bP2J653x3cXgkk22w5u3hMmPW3Kwn3M7xAG4TZQLqNRnAc32qzaGWOM5x2Yfb8uw Fe1BWuw4uS307DSLZ3Z4n9o96eKj7GydlQr5pCHIWgfcA4udwzYVQsz3s7VNE/MI/FsnwU+8j lfwDtXmeS1ZeXmheT0aG+Tv8MWe6Ii8QTCPFma/i1EVUl5IjOqoiuAaLudxJvciMC4vVaEmXF WAqFQY6jd9nbhyi2gOmpX+fo7l8MHgJbJKtWRx2pErskWr6YpIpSBdJxMdVgjWrvvnzIpXajW r4Jq1o+jwAuFcByd X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.5 (----) X-Debbugs-Envelope-To: submit Cc: Drew Adams X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -4.5 (----) On 25.09.2016 16:53, Drew Adams wrote: > Let's check the doc, starting with `expand-abbrev': > > Hi Drew, thanks. abbrev.el needs a reconsideration from the bottom. Discussed this several weeks ago at emacs-devel. A re-write IMHO must start with specifications, i.e. it must be known, what to expect. Being in favor of accepting arbitrary, case-sensitive strings as abbrev, which seems not working at the moment. Cheers, Andreas From debbugs-submit-bounces@debbugs.gnu.org Sun Sep 25 15:39:22 2016 Received: (at submit) by debbugs.gnu.org; 25 Sep 2016 19:39:22 +0000 Received: from localhost ([127.0.0.1]:35797 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1boFGk-0001d3-Bt for submit@debbugs.gnu.org; Sun, 25 Sep 2016 15:39:22 -0400 Received: from eggs.gnu.org ([208.118.235.92]:36690) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1boFGi-0001cq-7W for submit@debbugs.gnu.org; Sun, 25 Sep 2016 15:39:21 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1boFGc-0008IO-0V for submit@debbugs.gnu.org; Sun, 25 Sep 2016 15:39:14 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50 autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:49910) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1boFGb-0008I0-TK for submit@debbugs.gnu.org; Sun, 25 Sep 2016 15:39:13 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:55894) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1boFGZ-0007gX-Pe for bug-gnu-emacs@gnu.org; Sun, 25 Sep 2016 15:39:12 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1boFGV-0008EZ-Ka for bug-gnu-emacs@gnu.org; Sun, 25 Sep 2016 15:39:10 -0400 Received: from aserp1040.oracle.com ([141.146.126.69]:31202) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1boFGV-0008CS-1u for bug-gnu-emacs@gnu.org; Sun, 25 Sep 2016 15:39:07 -0400 Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id u8PJd19n011691 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 25 Sep 2016 19:39:01 GMT Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by aserv0022.oracle.com (8.14.4/8.14.4) with ESMTP id u8PJd0aQ005895 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 25 Sep 2016 19:39:01 GMT Received: from abhmp0005.oracle.com (abhmp0005.oracle.com [141.146.116.11]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id u8PJcv4u023571; Sun, 25 Sep 2016 19:38:57 GMT MIME-Version: 1.0 Message-ID: Date: Sun, 25 Sep 2016 12:38:57 -0700 (PDT) From: Drew Adams To: =?utf-8?B?QW5kcmVhcyBSw7ZobGVy?= , bug-gnu-emacs@gnu.org Subject: RE: bug#24540: 25.1; doc of `abbrev-expand-function(s)', "wrapper hooks",... References: <39d1a887-a19f-40ba-9b00-84e27f2606ce@default> <8c315f6a-53ba-4b7c-7be1-050955e5ad58@easy-emacs.de> In-Reply-To: <8c315f6a-53ba-4b7c-7be1-050955e5ad58@easy-emacs.de> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9 (901082) [OL 12.0.6753.5000 (x86)] Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Source-IP: aserv0022.oracle.com [141.146.126.234] 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: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.0 (----) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -4.0 (----) > Hi Drew, >=20 > thanks. abbrev.el needs a reconsideration from the bottom. Discussed > this several weeks ago at emacs-devel. A re-write IMHO must start with > specifications, i.e. it must be known, what to expect. >=20 > Being in favor of accepting arbitrary, case-sensitive strings as abbrev, > which seems not working at the moment. Hi Andreas, OK, but maybe this doc could be cleared up a bit first, as a minor improvement. - Drew From debbugs-submit-bounces@debbugs.gnu.org Mon Sep 26 02:08:35 2016 Received: (at submit) by debbugs.gnu.org; 26 Sep 2016 06:08:35 +0000 Received: from localhost ([127.0.0.1]:35951 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1boP5f-00037e-KI for submit@debbugs.gnu.org; Mon, 26 Sep 2016 02:08:35 -0400 Received: from eggs.gnu.org ([208.118.235.92]:52920) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1boP5d-00037P-Pz for submit@debbugs.gnu.org; Mon, 26 Sep 2016 02:08:34 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1boP5X-00041R-Nw for submit@debbugs.gnu.org; Mon, 26 Sep 2016 02:08:28 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: * X-Spam-Status: No, score=1.3 required=5.0 tests=BAYES_50,RCVD_IN_SORBS_SPAM autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:57738) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1boP5X-00041E-Kc for submit@debbugs.gnu.org; Mon, 26 Sep 2016 02:08:27 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:43889) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1boP5V-0004ts-HK for bug-gnu-emacs@gnu.org; Mon, 26 Sep 2016 02:08:26 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1boP5R-0003za-AA for bug-gnu-emacs@gnu.org; Mon, 26 Sep 2016 02:08:24 -0400 Received: from mout.kundenserver.de ([212.227.126.135]:50057) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1boP5R-0003zN-09 for bug-gnu-emacs@gnu.org; Mon, 26 Sep 2016 02:08:21 -0400 Received: from [192.168.178.35] ([77.12.12.128]) by mrelayeu.kundenserver.de (mreue004) with ESMTPSA (Nemesis) id 0MBX6o-1bhDp22Bni-00ASqd; Mon, 26 Sep 2016 08:08:14 +0200 Subject: Re: bug#24540: 25.1; doc of `abbrev-expand-function(s)', "wrapper hooks",... To: bug-gnu-emacs@gnu.org References: <39d1a887-a19f-40ba-9b00-84e27f2606ce@default> From: =?UTF-8?Q?Andreas_R=c3=b6hler?= Message-ID: Date: Mon, 26 Sep 2016 08:15:25 +0200 User-Agent: Mozilla/5.0 (X11; Linux i686; rv:45.0) Gecko/20100101 Icedove/45.2.0 MIME-Version: 1.0 In-Reply-To: <39d1a887-a19f-40ba-9b00-84e27f2606ce@default> Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit X-Provags-ID: V03:K0:8QUcjLnU1WpIqJS9+nQfrSVm3eBinOGlVrvO6lRi4FcH2HO8ON9 fk7eEmned/DbCbELhCO3KSYy7FZ/CIGdlJyIbb72mjEG/uPS6Igj7LoIrwVintxmxk/MGiu BxaPK9N0Rtc5RGP/+NSbdUar1DC1H0bmpz9KTV/HFtAsEIE6PFFqyoaHFfdwdNt0JATf8E5 kDdi0TDOv6guLybB/t2mw== X-UI-Out-Filterresults: notjunk:1;V01:K0:m7TTYgRroGI=:VZmcLln2Lha09tH38s/Egy 8+Fs/9GEUjWKOQ5tAMHXRi0EC6SxyJfTIFJqcnxMuCvnQcC40SynNGqICJb3CI/Dqn9Ze1N/s /u+OnyBP2h7ZlFhn6SAc7mUnTL3m8abZo6dLLseJ9fxWcsLW1FBd/3siK8H5HDbvFsMAJUC93 lqZ/tMc7jPSdsaMM8QwqVqJQ5GEMHRrh+uJapqTh+aaOeTo8EkUZAJQ08w3dErTqkES6RXdaR gIHK/OupdkeZ45sHTSA1iKLJdNEUKedDrz4PuOrR93e3f3W3gzTfhMP0u110sRzBSCX8HxUy8 QAm7hBu8SfJFdHW7rUC+n6wZG367TXBbCGlBHRj12XG9v0x64eRv342+jhsBUFG76H8bM+SQ7 H4h2C9Q7ZX7YXp7PVYJb0+Jte+LVUhl3CJINiDr6gfamXiVo4hsVzqEupPm214Fn1oWQCm/6B TaMDx3CTfZJ356LLHhAEoGN960vG707wTlhhBFaL7C6K7KlwNGZSIUO8oMrFgsB6nD+DRhPn4 VJgpFCGt+AT9VolfvwJQ/zu5OMCxIvummJDtJaFCK/z8H2U8trcydwRoniOD3wgzk4pvFat6V sT8nc8DvbCLBk9rJg8R/jdNEvoxSNNgHntC7q4Q2Eh/S77EhcLZ6DtRqXDYe5VjxbEA2IL9qo Hh49GgRCV3DlE9AgYjUDjuPFyQvPuj8uEM+csrJN7+wEPiE3+QB0dLDInW8sPtLVqrpGT3p9p dspaPJDtLUY6hOD8 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.5 (----) X-Debbugs-Envelope-To: submit Cc: Drew Adams X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -4.5 (----) On 25.09.2016 16:53, Drew Adams wrote: > 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." > > (It should say that it calls the _value of variable_ > `abbrev-expand-function'.) Hmm, the explicit "-function" tells me, there is something uncommon: ah, that's not a function at this level. OTOH a thing would be to name a function "-function". But these are conventions, which also apply to other parts. Think it's worth to be brought to emacs-devel. From debbugs-submit-bounces@debbugs.gnu.org Mon Sep 26 12:04:30 2016 Received: (at 24540-done) by debbugs.gnu.org; 26 Sep 2016 16:04:30 +0000 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 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 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 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-2.2 required=5.0 tests=BAYES_50,RP_MATCHES_RCVD autolearn=disabled version=3.3.2 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 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 Date: Mon, 26 Sep 2016 19:04:04 +0300 Message-Id: <83d1jqd4wb.fsf@gnu.org> From: Eli Zaretskii To: Drew Adams In-reply-to: <39d1a887-a19f-40ba-9b00-84e27f2606ce@default> (message from Drew Adams on Sun, 25 Sep 2016 07:53:30 -0700 (PDT)) Subject: Re: bug#24540: 25.1; doc of `abbrev-expand-function(s)', "wrapper hooks",... References: <39d1a887-a19f-40ba-9b00-84e27f2606ce@default> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -8.0 (--------) X-Debbugs-Envelope-To: 24540-done Cc: 24540-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Eli Zaretskii Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -8.0 (--------) > 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.) From unknown Sun Aug 10 16:45:03 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Tue, 25 Oct 2016 11:24:04 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator