* bug#31858: 27.0; doc of `window-toggle-side-windows'
@ 2018-06-16 12:35 Drew Adams
2018-06-16 16:28 ` Eli Zaretskii
0 siblings, 1 reply; 10+ messages in thread
From: Drew Adams @ 2018-06-16 12:35 UTC (permalink / raw)
To: 31858
AFAICT, neither the doc string nor the manual says what toggling the
side windows DOES or MEANS. Just what behavior or appearance is
toggled? What happens when a side window is - or all side windows are -
toggled?
The command is said to be "handy to toggle the appearance of all side
windows on a specified frame". But I have no idea what that appearance
toggling amounts to. Does it swap left for right windows and top for
bottom? Does it hide/show the currently shown/hidden side windows?
Does it reverse the order? Does it change the focus? Just what gets
toggled?
In GNU Emacs 27.0.50 (build 3, x86_64-w64-mingw32)
of 2018-03-21
Repository revision: e70d0c9e66d7a8609450b2889869d16aeb0363b5
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
`configure --without-dbus --host=x86_64-w64-mingw32
--without-compress-install -C 'CFLAGS=-O2 -static -g3''
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#31858: 27.0; doc of `window-toggle-side-windows'
2018-06-16 12:35 bug#31858: 27.0; doc of `window-toggle-side-windows' Drew Adams
@ 2018-06-16 16:28 ` Eli Zaretskii
2018-06-16 23:11 ` Drew Adams
0 siblings, 1 reply; 10+ messages in thread
From: Eli Zaretskii @ 2018-06-16 16:28 UTC (permalink / raw)
To: Drew Adams; +Cc: 31858
> Date: Sat, 16 Jun 2018 05:35:10 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
>
> AFAICT, neither the doc string nor the manual says what toggling the
> side windows DOES or MEANS. Just what behavior or appearance is
> toggled? What happens when a side window is - or all side windows are -
> toggled?
That's strange. I found answers to those questions in the doc string:
If FRAME has at least one side window, save FRAME’s state in the
FRAME’s ‘window-state’ frame parameter and delete all side
windows on FRAME afterwards. Otherwise, if FRAME has a
‘window-state’ parameter, use that to restore any side windows on
FRAME leaving FRAME’s main window alone. Signal an error if
FRAME has no side window and no saved state is found.
So I don't understand what is missing there. Could you be more
specific regarding the problems you see in this text?
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#31858: 27.0; doc of `window-toggle-side-windows'
2018-06-16 16:28 ` Eli Zaretskii
@ 2018-06-16 23:11 ` Drew Adams
2018-06-16 23:18 ` Noam Postavsky
0 siblings, 1 reply; 10+ messages in thread
From: Drew Adams @ 2018-06-16 23:11 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 31858
> > AFAICT, neither the doc string nor the manual says what toggling the
> > side windows DOES or MEANS. Just what behavior or appearance is
> > toggled? What happens when a side window is - or all side windows are
> -
> > toggled?
>
> That's strange. I found answers to those questions in the doc string:
>
> If FRAME has at least one side window, save FRAME’s state in the
> FRAME’s ‘window-state’ frame parameter and delete all side
> windows on FRAME afterwards. Otherwise, if FRAME has a
> ‘window-state’ parameter, use that to restore any side windows on
> FRAME leaving FRAME’s main window alone. Signal an error if
> FRAME has no side window and no saved state is found.
>
> So I don't understand what is missing there. Could you be more
> specific regarding the problems you see in this text?
The doc should say that the function deletes all side windows
of FRAME, or it restores all such previously deleted side windows.
There currently is no statement of just what gets toggled.
The toggling behavior is described, but what's not said is
that it is the presence/existence/validity (pick the right
term) of the side windows that is toggled.
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#31858: 27.0; doc of `window-toggle-side-windows'
2018-06-16 23:11 ` Drew Adams
@ 2018-06-16 23:18 ` Noam Postavsky
2018-06-17 0:14 ` Drew Adams
0 siblings, 1 reply; 10+ messages in thread
From: Noam Postavsky @ 2018-06-16 23:18 UTC (permalink / raw)
To: Drew Adams; +Cc: 31858
Drew Adams <drew.adams@oracle.com> writes:
>> > AFAICT, neither the doc string nor the manual says what toggling the
>> > side windows DOES or MEANS. Just what behavior or appearance is
>> > toggled? What happens when a side window is - or all side windows are
>> > toggled?
>>
>> That's strange. I found answers to those questions in the doc string:
>>
>> If FRAME has at least one side window, save FRAME’s state in the
>> FRAME’s ‘window-state’ frame parameter and delete all side
^^^^^^^^^^^^^^^
>> windows on FRAME afterwards. Otherwise, if FRAME has a
^^^^^^^^^^^^^^^^
>> ‘window-state’ parameter, use that to restore any side windows on
^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> FRAME leaving FRAME’s main window alone. Signal an error if
^^^^^
>> FRAME has no side window and no saved state is found.
>>
>> So I don't understand what is missing there. Could you be more
>> specific regarding the problems you see in this text?
>
> The doc should say that the function deletes all side windows
> of FRAME, or it restores all such previously deleted side windows.
Seems like it does say that?
> There currently is no statement of just what gets toggled.
?
> The toggling behavior is described, but what's not said is
> that it is the presence/existence/validity (pick the right
> term) of the side windows that is toggled.
It's the first sentence of the quoted paragraph: "If FRAME has at least
one side window..."
^ permalink raw reply [flat|nested] 10+ messages in thread* bug#31858: 27.0; doc of `window-toggle-side-windows'
2018-06-16 23:18 ` Noam Postavsky
@ 2018-06-17 0:14 ` Drew Adams
2018-06-17 3:46 ` Eli Zaretskii
0 siblings, 1 reply; 10+ messages in thread
From: Drew Adams @ 2018-06-17 0:14 UTC (permalink / raw)
To: Noam Postavsky; +Cc: 31858
> > The doc should say that the function deletes all side windows
> > of FRAME, or it restores all such previously deleted side windows.
>
> 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 “valid window” is one that is either live or internal.
A valid window can be “deleted”, 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.
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#31858: 27.0; doc of `window-toggle-side-windows'
2018-06-17 0:14 ` Drew Adams
@ 2018-06-17 3:46 ` Eli Zaretskii
0 siblings, 0 replies; 10+ messages in thread
From: Eli Zaretskii @ 2018-06-17 3:46 UTC (permalink / raw)
To: Drew Adams; +Cc: 31858, npostavs
> Date: Sat, 16 Jun 2018 17:14:56 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, 31858@debbugs.gnu.org
>
> What's toggled here?
Would replacing this:
Toggle side windows on specified FRAME.
with this:
Toggle display of side windows on specified FRAME.
solve your problem with this doc string?
^ permalink raw reply [flat|nested] 10+ messages in thread
[parent not found: <<65951719-2046-44e9-8946-692a7a15d6d0@default>]
[parent not found: <<<65951719-2046-44e9-8946-692a7a15d6d0@default>]
end of thread, other threads:[~2018-06-17 14:22 UTC | newest]
Thread overview: 10+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2018-06-16 12:35 bug#31858: 27.0; doc of `window-toggle-side-windows' Drew Adams
2018-06-16 16:28 ` Eli Zaretskii
2018-06-16 23:11 ` Drew Adams
2018-06-16 23:18 ` Noam Postavsky
2018-06-17 0:14 ` Drew Adams
2018-06-17 3:46 ` Eli Zaretskii
[not found] <<65951719-2046-44e9-8946-692a7a15d6d0@default>
[not found] ` <<837emyzofh.fsf@gnu.org>
[not found] ` <<294e533a-0cd8-417f-b83c-f40c2ebb8ed9@default>
[not found] ` <<87in6itj6c.fsf@gmail.com>
[not found] ` <<1e768b88-46ea-4e55-9403-2ce27d1cc63c@default>
[not found] ` <<83wouyxegg.fsf@gnu.org>
2018-06-17 4:20 ` Drew Adams
2018-06-17 5:43 ` Eli Zaretskii
2018-06-17 7:53 ` martin rudalics
[not found] <<<65951719-2046-44e9-8946-692a7a15d6d0@default>
[not found] ` <<<837emyzofh.fsf@gnu.org>
[not found] ` <<<294e533a-0cd8-417f-b83c-f40c2ebb8ed9@default>
[not found] ` <<<87in6itj6c.fsf@gmail.com>
[not found] ` <<<1e768b88-46ea-4e55-9403-2ce27d1cc63c@default>
[not found] ` <<<83wouyxegg.fsf@gnu.org>
[not found] ` <<18382c51-ad2f-499a-a6d7-02e802abb908@default>
[not found] ` <<83po0qx915.fsf@gnu.org>
2018-06-17 14:22 ` Drew Adams
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).