RE: problems with face-spec-reset-face and set-face-attribute

[Drew Adams]

        1. The statement about the behavior of nil and t for
           set-face-attribute is apparently not true for attribute
           :inherit, but it is true for the other
           attributes. The doc for set-face-attribute specifically
           mentions support for :inherit, without saying anything
           special about it.

    It is supposed to be true for all attributes.
    Why do you say this is not true for :inherit?

I could be mistaken, but that's what I understood from the investigation by
Eli:

    <Eli> This seems to be a bug in internal-set-lisp-face-attribute that is
    specific to the :inherit attribute.  When I try your recipe with other
    attributes, like :foreground or :slant, everything works as expected.
    (A good face to try this is `fringe': when it changes, you see the
    effect immediately.)

    Perhaps there is a bug.

I think so, but I admit that I don't understand this well.

        2. Apparently, the set-face-attribute behavior also depends
           on what value the attribute is set to: setting it to
           (pseudo-)value nil changes (resets)
           its default value for future frames; setting it to another
           value apparently does not.

    If this is true, it is a bug.  It is supposed to affect future frames
    when FRAME is nil or t.  Otherwise it should never do so.

Yes, that's my understanding too.

        3. The value `unspecified' is not very clear to me, but I
           don't have time now to look up where it is documented.
           A default value of `unspecified', by its _name_, would
           seem like it should have the behavior that apparently only
           nil gives. Or is that just for :inherit?

    This is documented in the Lisp manual.  Is that documentation clear?
    If not, could you point out what in the Lisp manual is unclear?

The Face Attributes node is clear about `unspecified'. I haven't yet found
the place where nil is documented wrt the default value (e.g. set to nil to
reset default value for new frames), but that doesn't mean it's not
mentioned clearly somewhere in the manual.

    If you find a case whose behavior does not match the manual,
    could you please report that as a bug?

Will do. Nothing so far, except the above :inherit bug or doc bug wrt
face-spec-reset-face,  set-face-attribute, and
internal-set-lisp-face-attribute.

        4. set-face-attribute is implemented with
           internal-set-lisp-face-attributes.
           That internal function has the clearest doc string of the three!
           Its treatment of nil and t is different (and somewhat backward)
           from their treatment by set-face-attribute: nil means change the
           attribute for the selected frame; t means change its default
           value, for new frames; 0 means change its value on all existing
           frames and its default value for new frames. nil for
           set-face-attribute translates to 0 for internal-set*; t
           remains t; a real frame is passed along.

    It is somewhat unclean that internal-set-lisp-face-attributes
    does not follow the same convention as set-face-attribute,
    but since internal-set-lisp-face-attributes is not meant for users,
    it is not a real problem.

I understand that. I have no problem with the arguments having different
behavior/meaning. #4 was only background for #5, which said that the FRAME
parameter is not documented for face-spec-reset-face.

Since it is not documented for face-spec-reset-face, you have to read the
face-spec-reset-face code, which leads you (after two indirections) to the
internal-set-lisp-face-attributes code and doc string. It is having to go
through these three doc strings, with different meanings for FRAME, that is
confusing.

If FRAME were simply (and correctly) documented for face-spec-reset-face,
there would be no problem - there is no real problem with the other two doc
strings (although, as I mentioned in July, the doc string for
set-face-attribute could be cleaned up and simplified.

        6. What is the point (use case) of face-spec-reset?

    I don't see any face-spec-reset in frame.el.
    Do you mean face-spec-reset-face?

Yes, sorry.

    It is meant for use by face-spec-set.

Yes, but it looks like it could also be of use anywhere one wants to reset a
face spec to `unspecified'. That's why I started with it.

        And I don't see :inherit mentioned anywhere as an exception.

    That's because it isn't one.

Are you sure? See Eli's email and the earlier thread. It's not clear to me.

        And I don't see nil mentioned in its special role for
        default (future) values, although that might be done somewhere
        else in the doc.

    That's because it does not have such a role.

Then I'm confused. As Juri said (and it works):

    `unspecified' does just what it says, i.e. leaves the default frame
    value untouched.  If you want to change the default for new frames,
    you can set the value of this attribute to nil.  So this should work
    just fine:

        (set-face-attribute 'completions-first-difference nil :inherit nil)

I interpret this to mean that setting a face attribute to nil will "change
the default for new frames", as Juri said. The same is not true for setting
it to "Bold" or "unspecified", IIUC.

Again, I'm not arguing that what I think I understand is correct. I admit
that this is largely unclear to me. I'm hoping that 1) I'll finish by
understanding it and, as a result, 2) the doc can be made clearer (and the
bugs fixed, if any).  HTH.