bug#22104: 25.1.50; doc string of `modify-frame-parameters'

bug#22104: 25.1.50; doc string of `modify-frame-parameters'

[Drew Adams]

This part of the doc string is unclear:

 Undefined PARMs are ignored, but stored in the frame's parameter list
 so that 'frame-parameters' will return them.

What does "ignored" mean here?  It can only mean (?) ignored by
`modify-parameters', but what does that mean, operationally?

The rest of the sentence would lead you to think that
`modify-parameters' nevertheless updates the parameter list for 
"ignored" parameters.  But then in what way are they ignored?




In GNU Emacs 25.1.50.1 (i686-pc-mingw32)
 of 2015-12-04
Bzr revision: ffefb6e899fbcdcbd79cb34292d57b7bc3043fcc
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk --enable-checking=yes
 --enable-check-lisp-object-type --without-compress-install 'CFLAGS=-Og
 -ggdb3' LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

bug#22104: 25.1.50; doc string of `modify-frame-parameters'

[Eli Zaretskii]

> Date: Sun, 6 Dec 2015 19:58:11 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> This part of the doc string is unclear:
> 
>  Undefined PARMs are ignored, but stored in the frame's parameter list
>  so that 'frame-parameters' will return them.
> 
> What does "ignored" mean here?  It can only mean (?) ignored by
> `modify-parameters', but what does that mean, operationally?

It means they have no effect beyond being stored in the parameter
list.  I will clarify that.

bug#22104: 25.1.50; doc string of `modify-frame-parameters'

[Drew Adams]

> > This part of the doc string is unclear:
> >
> >  Undefined PARMs are ignored, but stored in the frame's parameter list
> >  so that 'frame-parameters' will return them.
> >
> > What does "ignored" mean here?  It can only mean (?) ignored by
> > `modify-parameters', but what does that mean, operationally?
> 
> It means they have no effect beyond being stored in the parameter
> list.  I will clarify that.

But I still don't understand, from that description.  What else
does `modify-frame-parameters' ever do, besides store them in the
parameter list?  Am I missing something?  (I thought the doc in the
manual was enough.)

bug#22104: 25.1.50; doc string of `modify-frame-parameters'

[Eli Zaretskii]

> Date: Mon, 7 Dec 2015 09:34:28 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 22104@debbugs.gnu.org
> 
> > > This part of the doc string is unclear:
> > >
> > >  Undefined PARMs are ignored, but stored in the frame's parameter list
> > >  so that 'frame-parameters' will return them.
> > >
> > > What does "ignored" mean here?  It can only mean (?) ignored by
> > > `modify-parameters', but what does that mean, operationally?
> > 
> > It means they have no effect beyond being stored in the parameter
> > list.  I will clarify that.
> 
> But I still don't understand, from that description.  What else
> does `modify-frame-parameters' ever do, besides store them in the
> parameter list?

Quite a few parameters require modify-frame-parameters to call some
API in order to put the parameter in effect.  For example,
background-color -- just storing the new value won't magically change
the color, would it?

IOW, modify-frame-parameters is not just for altering the params
alist, it is primarily for changing the frame according to the changed
parameters; it records the parameters in effect in the alist mostly as
a side effect.

Yes, "modify the frame parameters" is ambiguous.

bug#22104: 25.1.50; doc string of `modify-frame-parameters'

[Drew Adams]

> > > > This part of the doc string is unclear:
> > > >
> > > >  Undefined PARMs are ignored, but stored in the frame's parameter
> list
> > > >  so that 'frame-parameters' will return them.
> > > >
> > > > What does "ignored" mean here?  It can only mean (?) ignored by
> > > > `modify-parameters', but what does that mean, operationally?
> > >
> > > It means they have no effect beyond being stored in the parameter
> > > list.  I will clarify that.
> >
> > But I still don't understand, from that description.  What else
> > does `modify-frame-parameters' ever do, besides store them in the
> > parameter list?
> 
> Quite a few parameters require modify-frame-parameters to call some
> API in order to put the parameter in effect.  For example,
> background-color -- just storing the new value won't magically change
> the color, would it?
> 
> IOW, modify-frame-parameters is not just for altering the params
> alist, it is primarily for changing the frame according to the changed
> parameters; it records the parameters in effect in the alist mostly as
> a side effect.
> 
> Yes, "modify the frame parameters" is ambiguous.

OK, so I guess the point is that unrecognized (perhaps a better term than "undefined", here) parameters are simply stored in the frame's parameter
list.  No extra handling is done.

I think that statement can just be removed.  No one would guess that
any special, additional action would be undertaken for a parameter that
Emacs does not recognize.  Talking about this just confuses readers.

Users should know that they can add any parameters they want, which
are unknown to Emacs.  But because Emacs knows nothing about them it
is up to a user to provide any expected behavior for them.

It is important to say that users can add their own parameters.

And I guess it is helpful to add that Emacs does not do anything
with them (unless the user programs it to do so).  But if we can't
do that without confusing readers more, then this addition should
be dropped, IMO.

bug#22104: 25.1.50; doc string of `modify-frame-parameters'

[Eli Zaretskii]

> Date: Mon, 7 Dec 2015 10:07:49 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 22104@debbugs.gnu.org
> 
> I think that statement can just be removed.

I believe this feature is used to make "frame-local" variables.  So
removing that sentence will lose information.

> No one would guess that any special, additional action would be
> undertaken for a parameter that Emacs does not recognize.

But it could well barf for such a parameter, at least in principle.
So that sentence does add useful information.

> It is important to say that users can add their own parameters.
> 
> And I guess it is helpful to add that Emacs does not do anything
> with them (unless the user programs it to do so).  But if we can't
> do that without confusing readers more, then this addition should
> be dropped, IMO.

Oh, I think we have all the technology necessary to say that in a way
that won't confuse users.

bug#22104: 25.1.50; doc string of `modify-frame-parameters'

[Drew Adams]

> > I think that statement can just be removed.
> 
> I believe this feature is used to make "frame-local" variables.  So
> removing that sentence will lose information.

How so? Is that explained somewhere (e.g. in the manual)?
I know nothing about this, and the statement in the doc string
leaves me clueless.

> > No one would guess that any special, additional action would be
> > undertaken for a parameter that Emacs does not recognize.
> 
> But it could well barf for such a parameter, at least in principle.
> So that sentence does add useful information.

Really?  That would be a bug, no?  Why should it not accept a
user-supplied parameter?

As for that sentence adding useful info - I cannot agree.
Frankly, it just confuses me.

When you say that Emacs might barf, given a parameter it doesn't
recognize, that is not at all conveyed by a statement that Emacs
doesn't do anything with it except store it as a frame parameter.

Sorry, but this is not at all clear to me now - neither what
Emacs really does (possibly barfs?) nor how that statement is
supposed to help understanding (including about frame-local vars
and the possibility that Emacs might barf).

> > It is important to say that users can add their own parameters.
> >
> > And I guess it is helpful to add that Emacs does not do anything
> > with them (unless the user programs it to do so).  But if we can't
> > do that without confusing readers more, then this addition should
> > be dropped, IMO.
> 
> Oh, I think we have all the technology necessary to say that in a way
> that won't confuse users.

OK, I trust you will; thanks.  You've heard my concerns/confusions,
at least.  Maybe they will help you decide what to say, and how.