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

[Drew Adams]

        `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)

    Drew, do you think something in the documentation is not clear enough
    about this?  If you identify a place that is not clear, I can
    improve it.

Well, I mentioned a few things in my July emails that were not clear to me
in the doc. I'll repeat some of them here.

face-spec-reset: "Reset all attributes of FACE on FRAME to unspecified."

This says nothing about FRAME, suggesting that it is just a frame. FRAME is
optional, but the doc doesn't say anything about what happens if FRAME is
omitted (nil). Is the selected frame used? All frames?

In fact, the value FRAME is just passed to set-face-attribute.  The doc for
that function says that if FRAME is either nil or t, it changes the face
attributes on all future frames (nil also changes the face attributes on all
existing frames). This means that using nil or t for face-spec-reset would
do the same, but that is not documented.

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.

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. Or is that just true for :inherit? It's not clear to me. Anyway,
it's not documented in set-face-attribute or face-spec-reset.

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?

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.

5. So, FRAME for face-spec-reset: if nil (default), translates to 0 for
internal-set*: change attribute for all frames and the default value for new
frames; if t, translates to t for internal-set*: change default value for
new frames. None of that is documented for face-spec-reset.

6. What is the point (use case) of face-spec-reset? Given the name and the
doc string, it would seem to be to reset all attributes for the face to
`unspecified' - tabla rasa. Given the name "unspecified", that would seem to
wipe out any defined values. Given the default treatment of FRAME (nil) and
the treatment of a t value for FRAME, the wiping out with these FRAME values
would seem to be for new frames (nil and t) and possibly all existing frames
(nil).

7. This seems partly to be the case, except for:

 - `unspecified' has apparently no effect on future frames; that must be
done using a value of nil, which face-spec-reset does not do.

 - It's not clear to me, but maybe this is true for `unspecified' only for
attribute :inherit? That seems to be what Eli was saying, from his tests of
other attributes.

 - If the various doc strings imply that future frames should be affected,
but they are not, is that not a bug of some kind? Even if this is true only
for :inherit, shouldn't that be mentioned as an exception, contradicting the
general treatment of nil and t that affects future frames?

I'm sure I don't understand this correctly, but it's not for want of trying
to understand. It looks to me like there is a difference between what the
doc says and what happens - at least in the case of :inherit.

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

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.

And I do see `unspecified' being mentioned as if it would play the role that
nil apparently plays wrt default (future) behavior. At least that is what
the name suggests to me.

Bottom line, for me: I started with face-spec-reset-face, thinking it would
help me get rid of the default behavior for completions-first-difference and
completions-common-part - on all existing frames and all new frames. I guess
what I've learned I need to do (but I'm not sure) is this:

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

Actually, I would like to get rid of the use of these two faces altogether,
for my own use. IIUC, they are used at the C level, so I cannot get rid of
their use (and still use completion); the most I can do is get rid of their
Boldness, trying to make them seem like normal text.

Anyway, I realize this might not sound too coherent, but I don't have time
now to make it make more sense. Hope it's helpful in some way.

 - Drew