From unknown Sun Jun 22 00:08:46 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#28947 <28947@debbugs.gnu.org> To: bug#28947 <28947@debbugs.gnu.org> Subject: Status: 26.0; doc string of `window-normalize-buffer' and similar Reply-To: bug#28947 <28947@debbugs.gnu.org> Date: Sun, 22 Jun 2025 07:08:46 +0000 retitle 28947 26.0; doc string of `window-normalize-buffer' and similar reassign 28947 emacs submitter 28947 Drew Adams severity 28947 minor thanks From debbugs-submit-bounces@debbugs.gnu.org Sun Oct 22 16:21:55 2017 Received: (at submit) by debbugs.gnu.org; 22 Oct 2017 20:21:55 +0000 Received: from localhost ([127.0.0.1]:56267 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1e6Mkt-000493-7x for submit@debbugs.gnu.org; Sun, 22 Oct 2017 16:21:55 -0400 Received: from eggs.gnu.org ([208.118.235.92]:59985) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1e6Mkr-00048r-6q for submit@debbugs.gnu.org; Sun, 22 Oct 2017 16:21:53 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1e6Mkl-0005Le-47 for submit@debbugs.gnu.org; Sun, 22 Oct 2017 16:21:48 -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]:54139) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1e6Mkl-0005LY-1P for submit@debbugs.gnu.org; Sun, 22 Oct 2017 16:21:47 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:50951) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1e6Mkj-0004lO-Tq for bug-gnu-emacs@gnu.org; Sun, 22 Oct 2017 16:21:46 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1e6Mkg-0005K6-O9 for bug-gnu-emacs@gnu.org; Sun, 22 Oct 2017 16:21:45 -0400 Received: from userp1040.oracle.com ([156.151.31.81]:25478) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1e6Mkg-0005Jg-Fb for bug-gnu-emacs@gnu.org; Sun, 22 Oct 2017 16:21:42 -0400 Received: from userv0021.oracle.com (userv0021.oracle.com [156.151.31.71]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id v9MKLfZ4008354 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Sun, 22 Oct 2017 20:21:41 GMT Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by userv0021.oracle.com (8.14.4/8.14.4) with ESMTP id v9MKLelP020298 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Sun, 22 Oct 2017 20:21:41 GMT Received: from abhmp0012.oracle.com (abhmp0012.oracle.com [141.146.116.18]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id v9MKLdjE028774 for ; Sun, 22 Oct 2017 20:21:40 GMT MIME-Version: 1.0 Message-ID: Date: Sun, 22 Oct 2017 13:21:38 -0700 (PDT) From: Drew Adams To: bug-gnu-emacs@gnu.org Subject: 26.0; doc string of `window-normalize-buffer' and similar X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4600.0 (x86)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Source-IP: userv0021.oracle.com [156.151.31.71] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] [fuzzy] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -5.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: -5.0 (-----) The doc string does not tell anything more than what the doc of `get-buffer' tells you. In fact, it tells you less. Why does the function name start with `window-'? Is it just because it is in file window.el? If so, consider moving it. If the function has some relation to a window (I don't see anything in the code that indicates that) then please describe that in the doc string. It looks like this should be called something like `get-live-buffer', and the doc string should say that if no live buffer can be found then an error is raised. The doc string should also say explicitly that if the arg is nil then the current buffer is returned. Actually, if the arg is a buffer name that names a dead buffer then that dead buffer is returned, so that wouldn't exactly be reflected in the name `get-live-buffer'. I wonder why that behavior. Should the 3rd cond branch perhaps check that the result is a live buffer (in effect using the 2nd cond branch on the buffer gotten)? Similar remarks apply to function `window-normalize-frame'. Not specific to a window. Mention that a nil arg returns selected frame. And similar remarks apply to function `window-normalize-window'. In this case the function is about windows, but the suffix `-window' is enough. No need for prefix `window-'. In GNU Emacs 26.0.90 (build 3, x86_64-w64-mingw32) of 2017-10-13 Repository revision: 906224eba147bdfc0514090064e8e8f53160f1d4 Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --without-dbus --host=3Dx86_64-w64-mingw32 --without-compress-install 'CFLAGS=3D-O2 -static -g3'' From debbugs-submit-bounces@debbugs.gnu.org Mon Oct 23 04:06:18 2017 Received: (at 28947) by debbugs.gnu.org; 23 Oct 2017 08:06:19 +0000 Received: from localhost ([127.0.0.1]:56584 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1e6XkY-00006m-HV for submit@debbugs.gnu.org; Mon, 23 Oct 2017 04:06:18 -0400 Received: from mout.gmx.net ([212.227.17.21]:58706) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1e6XkW-00006Y-Sv for 28947@debbugs.gnu.org; Mon, 23 Oct 2017 04:06:17 -0400 Received: from [192.168.1.100] ([46.125.249.110]) by mail.gmx.com (mrgmx103 [212.227.17.168]) with ESMTPSA (Nemesis) id 0MGB7j-1e1Iwi2D0J-00FFRu; Mon, 23 Oct 2017 10:06:07 +0200 Message-ID: <59EDA2E9.902@gmx.at> Date: Mon, 23 Oct 2017 10:06:01 +0200 From: martin rudalics MIME-Version: 1.0 To: Drew Adams , 28947@debbugs.gnu.org Subject: Re: bug#28947: 26.0; doc string of `window-normalize-buffer' and similar References: In-Reply-To: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Provags-ID: V03:K0:c9ZVuk0043aZP5q6JkZ33SFdXUACOmqd5LDgJFOUkdqsFWLGrWU ZHKeB309pIlmR3IFlEOUxeTZh0y2IvaZ921YiPWOmqKsFOTulB4YtrKO1/sJvYPmsS77j6k x9575NAIGLjnVjX7yiZHJgKKC4fH7pAHtrHW//Z8pe4AoQvlatx7naEk8eRM1QXRsX6aWg6 FezYEGxzUk9pGrnBB4Oug== X-UI-Out-Filterresults: notjunk:1;V01:K0:nV9ArmGMS3w=:BVR4daEzN1Mf/48v7u/5Kb cQU6duaPxyg9DW9G67ZNbNc55JY2vPhrlcSMfs6vvFea33fFsr7H79Ju7DZz/PEhkLrCywfAv vQQXrjb8fw0Ir9ThjKFEClyhwvMjQhKc3RkjbQJRSTvNmDlLpklC9gwY7vWhgWrzUZWXjwqb6 daxiJebjA0kUPVty6Bv8mwObmRzhnvn0CAy/DJHPMKSnnXPaueK99X5GWjYULaJ57kW1/I7kp l1eHU5moR9655EhMQAMt9/1uiXmsKnqPw4++i9879jCYN48X2VARHdLQXFiGTr9hHmzvkJ+1o Z1OszspTA6cgEoLrZUaXraj1CkMp2Ci7ucY9tN3sGBmutJgJ3h9ODYvYYO8yu75UbTLC9C36E wUiY5v4XbtA06oCWqKTvu73h5bhQLvwKxzkv3PVGhhMh+2aPC1nsy0FwxF1IVseeKSZaO2wcv 3CaiiQZbza6trgKN43dipq6+sFjTvZwI93AgzUorQUKXe9D6VGu9l+RvKz5vNNDwiYw7aUr44 aRib7g5HVov877phaAbPcaxSYa+FlLEtgHlq5DhPEInoZ+qwkW5ChLTboFNloiAZjYUwcUvwc AowP9givw6M7J6BFOczQw0VH9gyKRkn0k/WK2UuRalnCIETZbYuey6KkQse8Y2QbZnKa3Jl1q zAEct2VjjK9ST3X3jO7PhZrUWKrOgViR/kxd1rU2TQy7NlHAqTcbppFjStbqdYEJU1es9qVlj hTWCqe5Vt02kqY1ulussmylL52T8lfl2xD3R27y32IqiDJc/Sc4Poa8/0AQ57h6eqxNj0auxZ HdgAbfUt8326fikJ4WgQSSFNMa2lLa+sKwIk8k1UlhKilguExU+wMqasuyTzczfC/6LEn9D X-Spam-Score: -1.5 (-) X-Debbugs-Envelope-To: 28947 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: -1.5 (-) > The doc string does not tell anything more than what the doc of > `get-buffer' tells you. In fact, it tells you less. > > Why does the function name start with `window-'? Is it just because it > is in file window.el? If so, consider moving it. If the function has > some relation to a window (I don't see anything in the code that > indicates that) then please describe that in the doc string. > > It looks like this should be called something like `get-live-buffer', > and the doc string should say that if no live buffer can be found then > an error is raised. > > The doc string should also say explicitly that if the arg is nil then > the current buffer is returned. I rewrote the doc-string as follows: Return buffer specified by BUFFER-OR-NAME. BUFFER-OR-NAME must be a live buffer, a string naming a live buffer or nil which means to return the current buffer. This function is commonly used to process the (usually optional) "BUFFER-OR-NAME" argument of window related functions where nil stands for the current buffer. > Actually, if the arg is a buffer name that names a dead buffer then that > dead buffer is returned, so that wouldn't exactly be reflected in the > name `get-live-buffer'. > > I wonder why that behavior. Should the 3rd cond branch perhaps check > that the result is a live buffer (in effect using the 2nd cond branch on > the buffer gotten)? Right. This should have been fixed in the release version. > Similar remarks apply to function `window-normalize-frame'. Not > specific to a window. Mention that a nil arg returns selected frame. Done. > And similar remarks apply to function `window-normalize-window'. > In this case the function is about windows, but the suffix `-window' is > enough. No need for prefix `window-'. These three functions did not have the `window-' prefix initially. The prefix was requested by a maintainer and added later. Thanks for the report, martin From debbugs-submit-bounces@debbugs.gnu.org Mon Oct 23 09:16:41 2017 Received: (at 28947) by debbugs.gnu.org; 23 Oct 2017 13:16:41 +0000 Received: from localhost ([127.0.0.1]:56724 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1e6cau-0001U4-Vk for submit@debbugs.gnu.org; Mon, 23 Oct 2017 09:16:41 -0400 Received: from userp1040.oracle.com ([156.151.31.81]:48720) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1e6cau-0001Tp-3f for 28947@debbugs.gnu.org; Mon, 23 Oct 2017 09:16:40 -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 v9NDGXhF029884 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 23 Oct 2017 13:16:33 GMT Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by aserv0022.oracle.com (8.14.4/8.14.4) with ESMTP id v9NDGWNh022388 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 23 Oct 2017 13:16:33 GMT Received: from abhmp0002.oracle.com (abhmp0002.oracle.com [141.146.116.8]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id v9NDGWjn003785; Mon, 23 Oct 2017 13:16:32 GMT MIME-Version: 1.0 Message-ID: <98a3ef2e-10ec-4c7e-b089-c75008ac1fdb@default> Date: Mon, 23 Oct 2017 06:16:31 -0700 (PDT) From: Drew Adams To: martin rudalics , 28947@debbugs.gnu.org Subject: RE: bug#28947: 26.0; doc string of `window-normalize-buffer' and similar References: <59EDA2E9.902@gmx.at> In-Reply-To: <59EDA2E9.902@gmx.at> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4600.0 (x86)] Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Source-IP: aserv0022.oracle.com [141.146.126.234] X-Spam-Score: -5.1 (-----) X-Debbugs-Envelope-To: 28947 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: -5.1 (-----) > I rewrote the doc-string as follows: >=20 > Return buffer specified by BUFFER-OR-NAME. > BUFFER-OR-NAME must be a live buffer, a string naming a live > buffer or nil which means to return the current buffer. >=20 > This function is commonly used to process the (usually optional) > "BUFFER-OR-NAME" argument of window related functions where nil > stands for the current buffer. > ... > Right. This should have been fixed in the release version. > ... > Done. > ... > These three functions did not have the `window-' prefix initially. The > prefix was requested by a maintainer and added later. Thanks for the quick fix. Too bad about the function names. I don't really see them as normalizing anything. And yes, they are used by window-related functions. But they are general utilities, not really having anything to do with windows. It's a bit like having a general function such as `get-buffer' defined in a Lisp library `foo.el', which is about using foos, and naming it `foo-get-buffer'. If the function is usable and useful outside foo.el then its definition belongs outside foo.el, and it shouldn't have the misleading prefix `foo-'. This (the name) is all the more important for a library named `window.el', as a window is an important, basic Emacs thingie, and functions with `window' in their name should be about Emacs windows. Perhaps our maintainer could consider changing his mind about this one? Perhaps we could move these functions out of `window.el' and rename them without prefix `window-'? From debbugs-submit-bounces@debbugs.gnu.org Tue Oct 31 04:41:31 2017 Received: (at 28947-done) by debbugs.gnu.org; 31 Oct 2017 08:41:31 +0000 Received: from localhost ([127.0.0.1]:43169 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1e9S71-0004E7-ED for submit@debbugs.gnu.org; Tue, 31 Oct 2017 04:41:31 -0400 Received: from mout.gmx.net ([212.227.17.20]:59155) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1e9S6z-0004Du-QD for 28947-done@debbugs.gnu.org; Tue, 31 Oct 2017 04:41:30 -0400 Received: from [192.168.1.100] ([46.125.249.55]) by mail.gmx.com (mrgmx103 [212.227.17.168]) with ESMTPSA (Nemesis) id 0MegeC-1dlJY808HQ-00OE5x; Tue, 31 Oct 2017 09:41:20 +0100 Message-ID: <59F83729.3050108@gmx.at> Date: Tue, 31 Oct 2017 09:41:13 +0100 From: martin rudalics MIME-Version: 1.0 To: Drew Adams , 28947-done@debbugs.gnu.org Subject: Re: bug#28947: 26.0; doc string of `window-normalize-buffer' and similar References: <59EDA2E9.902@gmx.at> <98a3ef2e-10ec-4c7e-b089-c75008ac1fdb@default> In-Reply-To: <98a3ef2e-10ec-4c7e-b089-c75008ac1fdb@default> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Provags-ID: V03:K0:5VMEQIBICKfcEQxK27Vsf8uQS1mZfjoEx8vlB2Es/YAcOHQhuER Q16xcG0jbIERFjPnkFPAIdT74nr1rUiXUTa9aJiMG0Ufa7zTnsKj5kki3z6wI3KaA1loDZd Z2Q01iiGXrdoAH7lc4a2z7HYh84xZ/GDJjRAWI5/NWBHES/kipbyq7V0F35f9A6URWcIKCq Xe3zKzIBWXYF310JnWzUw== X-UI-Out-Filterresults: notjunk:1;V01:K0:UYRmyPNSuD4=:H748aJMMJ7XZoYOuRcP8I2 r3eclYbWoXuAoyunDBrVNRY09fsy7Q3VJQP6IudPFBYz0HsMUSZruT78Y56Bkw4F7PFMhDGxC HoohwauQPt05I0khye5CYKsLd/29IpKmDNDnzA+6GlVS+RdZcTHlJkrzkdJ5YiS5CEEQoWSg9 D3GiIwx3BnTbLTScPrMIASKuBCjiTgoJ8L8vvXwiyJhIYmZGsCpBjuTV/ZuYEnd5AG8crWtDm 7apZ3X3DX27jhjkwEg1z5+f9fHap/Gx2UJP9jjM+keiSGwpO6ejYJgKP/doo+VZinKJUaPMFq hWK30+fkFmGpxGVJDDNYd2qbmVVFyQI1OeiY7ODz0+jBAdIosl4SWpNCnHAPw//tVdpSAOMGt g2evAAI+t7HlLT5AyVA/AuSYH7vetJ9sy2NFMacGK4PRxUPTwmz6cQzyKVcgsD9M9aqvkZh2W Sk92raAoUfHxRLTowJ8JVDosxoTeEtjZDYpwEccDj7Tz1ArS5cULsjXH7Xzq4LyV46Dwd//K1 cM+wYwrGnKkmd3ZJyt1pJ9u7LCn5DPyo2Qi+h9cCP2QOPahxOgwkiSHBlerCpoex1ubyAHcSY 6ltda5qDGExPzBsG/9bOACBc9QHKfuJSSATWp3nJCDW6TDEs3gIGMfWTjNI7+BHTJ4JOyhKNC LWBmmsP9ZNJ5EgIFjWV2NXYrTugG2yxvfvHlVLx9Vecmf2Jxx/vIjyn5EIALDvf4lr7gzvGvB DU65S0cqy1BOj/dYpsMamnXJ/6gupYDo6jvs2mQRvndF7xlmorvVYRH93HDpKIiOt5LnM5oxG zVJB5oSmZ4P63ES3ZWjc3ZkxYakRUClr2i6egRgHyex1uPSnHvKUMDMppm0vdcujPTS3Eoo X-Spam-Score: -0.2 (/) X-Debbugs-Envelope-To: 28947-done 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: -0.2 (/) > Perhaps our maintainer could consider changing his > mind about this one? Perhaps we could move these > functions out of `window.el' and rename them without > prefix `window-'? Probably people don't care much so I'm closing this bug. Thanks, martin From unknown Sun Jun 22 00:08:46 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, 28 Nov 2017 12:24:05 +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