bug#51465: 27.2; `face-all-attributes' doc or behavior (?)

bug#51465: 27.2; `face-all-attributes' doc or behavior (?)

[Drew Adams]

emacs -Q

Set eval-expression-print-length to nil for the session.

 (face-all-attributes 'region) ; C-x C-e

Shows all attributes, including :background, with value `unspecified'.

 (face-all-attributes 'region (selected-frame)) ; C-x C-e

Shows attribute :background with value "LightGoldenrod".

The doc string of `face-all-attributes' says that a nil second arg
means use "the default attributes".

What does that mean - what are the default attributes?  I was expecting
that it meant the default settings for the face: default set of
attributes with their default values for that face.

(elisp) `Attribute Functions' says "the default attributes of FACE for
newly created frames".  I would expect to see :background as
"LightGoldenrod", not as `unspecified'.

If arg FRAME is specified (as a frame) then the function returns the
attributes of FACE on FRAME.  Not sure what that means either - faces
have different attributes on different frames?

If I do `M-x customize-face region' from emacs -Q I see :background set
as "LightGoldenrod".  That command customizes the face for all frames,
no?  So doesn't that mean that the face has that background for all
frames (by default)?

Why would one want to get a list of the face's attributes with every
attribute value as `unspecified'?  More importantly, how to get the
actual (default) values "for all frames" - what you see when you use
`customize-face'?

I feel I must be missing something obvious, here.  But the Elisp manual
didn't make things any clearer.

___

You can let me know if the rest of this report should be posted as a
separate bug report.  But perhaps you could just let me know what I'm
missing in this regard too, if that's simple to do.

My question is why do we have the &rest argument ARGUMENTS of
`set-face-attribute' be a plist, but what `face-all-attributes' returns
is an alist?  Just to do something like the following isn't possible:

(apply #'set-face-attribute 'some-face
                            nil
                            (face-all-attributes 'other-face))

To accomplish that you need to convert the alist returned by
`face-all-attributes' to a plist, and pass that to `set-face-attribute'.
Why?  What other uses of these two functions would suggest that they
should use different ways to express the list of face attributes?


In GNU Emacs 27.2 (build 1, x86_64-w64-mingw32)
 of 2021-03-26 built on CIRROCUMULUS
Repository revision: deef5efafb70f4b171265b896505b92b6eef24e6
Repository branch: HEAD
Windowing system distributor 'Microsoft Corp.', version 10.0.19042
System Description: Microsoft Windows 10 Pro (v10.0.2009.19042.1288)

bug#51465: 27.2; `face-all-attributes' doc or behavior (?)

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Thu, 28 Oct 2021 19:08:53 +0000
> 
> What does that mean - what are the default attributes?  I was expecting
> that it meant the default settings for the face: default set of
> attributes with their default values for that face.

"Default attributes" and "default settings for the face" are one and
the same.

> (elisp) `Attribute Functions' says "the default attributes of FACE for
> newly created frames".  I would expect to see :background as
> "LightGoldenrod", not as `unspecified'.

Why? because that's what you actually see in a new frame?  Those
aren't the default attributes, those are the attributes specified by
defface.

> If arg FRAME is specified (as a frame) then the function returns the
> attributes of FACE on FRAME.  Not sure what that means either - faces
> have different attributes on different frames?

Of course.  Faces are, and always were, specific to frames.  You can
change face attributes on one frame without affecting any other
frames.

> If I do `M-x customize-face region' from emacs -Q I see :background set
> as "LightGoldenrod".

Because that shows the face on the current frame.

> That command customizes the face for all frames,
> no?

Yes.

> So doesn't that mean that the face has that background for all
> frames (by default)?

No.

> Why would one want to get a list of the face's attributes with every
> attribute value as `unspecified'?

I don't know.  I guess those defaults are not very interesting,
indeed.

> More importantly, how to get the actual (default) values "for all
> frames"

There's no such thing.  You must supply a frame to answer that
question.

bug#51465: [External] : Re: bug#51465: 27.2; `face-all-attributes' doc or behavior (?)

[Drew Adams]

> > (elisp) `Attribute Functions' says "the default attributes of FACE
> > for newly created frames".  I would expect to see :background as
> > "LightGoldenrod", not as `unspecified'.
> 
> Why? because that's what you actually see in a new frame?  Those
> aren't the default attributes, those are the attributes specified by
> defface.

The Elisp manual says it returns "the default attributes
of FACE for newly created frames."

Whenever I create a new frame (from emacs -Q) that face
on that frame has a :background of "LightGoldenrod" -
never `unspecified'.  Is the manual wrong?  Or are the
manual and the doc string trying to say the same thing
but ending up suggesting different things?

To me, the manual's text suggests I'd expect to see
"LightGoldenrod", with emacs -Q, based on a GUI Emacs.
The defface for `region' and a light background with at
least 88 colors specifies "lightgoldenrod2".

> > Why would one want to get a list of the face's attributes
> > with every attribute value as `unspecified'?
> 
> I don't know.  I guess those defaults are not very interesting,
> indeed.

Unless otherwise specified (which could be by
`default-frame-alist' or whatever) a newly created
frame has, according to the manual, the attributes
for that face that are given by `face-all-attributes'
when that function is passed a nil FRAME arg: "the
default attributes of FACE for newly created frames."

IOW, it calls this "the default attributes" for
"newly created frames", not the attributes for some
existing frame (this is the FRAME=nil case).

And yet, with emacs -Q, every newly created frame
has :background set to "LightGoldenrod" (AFAICT).
At the very least, most, if not all, newly created
frames have that attribute value.  None have that
attribute with a value of `unspecified'.

The function returns `unspecified' as the default
for newly created frames (for this FACE's background).
But it seems that the actual default for newly
created frames is "LightGoldenrod".  Perhaps there
are multiple, unexplained meanings of "default"
involved here?

I'd think that "default" would just mean what you
get for a newly created frame unless there is
something that overrides that somehow.  I'd think
that "default" is what the current customized value
of the face has - that's what you get by default for
a newly created frame (or if it's not customized
then the value given by the original defface).

I'm hoping you at least see a possibility for
confusion in the doc.  And maybe even a problematic
behavior (what's the point of returning `unspecified'
everywhere?).
____

You didn't address my question about the seeming
impedance mismatch between what `set-face-attribute'
accepts as a list of attributes and what
`face-all-attributes' returns as a list of attributes.
So I submitted a separate bug report for that: #51469.

bug#51465: [External] : Re: bug#51465: 27.2; `face-all-attributes' doc or behavior (?)

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "51465@debbugs.gnu.org" <51465@debbugs.gnu.org>
> Date: Thu, 28 Oct 2021 23:08:42 +0000
> 
> > > (elisp) `Attribute Functions' says "the default attributes of FACE
> > > for newly created frames".  I would expect to see :background as
> > > "LightGoldenrod", not as `unspecified'.
> > 
> > Why? because that's what you actually see in a new frame?  Those
> > aren't the default attributes, those are the attributes specified by
> > defface.
> 
> The Elisp manual says it returns "the default attributes
> of FACE for newly created frames."
> 
> Whenever I create a new frame (from emacs -Q) that face
> on that frame has a :background of "LightGoldenrod" -
> never `unspecified'.  Is the manual wrong?

No, it isn't wrong: the "default attributes for newly created frames"
are those the face has before applying the definitions in defface.

Note that the description of face-attribute in the same section
already hints on what is going on here:

                      If FRAME is ‘t’, this function returns the value
     of the specified attribute for newly-created frames (this is
     normally ‘unspecified’, unless you have specified some value using
     ‘set-face-attribute’; see below).

If you use set-face-attribute with the FRAME argument t to set some
attribute's value, the next call to face-all-attributes will no longer
show 'unspecified' for that attribute.  And the next frame created
after that will use the attribute value you specified, effectively
overriding the corresponding attribute's value defined by defface.

> Unless otherwise specified (which could be by
> `default-frame-alist' or whatever) a newly created
> frame has, according to the manual, the attributes
> for that face that are given by `face-all-attributes'
> when that function is passed a nil FRAME arg: "the
> default attributes of FACE for newly created frames."
> 
> IOW, it calls this "the default attributes" for
> "newly created frames", not the attributes for some
> existing frame (this is the FRAME=nil case).
> 
> And yet, with emacs -Q, every newly created frame
> has :background set to "LightGoldenrod" (AFAICT).
> At the very least, most, if not all, newly created
> frames have that attribute value.  None have that
> attribute with a value of `unspecified'.

That's because defface's definitions are merged with those defaults,
when the frame is created, which in this case yields the
non-unspecified background color.  So you rarely if ever see those
default attributes, except if you call this function.

> I'd think that "default" would just mean what you
> get for a newly created frame unless there is
> something that overrides that somehow.

That is correct, and that is what happens here; see above.

> I'd think that "default" is what the current customized value of the
> face has - that's what you get by default for a newly created frame
> (or if it's not customized then the value given by the original
> defface).

Right.  But the default values are before merging the defface's
definitions.

> I'm hoping you at least see a possibility for
> confusion in the doc.

Thanks, I've now clarified the documentation on the release branch to
be more specific about the meaning of "default" in this context, and
made sure the same explanation appears in both face-attribute and
face-all-attributes.

> And maybe even a problematic behavior

I see no problems in the behavior, no.  It's just a complex issue, and
it isn't easy to explain it clearly to readers that aren't necessarily
privy to the implementation details.  Hopefully, it's more clear now.

> (what's the point of returning `unspecified' everywhere?).

Only if no default values were defined via set-face-attribute.

And with that, I'm closing this bug report.

bug#51465: [External] : Re: bug#51465: 27.2; `face-all-attributes' doc or behavior (?)

[Drew Adams]

> No, it isn't wrong: the "default attributes for newly created frames"
> are those the face has before applying the definitions in defface.

Hopefully that is what you've added to the doc, to clarify it.

> > I'm hoping you at least see a possibility for
> > confusion in the doc.
> 
> Thanks, I've now clarified the documentation on the release branch to
> be more specific about the meaning of "default" in this context, and
> made sure the same explanation appears in both face-attribute and
> face-all-attributes.

Thank you.  I'll assume it's clearer now.

That said and done, what a user expects as the
"default" behavior (for new frames, for example)
is very likely to differ from this other kind of
"default".

I hope you've come up with some terminology to
distinguish the two, i.e., some way to talk about
(what I expect is) the more immediate/likely user
understanding of "default" for new frames. 

> It's just a complex issue, and it isn't easy to
> explain it clearly to readers that aren't necessarily
> privy to the implementation details.  Hopefully, it's
> more clear now.

Thank you for trying, here and in the doc.

> > (what's the point of returning `unspecified' everywhere?).
> 
> Only if no default values were defined via set-face-attribute.

OK, but what's the point in that case, even if
it's the only case?  Not a rhetorical question.
I expect there is some use/point; but I have no
idea what it might be.

bug#51465: [External] : Re: bug#51465: 27.2; `face-all-attributes' doc or behavior (?)

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "51465-done@debbugs.gnu.org" <51465-done@debbugs.gnu.org>
> Date: Fri, 29 Oct 2021 16:11:22 +0000
> 
> > No, it isn't wrong: the "default attributes for newly created frames"
> > are those the face has before applying the definitions in defface.
> 
> Hopefully that is what you've added to the doc, to clarify it.

Yes.

> That said and done, what a user expects as the
> "default" behavior (for new frames, for example)
> is very likely to differ from this other kind of
> "default".

When the frame is created, you see the faces after application of the
spec in defface, so these defaults are never seen in that case.

> I hope you've come up with some terminology to
> distinguish the two, i.e., some way to talk about
> (what I expect is) the more immediate/likely user
> understanding of "default" for new frames. 

I see no reason to invent new terminology.  I just explained what
those defaults are and why they aren't seen after the frame is
created.

> > > (what's the point of returning `unspecified' everywhere?).
> > 
> > Only if no default values were defined via set-face-attribute.
> 
> OK, but what's the point in that case, even if
> it's the only case?  Not a rhetorical question.
> I expect there is some use/point; but I have no
> idea what it might be.

I don't know either.  This is an old function; perhaps it can be
useful in some rare cases.