bug#31858: 27.0; doc of `window-toggle-side-windows'

bug#31858: 27.0; doc of `window-toggle-side-windows'

[Drew Adams]

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''

bug#31858: 27.0; doc of `window-toggle-side-windows'

[Eli Zaretskii]

> 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?

bug#31858: 27.0; doc of `window-toggle-side-windows'

[Drew Adams]

> > 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.

bug#31858: 27.0; doc of `window-toggle-side-windows'

[Noam Postavsky]

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..."

bug#31858: 27.0; doc of `window-toggle-side-windows'

[Drew Adams]

> > 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.

bug#31858: 27.0; doc of `window-toggle-side-windows'

[Eli Zaretskii]

> 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?

bug#31858: 27.0; doc of `window-toggle-side-windows'

[Drew Adams]

> 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?

It's definitely an improvement.

bug#31858: 27.0; doc of `window-toggle-side-windows'

[Eli Zaretskii]

> Date: Sat, 16 Jun 2018 21:20:44 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: npostavs@gmail.com, 31858@debbugs.gnu.org
> 
> > 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?
> 
> It's definitely an improvement.

OK, I did that, and also changed the wording to be a bit more
reader-friendly.

bug#31858: 27.0; doc of `window-toggle-side-windows'

[martin rudalics]

 > OK, I did that, and also changed the wording to be a bit more
 > reader-friendly.

Thank you!

martin

bug#31858: 27.0; doc of `window-toggle-side-windows'

[Drew Adams]

> OK, I did that, and also changed the wording to be a bit more
> reader-friendly.

Thank you.