bug#46853: Confusing terminology "face height" instead of "font size"

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> My understanding of what it does is:
>>
>> 1) The default face is definitely adjusted (even if it has an explicit
>>    :height).
>>
>> 2) The header face is also adjusted (even if it has an explicit :height)
>>    and you have that variable set.
>>
>> 3) All other fonts will also be adjusted, except those with an explicit
>>    :height.

Thank you for laying this out clearly.

>> There may be other rules, too (are there other face attributes that
>> hinder size changes?), but this seems to indicate to me that we should
>> just say (as in Stefan's patches) "changes the size of the fonts", and
>> then link to a manual node that explains the three points above?
>>
>> Does that sound reasonable?
>
> Sorry, no, because that would mislead by catering to the "usual" cases
> and ignoring the rest.  What I think we should do instead is talk
> about the default face, and then add a note that other faces will be
> affected if they don't specify :height.

Yes, this would be an improvement.  But I have found it less than
helpful with this talk about the `default' face, since it evidently
scales *all* faces.

It also maintains the terminological confusion that is the reason for
this bug report -- i.e. it talks about "the default face" instead of
"the font size" [in the current buffer].

So I would propose:

a) Talking about "changing font size".  That is after all the most
   striking user visible effect, and it is what normally happens in most
   buffers.

b) On row two of the docstring (or three or whatever) we explain the
   exact details, something like:

  "This scales all faces that do not have an absolute :height specified.
  As an exception, the `default' face is scaled even if it has an
  absolute :height.  This exception also applies to the `header-line'
  face if the variable `text-scale-remap-header-line' is non-nil."

This seems both more accurate, and less confusing to me.

I think the difference between the two proposals is that this puts the
technical "implementation details" further down, and the user-visible
effects higher up.  (I put "implementation details" in quotes because it
becomes important as soon as you start customizing faces with absolute
values.)

> (The special handling of header-line doesn't have to be mentioned
> where header-line is not the most relevant feature; or we could say
> "see also `text-scale-remap-header-line' in some of them).

Agreed.  We should decide the level of detail on a case-by-case basis.