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

[Eli Zaretskii <eliz@gnu.org>]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Wed, 3 Mar 2021 16:43:07 -0600
> Cc: 46853@debbugs.gnu.org
> 
> > 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.

As this discussion shows, it definitely doesn't scale _all_ of them.

> 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].

There's no such thing as "the font in the current buffer" in modern
Emacs, because we are capable of using quite a few fonts in the same
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.

I didn't object to mentioning the font, I object to mentioning it
without _also_ mentioning the face(s) whose font attribute is
affected.

> 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.

The "absolute" part is inaccurate, see the other mail in this thread.

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

Which doc string are you alluding to here?  There's IMO a difference
between doc strings of user commands and doc strings of the rest of
the functions and variables.  The latter don't need to cater too much
to users, so they can be more rigorous.  Doc strings for user commands
and options should perhaps start with an easier to understand text,
but should afterwards have notes that prevent erroneous
interpretation.

IOW, we need to consider the doc strings on a case by case basis.