From unknown Tue Jun 24 05:10:06 2025 X-Loop: owner@emacsbugs.donarmstrong.com Subject: bug#3598: 23.0.94; doc string of frame-root-window Reply-To: "Drew Adams" , 3598@debbugs.gnu.org Resent-From: "Drew Adams" Resent-To: bug-submit-list@lists.donarmstrong.com Resent-CC: Emacs Bugs Resent-Date: Wed, 17 Jun 2009 16:50:04 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-Emacs-PR-Message: report 3598 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Received: via spool by submit@emacsbugs.donarmstrong.com id=B.124525706620945 (code B ref -1); Wed, 17 Jun 2009 16:50:04 +0000 Received: (at submit) by emacsbugs.donarmstrong.com; 17 Jun 2009 16:44:26 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-2.9 required=4.0 tests=AWL,FOURLA autolearn=no version=3.2.5-bugs.debian.org_2005_01_02 Received: from fencepost.gnu.org (fencepost.gnu.org [140.186.70.10]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n5HGiMe0020940 for ; Wed, 17 Jun 2009 09:44:23 -0700 Received: from mx10.gnu.org ([199.232.76.166]:54915) by fencepost.gnu.org with esmtp (Exim 4.67) (envelope-from ) id 1MGyFJ-0006oy-SS for emacs-pretest-bug@gnu.org; Wed, 17 Jun 2009 12:44:21 -0400 Received: from Debian-exim by monty-python.gnu.org with spam-scanned (Exim 4.60) (envelope-from ) id 1MGyFI-0002r6-AD for emacs-pretest-bug@gnu.org; Wed, 17 Jun 2009 12:44:21 -0400 Received: from acsinet12.oracle.com ([141.146.126.234]:61595) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1MGyFH-0002qg-6r for emacs-pretest-bug@gnu.org; Wed, 17 Jun 2009 12:44:20 -0400 Received: from rgminet15.oracle.com (rcsinet15.oracle.com [148.87.113.117]) by acsinet12.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n5HGiEiP002616 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Wed, 17 Jun 2009 16:44:16 GMT Received: from abhmt005.oracle.com (abhmt005.oracle.com [141.146.116.14]) by rgminet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n5HGiJ2S024595 for ; Wed, 17 Jun 2009 16:44:20 GMT Received: from dradamslap1 (/141.144.73.196) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Wed, 17 Jun 2009 09:44:12 -0700 From: "Drew Adams" To: Date: Wed, 17 Jun 2009 09:44:26 -0700 Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 Thread-Index: AcnvauCByaduBiVERnachq9nDiMNPA== X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 X-Source-IP: abhmt005.oracle.com [141.146.116.14] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090209.4A391D5E.001C:SCFSTAT5015188,ss=1,fgs=0 X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 1) Doc string: Returns the root-window of frame. 1. "root-window" should be "root window". 2. Root window needs to be explained - what is it? With no explanation, this doc string says nothing at all: "`frame-root-window' returns the frame's root window". Gee thanks a lot! `thrinblat-oag-plaz' returns the thrinblat's oag plaz. 3. And the manual's don't help - `frame-root-window' is not mentioned. In GNU Emacs 23.0.94.1 (i386-mingw-nt5.1.2600) of 2009-05-24 on SOFT-MJASON Windowing system distributor `Microsoft Corp.', version 5.1.2600 configured using `configure --with-gcc (3.4)' From unknown Tue Jun 24 05:10:06 2025 X-Loop: owner@emacsbugs.donarmstrong.com Subject: bug#3598: 23.0.94; doc string of frame-root-window Reply-To: "Drew Adams" , 3598@debbugs.gnu.org Resent-From: "Drew Adams" Resent-To: bug-submit-list@lists.donarmstrong.com Resent-CC: Emacs Bugs Resent-Date: Wed, 17 Jun 2009 17:30:04 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-Emacs-PR-Message: followup 3598 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Received: via spool by submit@emacsbugs.donarmstrong.com id=B.124525942028544 (code B ref -1); Wed, 17 Jun 2009 17:30:04 +0000 Received: (at submit) by emacsbugs.donarmstrong.com; 17 Jun 2009 17:23:40 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-4.4 required=4.0 tests=AWL,HAS_BUG_NUMBER autolearn=unavailable version=3.2.5-bugs.debian.org_2005_01_02 Received: from fencepost.gnu.org (fencepost.gnu.org [140.186.70.10]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n5HHNZBQ028537 for ; Wed, 17 Jun 2009 10:23:37 -0700 Received: from mail.gnu.org ([199.232.76.166]:56728 helo=mx10.gnu.org) by fencepost.gnu.org with esmtp (Exim 4.67) (envelope-from ) id 1MGyrG-00008G-SN for emacs-pretest-bug@gnu.org; Wed, 17 Jun 2009 13:23:34 -0400 Received: from Debian-exim by monty-python.gnu.org with spam-scanned (Exim 4.60) (envelope-from ) id 1MGyrF-000225-Si for emacs-pretest-bug@gnu.org; Wed, 17 Jun 2009 13:23:34 -0400 Received: from rcsinet11.oracle.com ([148.87.113.123]:19821 helo=rgminet11.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1MGyrF-00021f-3e for emacs-pretest-bug@gnu.org; Wed, 17 Jun 2009 13:23:33 -0400 Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by rgminet11.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n5HHOOlJ013847 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Wed, 17 Jun 2009 17:24:25 GMT Received: from abhmt010.oracle.com (abhmt010.oracle.com [141.146.116.19]) by acsinet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n5HHOcEA031770; Wed, 17 Jun 2009 17:24:38 GMT Received: from dradamslap1 (/141.144.73.196) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Wed, 17 Jun 2009 10:23:18 -0700 From: "Drew Adams" To: <3598@debbugs.gnu.org>, References: Date: Wed, 17 Jun 2009 10:23:31 -0700 Message-ID: <7CAD2668590D4016830B95F8A8FF3807@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-Reply-To: Thread-Index: AcnvauCByaduBiVERnachq9nDiMNPAABVySA X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 X-Source-IP: abhmt010.oracle.com [141.146.116.19] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090207.4A392687.008F:SCFSTAT5015188,ss=1,fgs=0 X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 1) Note too that "root window" means something about window manager windows (e.g. X Window), outside Emacs, so it is all the more important to explain this concept a frame's root window. From unknown Tue Jun 24 05:10:06 2025 X-Loop: owner@emacsbugs.donarmstrong.com Subject: bug#3598: 23.0.94; doc string of frame-root-window Reply-To: martin rudalics , 3598@debbugs.gnu.org Resent-From: martin rudalics Resent-To: bug-submit-list@lists.donarmstrong.com Resent-CC: Emacs Bugs Resent-Date: Thu, 18 Jun 2009 10:15:04 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-Emacs-PR-Message: followup 3598 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Received: via spool by 3598-submit@emacsbugs.donarmstrong.com id=B3598.12453197446205 (code B ref 3598); Thu, 18 Jun 2009 10:15:04 +0000 Received: (at 3598) by emacsbugs.donarmstrong.com; 18 Jun 2009 10:09:04 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-4.5 required=4.0 tests=AWL,FOURLA,HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from mail.gmx.net (mail.gmx.net [213.165.64.20]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with SMTP id n5IA8vNq006186 for <3598@emacsbugs.donarmstrong.com>; Thu, 18 Jun 2009 03:08:59 -0700 Received: (qmail invoked by alias); 18 Jun 2009 10:08:51 -0000 Received: from 62-47-35-144.adsl.highway.telekom.at (EHLO [62.47.35.144]) [62.47.35.144] by mail.gmx.net (mp009) with SMTP; 18 Jun 2009 12:08:51 +0200 X-Authenticated: #14592706 X-Provags-ID: V01U2FsdGVkX19Xmnsr7nlXKgQe1Wvj0VY4MKhxKj71sx+5NWrSF6 AexinLUxHO8aJP Message-ID: <4A3A11DD.4010500@gmx.at> Date: Thu, 18 Jun 2009 12:07:25 +0200 From: martin rudalics User-Agent: Thunderbird 2.0.0.21 (Windows/20090302) MIME-Version: 1.0 To: Drew Adams , 3598@debbugs.gnu.org References: In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Y-GMX-Trusted: 0 X-FuHaFi: 0.6899999999999999 > Doc string: > Returns the root-window of frame. > > 1. "root-window" should be "root window". > > 2. Root window needs to be explained - what is it? > > With no explanation, this doc string says nothing at all: > "`frame-root-window' returns the frame's root window". Gee thanks a > lot! `thrinblat-oag-plaz' returns the thrinblat's oag plaz. > > 3. And the manual's don't help - `frame-root-window' is not mentioned. IIUC `frame-root-window' was deliberately never described because up to Emacs 22 it was not always safe to call Lisp functions with an internal window as argument. So I think this function was intended for internal use only. martin From unknown Tue Jun 24 05:10:06 2025 X-Loop: owner@emacsbugs.donarmstrong.com Subject: bug#3598: 23.0.94; doc string of frame-root-window Reply-To: "Drew Adams" , 3598@debbugs.gnu.org Resent-From: "Drew Adams" Resent-To: bug-submit-list@lists.donarmstrong.com Resent-CC: Emacs Bugs Resent-Date: Thu, 18 Jun 2009 14:10:06 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-Emacs-PR-Message: followup 3598 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Received: via spool by 3598-submit@emacsbugs.donarmstrong.com id=B3598.124533391111301 (code B ref 3598); Thu, 18 Jun 2009 14:10:06 +0000 Received: (at 3598) by emacsbugs.donarmstrong.com; 18 Jun 2009 14:05:11 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-4.3 required=4.0 tests=AWL,FOURLA,HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from acsinet11.oracle.com (acsinet11.oracle.com [141.146.126.233]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n5IE547r010418 for <3598@emacsbugs.donarmstrong.com>; Thu, 18 Jun 2009 07:05:06 -0700 Received: from rgminet15.oracle.com (rcsinet15.oracle.com [148.87.113.117]) by acsinet11.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n5IE5vuo004758 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 18 Jun 2009 14:05:58 GMT Received: from abhmt003.oracle.com (abhmt003.oracle.com [141.146.116.12]) by rgminet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n5IE50Bn017699; Thu, 18 Jun 2009 14:05:01 GMT Received: from dradamslap1 (/141.144.74.8) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 18 Jun 2009 07:04:53 -0700 From: "Drew Adams" To: "'martin rudalics'" , <3598@debbugs.gnu.org> References: <4A3A11DD.4010500@gmx.at> Date: Thu, 18 Jun 2009 07:05:11 -0700 Message-ID: <29DA79C677954D6FAE4CBEBCB7DEA175@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <4A3A11DD.4010500@gmx.at> Thread-Index: Acnv/NRWFfwCc6CMSuGT360QZ73fsAAHpiLw X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 X-Source-IP: abhmt003.oracle.com [141.146.116.12] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090206.4A3A4987.023C:SCFSTAT5015188,ss=1,fgs=0 > > Returns the root-window of frame. > > 1. "root-window" should be "root window". > > 2. Root window needs to be explained - what is it? > > With no explanation, this doc string says nothing at all: > > "`frame-root-window' returns the frame's root window". > > 3. And the manual's don't help - `frame-root-window' is > > not mentioned. > > IIUC `frame-root-window' was deliberately never described > because up to Emacs 22 it was not always safe to call Lisp > functions with an internal window as argument. So I think > this function was intended for internal use only. I see. Well, the doc does not reflect that, for one thing. If it is an internal function, then please either do not give it a doc string or, preferably, give it one that calls that out explicitly, and please add a comment explaining why it is internal. Second, whether it is internal or not is a different matter from whether its doc (in the form of doc string or comment) is accurate and helpful. As I mentioned, the concept of a GNU Emacs "root window" is not explained anywhere, that I can find. See the XEmacs doc that I cited, which does provide some understandable doc. I don't claim that the GNU Emacs concept (which is unknown to me) is the same as or even similar to the XEmacs concept (which is clearly explained). IOW, internal is one thing; unexplained is another. Good explanation is in the spirit of free software, even if the bottom line is the source code. The function `frame-root-window' seems to be used in the source code in places where I might naively expect the code to use `one-window-p' (with appropriate args and perhaps sometimes additional tests). I don't claim expertise in this regard, obviously. I know that you are knowledgeable about Emacs windows and are no doubt familiar with some of this code (e.g. window.el). I would like to understand why `frame-root-window' is used in these contexts, even if it is not intended for my external use. Thx. From unknown Tue Jun 24 05:10:06 2025 X-Loop: owner@emacsbugs.donarmstrong.com Subject: bug#3598: 23.0.94; doc string of frame-root-window Reply-To: Eli Zaretskii , 3598@debbugs.gnu.org Resent-From: Eli Zaretskii Resent-To: bug-submit-list@lists.donarmstrong.com Resent-CC: Emacs Bugs Resent-Date: Thu, 18 Jun 2009 15:20:05 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-Emacs-PR-Message: followup 3598 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Received: via spool by 3598-submit@emacsbugs.donarmstrong.com id=B3598.124533803823477 (code B ref 3598); Thu, 18 Jun 2009 15:20:05 +0000 Received: (at 3598) by emacsbugs.donarmstrong.com; 18 Jun 2009 15:13:58 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-2.7 required=4.0 tests=AWL,HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from fencepost.gnu.org (fencepost.gnu.org [140.186.70.10]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n5IFDsgu023471 for <3598@emacsbugs.donarmstrong.com>; Thu, 18 Jun 2009 08:13:55 -0700 Received: from eliz by fencepost.gnu.org with local (Exim 4.67) (envelope-from ) id 1MHJJI-0008AS-VT; Thu, 18 Jun 2009 11:13:53 -0400 From: Eli Zaretskii To: Drew Adams , 3598@debbugs.gnu.org CC: rudalics@gmx.at In-reply-to: <29DA79C677954D6FAE4CBEBCB7DEA175@us.oracle.com> (drew.adams@oracle.com) References: <4A3A11DD.4010500@gmx.at> <29DA79C677954D6FAE4CBEBCB7DEA175@us.oracle.com> Message-Id: Date: Thu, 18 Jun 2009 11:13:52 -0400 > From: "Drew Adams" > Date: Thu, 18 Jun 2009 07:05:11 -0700 > Cc: > Reply-To: Drew Adams , 3598@emacsbugs.donarmstrong.com > > If it is an internal function, then please either do not give it a doc string > or, preferably, give it one that calls that out explicitly, and please add a > comment explaining why it is internal. I see no reason not to have doc strings for internal functions. Emacs hackers need doc strings from time to time. Adding "internal use only" to the doc string is the preferred solution. From unknown Tue Jun 24 05:10:06 2025 X-Loop: owner@emacsbugs.donarmstrong.com Subject: bug#3598: 23.0.94; doc string of frame-root-window Reply-To: "Drew Adams" , 3598@debbugs.gnu.org Resent-From: "Drew Adams" Resent-To: bug-submit-list@lists.donarmstrong.com Resent-CC: Emacs Bugs Resent-Date: Thu, 18 Jun 2009 15:25:07 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-Emacs-PR-Message: followup 3598 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Received: via spool by 3598-submit@emacsbugs.donarmstrong.com id=B3598.124533827924307 (code B ref 3598); Thu, 18 Jun 2009 15:25:07 +0000 Received: (at 3598) by emacsbugs.donarmstrong.com; 18 Jun 2009 15:17:59 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-4.3 required=4.0 tests=AWL,FOURLA,HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from rgminet12.oracle.com (rcsinet12.oracle.com [148.87.113.124]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n5IFHtCu024284 for <3598@emacsbugs.donarmstrong.com>; Thu, 18 Jun 2009 08:17:56 -0700 Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by rgminet12.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n5IFHVEv018060 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 18 Jun 2009 15:17:33 GMT Received: from abhmt001.oracle.com (abhmt001.oracle.com [141.146.116.10]) by acsinet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n5IFJ6Rp010041; Thu, 18 Jun 2009 15:19:06 GMT Received: from dradamslap1 (/130.35.178.194) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 18 Jun 2009 08:17:45 -0700 From: "Drew Adams" To: "'Eli Zaretskii'" , <3598@debbugs.gnu.org> Cc: References: <4A3A11DD.4010500@gmx.at> <29DA79C677954D6FAE4CBEBCB7DEA175@us.oracle.com> Date: Thu, 18 Jun 2009 08:17:44 -0700 Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-Reply-To: Thread-Index: AcnwJ2/8u7mIKl3iQ6yi6Aw+B0pR4wAAGI9w X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 X-Source-IP: abhmt001.oracle.com [141.146.116.10] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A010203.4A3A5A9A.00C2:SCFSTAT5015188,ss=1,fgs=0 > > If it is an internal function, then please either do not > > give it a doc string or, preferably, give it one that calls > > that out explicitly, and please add a > > comment explaining why it is internal. > > I see no reason not to have doc strings for internal functions. > Emacs hackers need doc strings from time to time. Adding "internal > use only" to the doc string is the preferred solution. FWIW, I agree 100%. From unknown Tue Jun 24 05:10:06 2025 X-Loop: owner@emacsbugs.donarmstrong.com Subject: bug#3598: 23.0.94; doc string of frame-root-window Reply-To: Lennart Borgman , 3598@debbugs.gnu.org Resent-From: Lennart Borgman Resent-To: bug-submit-list@lists.donarmstrong.com Resent-CC: Emacs Bugs Resent-Date: Thu, 18 Jun 2009 16:55:07 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-Emacs-PR-Message: followup 3598 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Received: via spool by 3598-submit@emacsbugs.donarmstrong.com id=B3598.12453436397134 (code B ref 3598); Thu, 18 Jun 2009 16:55:07 +0000 Received: (at 3598) by emacsbugs.donarmstrong.com; 18 Jun 2009 16:47:19 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-2.4 required=4.0 tests=AWL,FOURLA,HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from mail-bw0-f205.google.com (mail-bw0-f205.google.com [209.85.218.205]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n5IGlE1N007126 for <3598@emacsbugs.donarmstrong.com>; Thu, 18 Jun 2009 09:47:16 -0700 Received: by bwz1 with SMTP id 1so1355884bwz.1 for <3598@emacsbugs.donarmstrong.com>; Thu, 18 Jun 2009 09:47:08 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:received:in-reply-to:references :date:message-id:subject:from:to:cc:content-type :content-transfer-encoding; bh=/nk0yKNtdiXjDJfRgMn0CuJTNVV1EL//6UkZO63rk30=; b=LwgWOok915xzSaKr/eQZ8VBPzCQbacxElD+YkX37e+mKtbr8c9LqX+JrJLEnpYfhoG dT2J8MRVCs/MW9jVudo606uXCtWiKfsErriHHnU7Ca+9XNU6WnG/Hl0I2wH7GBDJtYbv 0HZgkcb+IIcNKBlB6hFs+2wB+sF8w9Uh+rif8= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type:content-transfer-encoding; b=OqvT9KubFgO8P/f72CXrhWo8lypleCfYKaF07EgIJylhytWGMHhyD4D6Zg5OabEMGA bnf600QhUhM/H+uh0fKd3EDmohzihq6HRvZIrEMpXqpsuB9PyOx3AhLvQ6CmSknbw/Nh hDHOGdQ4MnfyACahNuBieVhB6zCJIkbIVLRYI= MIME-Version: 1.0 Received: by 10.239.137.84 with SMTP id k20mr152910hbk.21.1245343628689; Thu, 18 Jun 2009 09:47:08 -0700 (PDT) In-Reply-To: References: <4A3A11DD.4010500@gmx.at> <29DA79C677954D6FAE4CBEBCB7DEA175@us.oracle.com> Date: Thu, 18 Jun 2009 18:47:08 +0200 Message-ID: From: Lennart Borgman To: Drew Adams , 3598@debbugs.gnu.org Cc: Eli Zaretskii Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable On Thu, Jun 18, 2009 at 5:17 PM, Drew Adams wrote: >> > If it is an internal function, then please either do not >> > give it a doc string or, preferably, give it one that calls >> > that out explicitly, and please add a >> > comment explaining why it is internal. >> >> I see no reason not to have doc strings for internal functions. >> Emacs hackers need doc strings from time to time. =C2=A0Adding "internal >> use only" to the doc string is the preferred solution. > > FWIW, I agree 100%. And I agree 150%. At least. In every situation where the semantics of a function may be difficult to understand it is very important to have the doc string describe it. Otherwise both the person who programs the function and the user might be confused. From unknown Tue Jun 24 05:10:06 2025 X-Loop: owner@emacsbugs.donarmstrong.com Subject: bug#3598: 23.0.94; doc string of frame-root-window Reply-To: martin rudalics , 3598@debbugs.gnu.org Resent-From: martin rudalics Resent-To: bug-submit-list@lists.donarmstrong.com Resent-CC: Emacs Bugs Resent-Date: Fri, 19 Jun 2009 09:00:04 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-Emacs-PR-Message: followup 3598 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Received: via spool by 3598-submit@emacsbugs.donarmstrong.com id=B3598.124540149116400 (code B ref 3598); Fri, 19 Jun 2009 09:00:04 +0000 Received: (at 3598) by emacsbugs.donarmstrong.com; 19 Jun 2009 08:51:31 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-4.5 required=4.0 tests=AWL,FOURLA,HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from mail.gmx.net (mail.gmx.net [213.165.64.20]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with SMTP id n5J8pPSb016393 for <3598@emacsbugs.donarmstrong.com>; Fri, 19 Jun 2009 01:51:27 -0700 Received: (qmail invoked by alias); 19 Jun 2009 08:51:19 -0000 Received: from 62-47-32-51.adsl.highway.telekom.at (EHLO [62.47.32.51]) [62.47.32.51] by mail.gmx.net (mp007) with SMTP; 19 Jun 2009 10:51:19 +0200 X-Authenticated: #14592706 X-Provags-ID: V01U2FsdGVkX1++pTo4UvC+ASFuS4CWdkQ9TUq6yH0E/jIP+ttJos W04cu61bEavrWz Message-ID: <4A3B5184.9070808@gmx.at> Date: Fri, 19 Jun 2009 10:51:16 +0200 From: martin rudalics User-Agent: Thunderbird 2.0.0.21 (Windows/20090302) MIME-Version: 1.0 To: Drew Adams CC: 3598@debbugs.gnu.org References: <4A3A11DD.4010500@gmx.at> <29DA79C677954D6FAE4CBEBCB7DEA175@us.oracle.com> In-Reply-To: <29DA79C677954D6FAE4CBEBCB7DEA175@us.oracle.com> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Y-GMX-Trusted: 0 X-FuHaFi: 0.6 >> IIUC `frame-root-window' was deliberately never described >> because up to Emacs 22 it was not always safe to call Lisp >> functions with an internal window as argument. So I think >> this function was intended for internal use only. > > I see. Well, the doc does not reflect that, for one thing. I only expressed my personal thoughts. The person who wrote the doc-string might have had other ideas. > If it is an internal function, then please either do not give it a doc string > or, preferably, give it one that calls that out explicitly, and please add a > comment explaining why it is internal. I simply don't know whether that function was meant to be internal. It has been introduced in 1992. > Second, whether it is internal or not is a different matter from whether its doc > (in the form of doc string or comment) is accurate and helpful. As I mentioned, > the concept of a GNU Emacs "root window" is not explained anywhere, that I can > find. See the XEmacs doc that I cited, which does provide some understandable > doc. I don't claim that the GNU Emacs concept (which is unknown to me) is the > same as or even similar to the XEmacs concept (which is clearly explained). I intend to provide a specification of window trees as soon as I have fully understood the code that constitutes the operations allowed on them. This might still take some time, though. > IOW, internal is one thing; unexplained is another. Good explanation is in the > spirit of free software, even if the bottom line is the source code. But it's sometimes hard to provide explanations for things that have been written more than 15 years ago. I'm no archaeologist. > The function `frame-root-window' seems to be used in the source code in places > where I might naively expect the code to use `one-window-p' (with appropriate > args and perhaps sometimes additional tests). I dislike `one-window-p'. It only operates on the selected window and I mostly try to avoid `save-selected-window' based routines. Moreover, `one-window-p' calls `next-window' and it requires the knowledge of window trees to tell whether that always DTRT in a particular context. (eq window (frame-root-window (window-frame window))) is for me the most trivial way to tell whether `window' stands for "everything but the mini stuff" on its frame. martin From unknown Tue Jun 24 05:10:06 2025 X-Loop: owner@emacsbugs.donarmstrong.com Subject: bug#3598: 23.0.94; doc string of frame-root-window Reply-To: "Drew Adams" , 3598@debbugs.gnu.org Resent-From: "Drew Adams" Resent-To: bug-submit-list@lists.donarmstrong.com Resent-CC: Emacs Bugs Resent-Date: Fri, 19 Jun 2009 21:25:05 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-Emacs-PR-Message: followup 3598 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Received: via spool by 3598-submit@emacsbugs.donarmstrong.com id=B3598.124544633222110 (code B ref 3598); Fri, 19 Jun 2009 21:25:05 +0000 Received: (at 3598) by emacsbugs.donarmstrong.com; 19 Jun 2009 21:18:52 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-4.3 required=4.0 tests=AWL,FOURLA,HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from acsinet12.oracle.com (acsinet12.oracle.com [141.146.126.234]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n5JLImfL022098 for <3598@emacsbugs.donarmstrong.com>; Fri, 19 Jun 2009 14:18:49 -0700 Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by acsinet12.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n5JLIelr010752 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 19 Jun 2009 21:18:41 GMT Received: from abhmt003.oracle.com (abhmt003.oracle.com [141.146.116.12]) by acsinet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n5JLK2fk020805; Fri, 19 Jun 2009 21:20:03 GMT Received: from dradamslap1 (/24.5.177.54) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Fri, 19 Jun 2009 14:18:40 -0700 From: "Drew Adams" To: "'martin rudalics'" Cc: <3598@debbugs.gnu.org> References: <4A3A11DD.4010500@gmx.at> <29DA79C677954D6FAE4CBEBCB7DEA175@us.oracle.com> <4A3B5184.9070808@gmx.at> Date: Fri, 19 Jun 2009 14:18:43 -0700 Message-ID: <212E942BC0954A2F8A2EB4CEDC1EBE55@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <4A3B5184.9070808@gmx.at> Thread-Index: Acnwu1mgklPwH3PUTbOzVVWSeZQysgAZlaPg X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 X-Source-IP: abhmt003.oracle.com [141.146.116.12] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090203.4A3C00B0.01D5:SCFSTAT5015188,ss=1,fgs=0 > > The function `frame-root-window' seems to be used in the > > source code in places where I might naively expect the > > code to use `one-window-p' (with appropriate args and > > perhaps sometimes additional tests). > > I dislike `one-window-p'. What's the alternative (for users)? `frame-root-window' is internal, and undocumented (and I don't understand it). But am I right that this is what `frame-root-window' seems to be used for most of the time: testing whether the window is alone in its frame? > It only operates on the selected window Agreed. (But it's not a big deal to select a window temporarily). > and I mostly try to avoid `save-selected-window' based routines. What is the reason you avoid it? Is it because of performance? I find myself using it more than I would like, but mainly I don't like all of the debugger minutia it goes through, starting with Emacs 22 (21?). I have to remember (and recognize) that I can skip that particular dolist or mapcar etc. that maps over all the frames. In Emacs 20, that doesn't happen (no doubt it is less correct). > Moreover, `one-window-p' calls `next-window' and it requires the knowledge of > window trees to tell whether that always DTRT in a particular context. > > (eq window (frame-root-window (window-frame window))) > > is for me the most trivial way to tell whether `window' stands for > "everything but the mini stuff" on its frame. Then maybe that idiom should be provided as a user function? Or maybe one-window-p should be made more convenient in your terms, so that it can do that? All I mean is that this operation of telling whether a window is alone in its frame is not something that only internal Emacs code needs to do. It is a pretty common operation. If the only choices are (1) a function that you feel is not so great and (2) an internal function, then you must feel that Emacs is missing something for users, no? From unknown Tue Jun 24 05:10:06 2025 X-Loop: owner@emacsbugs.donarmstrong.com Subject: bug#3598: 23.0.94; doc string of frame-root-window Reply-To: martin rudalics , 3598@debbugs.gnu.org Resent-From: martin rudalics Resent-To: bug-submit-list@lists.donarmstrong.com Resent-CC: Emacs Bugs Resent-Date: Sat, 20 Jun 2009 08:15:06 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-Emacs-PR-Message: followup 3598 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Received: via spool by 3598-submit@emacsbugs.donarmstrong.com id=B3598.124548537829375 (code B ref 3598); Sat, 20 Jun 2009 08:15:06 +0000 Received: (at 3598) by emacsbugs.donarmstrong.com; 20 Jun 2009 08:09:38 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-4.5 required=4.0 tests=AWL,FOURLA,HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from mail.gmx.net (mail.gmx.net [213.165.64.20]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with SMTP id n5K89Xv8029349 for <3598@emacsbugs.donarmstrong.com>; Sat, 20 Jun 2009 01:09:34 -0700 Received: (qmail invoked by alias); 20 Jun 2009 08:09:27 -0000 Received: from 62-47-36-173.adsl.highway.telekom.at (EHLO [62.47.36.173]) [62.47.36.173] by mail.gmx.net (mp025) with SMTP; 20 Jun 2009 10:09:27 +0200 X-Authenticated: #14592706 X-Provags-ID: V01U2FsdGVkX187wGYgwt879B6OeYn9/jBBzapifwe2vB6GENl6YW R1vx0cWTsOUnu+ Message-ID: <4A3C98F4.3020109@gmx.at> Date: Sat, 20 Jun 2009 10:08:20 +0200 From: martin rudalics User-Agent: Thunderbird 2.0.0.21 (Windows/20090302) MIME-Version: 1.0 To: Drew Adams CC: 3598@debbugs.gnu.org References: <4A3A11DD.4010500@gmx.at> <29DA79C677954D6FAE4CBEBCB7DEA175@us.oracle.com> <4A3B5184.9070808@gmx.at> <212E942BC0954A2F8A2EB4CEDC1EBE55@us.oracle.com> In-Reply-To: <212E942BC0954A2F8A2EB4CEDC1EBE55@us.oracle.com> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Y-GMX-Trusted: 0 X-FuHaFi: 0.66 >> and I mostly try to avoid `save-selected-window' based routines. > > What is the reason you avoid it? Is it because of performance? Hysterical reasons. Earlier (maybe < 2005) versions failed to restore the current buffer and I spent hours debugging that. I don't even know whether all issues have been fixed by now. > I find myself using it more than I would like, but mainly I don't like all of > the debugger minutia it goes through, starting with Emacs 22 (21?). I have to > remember (and recognize) that I can skip that particular dolist or mapcar etc. > that maps over all the frames. In Emacs 20, that doesn't happen (no doubt it is > less correct). The inherent problem of all `save-selected-window' based routines is the selected window vs current buffer relation. Unfortunately, there's no perfect solution for this since sometimes you want to look at a particular window only to check its geometry or some related settings and IMHO `one-window-p' definitively belongs to that category. Other times you are interested in the buffer shown by the window as well and there it makes well sense to make the window's buffer current too. BTW, in this context note how often Emacs code used to talk (and occasionally still does) about selected buffers and current windows. > Then maybe that idiom should be provided as a user function? Or maybe > one-window-p should be made more convenient in your terms, so that it can do > that? > > All I mean is that this operation of telling whether a window is alone in its > frame is not something that only internal Emacs code needs to do. It is a pretty > common operation. If the only choices are (1) a function that you feel is not so > great and (2) an internal function, then you must feel that Emacs is missing > something for users, no? I most certainly do. But I'm not sure whether it'd better to rewrite `one-window-p' or provide a separate function. martin From rgm@gnu.org Wed Nov 4 14:01:42 2009 Received: (at control) by emacsbugs.donarmstrong.com; 4 Nov 2009 22:01:42 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-3.8 required=4.0 tests=AWL,ONEWORD,VALID_BTS_CONTROL autolearn=no version=3.2.5-bugs.debian.org_2005_01_02 Received: from fencepost.gnu.org (fencepost.gnu.org [140.186.70.10]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id nA4M1e7A002782 for ; Wed, 4 Nov 2009 14:01:42 -0800 Received: from rgm by fencepost.gnu.org with local (Exim 4.67) (envelope-from ) id 1N5nv9-0000E4-Ub; Wed, 04 Nov 2009 17:01:39 -0500 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <19185.63939.653937.427902@fencepost.gnu.org> Date: Wed, 4 Nov 2009 17:01:39 -0500 From: Glenn Morris To: control Subject: control severity 3631 minor severity 3267 minor reassign 3267 emacsbugs.donarmstrong.com severity 3481 minor severity 3644 minor severity 3722 wishlist severity 4360 minor tags 3613 wontfix tags 2134 = severity 4731 minor severity 3849 wishlist close 3564 merge 4668 3227 tags 2792 wontfix minor severity 4433 minor severity 4668 minor severity 4562 minor severity 3934 minor severity 3856 minor severity 3801 minor severity 3615 minor severity 3599 minor severity 3598 minor severity 3575 minor severity 3566 minor severity 3550 minor severity 3549 minor severity 3527 minor severity 3525 minor severity 3524 minor severity 3523 minor severity 3519 minor severity 3509 minor severity 3503 minor severity 3393 minor severity 3371 minor severity 3320 minor severity 3313 minor severity 3249 minor severity 3227 minor severity 3138 minor severity 3135 minor severity 3137 minor severity 3052 minor severity 3042 minor severity 2974 minor severity 2946 minor severity 2792 minor severity 1749 minor severity 1375 minor severity 1144 minor From debbugs-submit-bounces@debbugs.gnu.org Tue Jan 26 17:59:30 2010 Received: (at control) by debbugs.gnu.org; 26 Jan 2010 22:59:30 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1NZuNe-0006Wg-50 for submit@debbugs.gnu.org; Tue, 26 Jan 2010 17:59:30 -0500 Received: from fencepost.gnu.org ([140.186.70.10]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1NZuNc-0006Wa-Ri for control@debbugs.gnu.org; Tue, 26 Jan 2010 17:59:29 -0500 Received: from rgm by fencepost.gnu.org with local (Exim 4.69) (envelope-from ) id 1NZuNZ-0005iV-10; Tue, 26 Jan 2010 17:59:25 -0500 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <19295.29644.873399.225898@fencepost.gnu.org> Date: Tue, 26 Jan 2010 17:59:24 -0500 From: Glenn Morris To: control Subject: control X-Attribution: GM X-Mailer: VM (www.wonderworks.com/vm), GNU Emacs (www.gnu.org/software/emacs) X-Hue: green X-Ran: &(VbNfmJXZ;[J{*G3aTbd+b!ecJ2-$GFxDMQQe0OAuT_7w/9GVc(bITh-`eB%[Y;QuxJkO X-Debbugs-No-Ack: yes X-Spam-Score: -5.0 (-----) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -5.0 (-----) merge 3598 3599 severity 3625 wishlist tags 3634 moreinfo severity 3639 minor unmerge 3728