From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#31858: 27.0; doc of `window-toggle-side-windows' Date: Sat, 16 Jun 2018 17:14:56 -0700 (PDT) Message-ID: <1e768b88-46ea-4e55-9403-2ce27d1cc63c@default> References: <65951719-2046-44e9-8946-692a7a15d6d0@default> <837emyzofh.fsf@gnu.org> <294e533a-0cd8-417f-b83c-f40c2ebb8ed9@default> <87in6itj6c.fsf@gmail.com> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1529194448 20228 195.159.176.226 (17 Jun 2018 00:14:08 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 17 Jun 2018 00:14:08 +0000 (UTC) Cc: 31858@debbugs.gnu.org To: Noam Postavsky Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Jun 17 02:14:04 2018 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 1fULKU-000540-Am for geb-bug-gnu-emacs@m.gmane.org; Sun, 17 Jun 2018 02:14:02 +0200 Original-Received: from localhost ([::1]:53252 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fULMb-00089C-BN for geb-bug-gnu-emacs@m.gmane.org; Sat, 16 Jun 2018 20:16:13 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:52492) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fULMT-00088u-MP for bug-gnu-emacs@gnu.org; Sat, 16 Jun 2018 20:16:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fULMQ-0008Qo-9o for bug-gnu-emacs@gnu.org; Sat, 16 Jun 2018 20:16:05 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:44423) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fULMQ-0008Qj-5w for bug-gnu-emacs@gnu.org; Sat, 16 Jun 2018 20:16:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1fULMQ-0007t5-00 for bug-gnu-emacs@gnu.org; Sat, 16 Jun 2018 20:16: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: Sun, 17 Jun 2018 00:16:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 31858 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 31858-submit@debbugs.gnu.org id=B31858.152919450830263 (code B ref 31858); Sun, 17 Jun 2018 00:16:01 +0000 Original-Received: (at 31858) by debbugs.gnu.org; 17 Jun 2018 00:15:08 +0000 Original-Received: from localhost ([127.0.0.1]:52320 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fULLY-0007s3-48 for submit@debbugs.gnu.org; Sat, 16 Jun 2018 20:15:08 -0400 Original-Received: from userp2130.oracle.com ([156.151.31.86]:44928) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fULLV-0007rG-6q for 31858@debbugs.gnu.org; Sat, 16 Jun 2018 20:15:06 -0400 Original-Received: from pps.filterd (userp2130.oracle.com [127.0.0.1]) by userp2130.oracle.com (8.16.0.22/8.16.0.22) with SMTP id w5H0ExwA039425; Sun, 17 Jun 2018 00:14:59 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2017-10-26; bh=n2+LblvwZEirB9kPqDY7eTx8hkXQbnCUuaW7Ou9oFM8=; b=OJeJoLSNItz/SdyTUDuG1DHpC9Q17dzTKsxul5zXeby3dnROFQL/n2P+3Nd0Jf1WlJSl 3ZNALRndof8xt1BMwpjFJdbY64TbUYHcHcI//SxIpsUhUiBSXTKubeIVLP6zc/LTcmqC zbe1j87upP1tlntr39zaUcRu4BQLHcFliyhz+hN/AWt44F0PDKd91PzTziqEtwhfOfAT oqdwDkYCJQGrjZlclXaeR5zG0AvSH3ItmmJ/TCQFWWgECnaAab8mdbsVmiRaBqgBbSQL i9MgK8O15RzJzew3VSU6VvxZNPGuLNdGX2AKEeJpXk4Z/mOTcvjdkoBlJjg2QYO7TPX6 7A== Original-Received: from userv0022.oracle.com (userv0022.oracle.com [156.151.31.74]) by userp2130.oracle.com with ESMTP id 2jmt0194jr-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 17 Jun 2018 00:14:59 +0000 Original-Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by userv0022.oracle.com (8.14.4/8.14.4) with ESMTP id w5H0Ex5v025722 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 17 Jun 2018 00:14:59 GMT Original-Received: from abhmp0007.oracle.com (abhmp0007.oracle.com [141.146.116.13]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id w5H0EwKN010650; Sun, 17 Jun 2018 00:14:58 GMT In-Reply-To: <87in6itj6c.fsf@gmail.com> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4690.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=8926 signatures=668702 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1805220000 definitions=main-1806170001 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:147550 Archived-At: > > The doc should say that the function deletes all side windows > > of FRAME, or it restores all such previously deleted side windows. >=20 > Seems like it does say that? Not in so many words. You have to read carefully to figure out just what's being toggled here: the presence/validity of (all) side windows. If the function were called `delete/restore-side-windows' then there would be no problem. The doc string would then only need to make clear that this means _all_ side windows. End of story. We can guess what deleting and restoring a window means. But toggling a window? When the name is "toggle" the doc should (explicitly) say what it is that is toggled - what state/quality. A name such as `toggle-foo-visibility' makes clear that it is the _visibility_ of a foo or foo's that gets toggled. What's toggled here? Surely it's not a "window" (unless you want to explicitly define "toggling" a window to mean what this function does). Here, the name of the state that is toggled is (apparently) the presence, or the existence, or (I guess) the "validity" of side windows. The paragraph you mention describes the deletion and restoring action, but it doesn't name the state/quality that is _toggled_. That's all. "toggle the _appearance_ of all side windows" sounds to me like perhaps something about the appearance - _how_ it looks gets toggled. In fact, IIUC it is the "validity" of the side windows that gets toggled. Not really their existence or their appearance or their presences (in Lisp), but their "validity". I think the doc says that "deletion" of a window object does not mean that the object no longer exists: it can be restored. Sounds similar to, say, overlays. When we "delete" an overlay we don't say that its "appearance" changes or is "toggled". We do carefully point out, just as we do for windows, that the overlay object continues to exist etc. We should use whatever the appropriate terminology is, for windows. I'm no expert on what term is best here. A quick reading of the window doc gave me the impression that the term is "validity" - deleted window objects exist but are not "valid". A =E2=80=9Cvalid window=E2=80=9D is one that is either live or internal. A valid window can be =E2=80=9Cdeleted=E2=80=9D, i.e., removed from its frame (*note Deleting Windows::); then it is no longer valid, but the Lisp object representing it might be still referenced from other Lisp objects. A deleted window may be made valid again by restoring a saved window configuration (*note Window Configurations::). -- node `Basic Windows' (That also defines what "deleting" a window means, BTW. If the doc string pointed to that manual node, it wouldn't hurt.) All I can say is that saying that the side "_windows are toggled_" doesn't make sense. That's OK for a function name, but not for an explanation. Or if you really want to talk about "toggling a window" then please add something like "toggling a window means...". I guess that here it means just what I said: "the function deletes all side windows ... or it restores all such previously deleted side windows." HTH.