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

[Drew Adams]

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

    It seems to me that the real problem is a lack of knowledge about how
    face rendering in general works.

    This should be solved by having a good overview of face rendering in the
    manual (I don't know if there is one or not), not by trying to shove
    that information in every function docstring that's somehow related to
    faces.

Yes, such an explanation in the manual is probably needed - that's what I
was trying to suggest. Whether it should take the form of a new, separate
section or just cleanup of existing text, I don't know. If a new section is
added, the existing text should still be cleaned up so that it makes more
sense (possibly cross-referencing the new section, to help).

I agree, too, that each function's doc string need not try to explain
everything. If the doc defines the terms it uses (e.g. "underlying",
"relative") and explains them clearly, then that lessens the burden of
explanation for doc strings.