RE: doc string for face-attribute-relative-p doesn't help

["Drew Adams" <drew.adams@oracle.com>]

    >>       Return non-nil if face ATTRIBUTE VALUE is relative.
    >>
    >>     What does that mean? How is ATTRIBUTE VALUE a face? This is
    >>     incomprehensible to me.
    >
    > It returns non-nil if the face attribute ATTRIBUTE is relative
    > when it has value VALUE.  "Relative" means that the value doesn't
    > _override_ that attribute of an underlying face during face merging,
    > but rather _modifies_ it.
    >
    > For most attributes the only value with that property is
    > `unspecified'; some attributes have other relative values (for
    > instance, with :height, floating-point numbers are relative, as
    > they specify a scale value rather than an absolute size).

    Fine text for a footnote.

I don't think so. It isn't clear to me, even after reading it a couple of
times.

For one thing, "underlying" face is unclear to me. It is used throughout the
face doc, but I find no explanation of what is meant, even in the section on
merging. What are the faces "underlying" a face? How are they determined?
What does it mean for them to "underly" the face - what is the effect of
"underlying"? "Underlying" is apparently not the same thing as "inherited
by". There is no way to understand this without knowing what "underlying"
means.

For another thing, I suspect that "relative" is not the right word here, but
it is the one that is used everywhere in the doc for this. What is relative
to what? There also seems to be confusion in Miles's text about whether it
is the attribute or the value that is "relative" - both are suggested.

There seem to be three things to distinguish: 1) the face, 2) its underlying
faces (=?), and 3) the appearance of the face (combined with its underlying
faces, presumably).

I suspect that this is about direct vs indirect application of an attribute
value to the attribute's face. When "relative", the value affects the face's
appearance only indirectly, by being applied not to the face itself but to
one (or more?) of its underlying faces.

Here is another attempt at wording, assuming I understand some of what this
is about.

  ATTRIBUTE with VALUE affects face indirectly, via an underlying face.

  Returns non-nil if, when ATTRIBUTE's face has an underlying face and
  ATTRIBUTE has value VALUE, the appearance of ATTRIBUTE's face is
  determined by applying VALUE to the underlying face. For example, a
  floating-point value for a :height face attribute is applied as a
  scale factor to the height of an underlying face. Returns non-nil
  for any ATTRIBUTE if VALUE is `unspecified'.

  Returns nil if the face has no underlying face.  Returns nil if VALUE
  is applied directly to the face itself to determine its appearance.
  For example, face attribute :foreground is not relative for any VALUE.

`unspecified' seems to be a special case, to me (so it needs to be
mentioned). It is not really applied in any way to the underlying face to
determine the appearance - it is simply ignored, no?

It's not clear to me whether:

 - a face always has an underlying face (e.g. `default')
 - a face can have more than one underlying face, and, if it does,
   which of them (one? several? how decided?) is the target of VALUE.

I think the answers are yes (so, remove the sentence about "no underlying
face") and yes (so, clarify which VALUE applies to). This should be
clarified in the doc.

I don't claim to understand this, so the text above is no doubt incorrect.
Maybe it will help someone come up with accurate text, by pointing out some
of the communication difficulties.

The Elisp manual needs to clarify what "underlying" means, as well as
"relative" (which I suspect is a misnomer for something involving
indirection).

HTH.