bug#59347: 29.0.50; `:family` face setting ignored

[Po Lu via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

Gregory Heytings <gregory@heytings.org> writes:

> They are not supposed to debug a (very subtle) part of the code they
> do not understand.

By that logic, I should just delete the entire "If you encounter X
protocol errors" section from etc/DEBUG.

> That's not possible.  You would understand that if you had read the
> post upthread in which I describe in every detail what that variable
> does and why.  But you don't care, apparently.

Yes, I don't.  The fundamental problem I have with the doc string is
that it did not say what it does, or what it is supposed to debug, in a
manner users can understand.

If someone finds a problem that can be fixed by removing ":medium" from
the list, he will type "C-h a font attributes RET" and come across the
variable, change it, and find out that it is fixed that way.  Then, when
the bug is reported, we will immediately know roughly where the problem
lies, skipping past a whole week of pain and anguish.

A doc string which only talks about realize_gui_face and bits in a
bitmask will at most lead to confusion and an immediate bug report.
That's assuming the variable can be found at all.

Even the following doc string helps more in that situation:

  "This variable controls some aspects of how Emacs understands
   font-related face attributes in face specifications.  Try removing or
   adding new elements to this list should you come across problems with
   Emacs ignoring fonts that do not have certain weights or widths."