GNU bug report logs - #46853
Confusing terminology "face height" instead of "font size"

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 46853 in the body.
You can then email your comments to 46853 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: bug-gnu-emacs <at> gnu.org
Subject: Confusing terminology "face height" instead of "font size"
Date: Mon, 1 Mar 2021 10:40:07 -0600

Severity: wishlist

I suggest changing the terminology "face height" to "font size" in user
documentation and messages.  For example, the documentation for
`text-scale-adjust' currently says:

   "Adjust the height of the default face by INC."

This is harder than it needs to be to understand, since the rest of the
world actually talks about "increase font size".  IOW, it would be more
clear if it said:

   "Adjust the font size in the current buffer by INC steps."

[This would also move talking about the `default' face further down, as
that is more of an implementation detail mostly of interest when
programming ELisp.]

Behind the scenes obviously a "face" is different from a "font" (as it
is rather a set of features that includes the font, formatting, etc.).
We should absolutely maintain that terminology.  We should also maintain
that if you want to customize the look of Emacs, including font size,
you need to customize this thing we call "faces".

As part of this, we could also consider introducing a new property for
`defface' called :size.  (Or :font-size and :font-scale which would
allow for semantics where we can specify :font-size 14 and mean 14pt
rather than 1.4pt.)

Message #8 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 46853 <at> debbugs.gnu.org
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Mon, 01 Mar 2021 19:06:14 +0200

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Mon, 1 Mar 2021 10:40:07 -0600
> 
> I suggest changing the terminology "face height" to "font size" in user
> documentation and messages.  For example, the documentation for
> `text-scale-adjust' currently says:
> 
>    "Adjust the height of the default face by INC."
> 
> This is harder than it needs to be to understand, since the rest of the
> world actually talks about "increase font size".  IOW, it would be more
> clear if it said:
> 
>    "Adjust the font size in the current buffer by INC steps."

It's okay to make that change in this example, but one example is not
enough to understand what else is on the table.  How about showing a
patch, or at least the full list of places where you think we have
similar problems?  This should IMO be handled on a case by case basis
anyway.

> As part of this, we could also consider introducing a new property for
> `defface' called :size.  (Or :font-size and :font-scale which would
> allow for semantics where we can specify :font-size 14 and mean 14pt
> rather than 1.4pt.)

I wouldn't go that far; using :height is well established in Emacs
(and elsewhere, I believe: the face attributes were defined with XLFD
in mind).

Message #11 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 46853 <at> debbugs.gnu.org
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Mon, 01 Mar 2021 18:12:59 +0100

Stefan Kangas <stefan <at> marxist.se> writes:

> This is harder than it needs to be to understand, since the rest of the
> world actually talks about "increase font size".  IOW, it would be more
> clear if it said:
>
>    "Adjust the font size in the current buffer by INC steps."

But...  is that correct?  I thought the command only adjusted the size
of the font of the default face (*phew*)...  let's see....  Yup.  I
tried using it in a eww buffer (which uses variable-pitch and not
default) and the `C-x C-+' didn't change the font size.  (It made the
lines taller, though...  Oh, right, some of the spaces use `default'.)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #14 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 46853 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Mon, 01 Mar 2021 19:17:51 +0200

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Date: Mon, 01 Mar 2021 18:12:59 +0100
> Cc: 46853 <at> debbugs.gnu.org
> 
> Stefan Kangas <stefan <at> marxist.se> writes:
> 
> >    "Adjust the font size in the current buffer by INC steps."
> 
> But...  is that correct?  I thought the command only adjusted the size
> of the font of the default face (*phew*)...

Yes.  So:

  Adjust size of the default face's font in current buffer by INC steps.

(with some "the" omitted for brevity).

Message #17 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 46853 <at> debbugs.gnu.org
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Mon, 1 Mar 2021 13:15:57 -0600

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> But...  is that correct?  I thought the command only adjusted the size
> of the font of the default face (*phew*)...  let's see....  Yup.  I
> tried using it in a eww buffer (which uses variable-pitch and not
> default) and the `C-x C-+' didn't change the font size.  (It made the
> lines taller, though...  Oh, right, some of the spaces use `default'.)

Hmm, I'm not seeing the same here in emacs -Q.

But I'd argue that it's a bug -- why shouldn't `C-x C-+' adjust
the size of `variable-pitch'?

Message #20 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 46853 <at> debbugs.gnu.org
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Mon, 01 Mar 2021 20:25:18 +0100

Stefan Kangas <stefan <at> marxist.se> writes:

> Hmm, I'm not seeing the same here in emacs -Q.

Does it really make the faces bigger...  or just add more vertical blank
space?  It just calls:

  (when text-scale-mode
    (face-remap--remap-face 'default)
    (when text-scale-remap-header-line
      (face-remap--remap-face 'header-line)))

So, OK, it's not just the `default' face, but also `header-line'
optionally.  :-)

> But I'd argue that it's a bug -- why shouldn't `C-x C-+' adjust
> the size of `variable-pitch'?

I don't know the history of the command...  could it be because
remapping all faces would just be too slow?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #23 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 46853 <at> debbugs.gnu.org
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Mon, 1 Mar 2021 13:31:44 -0600

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

> It's okay to make that change in this example, but one example is not
> enough to understand what else is on the table.  How about showing a
> patch, or at least the full list of places where you think we have
> similar problems?  This should IMO be handled on a case by case basis
> anyway.

Agreed, so here's a tentative diff.  It could probably use some
polishing though.

[font-size.diff (text/x-diff, attachment)]

Message #26 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 46853 <at> debbugs.gnu.org
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Mon, 01 Mar 2021 20:33:00 +0100

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> So, OK, it's not just the `default' face, but also `header-line'
> optionally.  :-)

Playing with this a bit more, I'm getting a bit confused here...
`C-x C-+' does indeed change the size of all the faces -- I had

(set-face-attribute 'variable-pitch nil :height 120)

in my .emacs.

So you're totally right; sorry for the confusion here.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #29 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 46853 <at> debbugs.gnu.org, larsi <at> gnus.org
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Mon, 01 Mar 2021 21:33:39 +0200

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Mon, 1 Mar 2021 13:15:57 -0600
> Cc: 46853 <at> debbugs.gnu.org
> 
> But I'd argue that it's a bug -- why shouldn't `C-x C-+' adjust
> the size of `variable-pitch'?

Because the command only changes the size of the 'default' face and
all the faces that inherit from it.

Message #32 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 46853 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Mon, 01 Mar 2021 21:35:25 +0200

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Date: Mon, 01 Mar 2021 20:25:18 +0100
> Cc: 46853 <at> debbugs.gnu.org
> 
>   (when text-scale-mode
>     (face-remap--remap-face 'default)
>     (when text-scale-remap-header-line
>       (face-remap--remap-face 'header-line)))
> 
> So, OK, it's not just the `default' face, but also `header-line'
> optionally.  :-)

You can remap other faces by hand, but that's not the original
question.

> > But I'd argue that it's a bug -- why shouldn't `C-x C-+' adjust
> > the size of `variable-pitch'?
> 
> I don't know the history of the command...  could it be because
> remapping all faces would just be too slow?

No, it's because enlarging _all_ faces makes no sense.

Message #35 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 46853 <at> debbugs.gnu.org
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Mon, 01 Mar 2021 20:37:07 +0100

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> So you're totally right; sorry for the confusion here.

So now I don't understand the point of this:

    (when text-scale-remap-header-line
      (face-remap--remap-face 'header-line)))

The variable is nil in emacs -Q, but this face, like all other faces, is
resized by `C-x C-+'.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #38 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 46853 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Mon, 01 Mar 2021 20:45:28 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

> No, it's because enlarging _all_ faces makes no sense.

I really thought that's how this command worked, but

emacs -Q -f list-faces-display

and then `C-x C-+' in the buffer enlarges all the faces, even
variable-pitch...

Is this something that varies by system Emacs is running on?  

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #41 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 46853 <at> debbugs.gnu.org
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Mon, 01 Mar 2021 21:46:18 +0200

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Mon, 1 Mar 2021 13:31:44 -0600
> Cc: 46853 <at> debbugs.gnu.org
> 
> Agreed, so here's a tentative diff.  It could probably use some
> polishing though.

Thanks.

First, this consistently removes the reference to the default face,
which loses information.  For example:

> -  To increase the height of the default face in the current buffer,
> -type @kbd{C-x C-+} or @kbd{C-x C-=}.  To decrease it, type @kbd{C-x
> -C--}.  To restore the default (global) face height, type @kbd{C-x
> -C-0}.  These keys are all bound to the same command,
> -@code{text-scale-adjust}, which looks at the last key typed to
> -determine which action to take.
> +  To increase the font size in the current buffer, type @kbd{C-x C-+}

This should be

  To increase the height of the default face's font, type ...

Please also retain the reference to the default face in all the other
places where it was mentioned before.

> --- a/lisp/cus-face.el
> +++ b/lisp/cus-face.el
> @@ -73,9 +73,9 @@ custom-face-attributes
>  
>      (:height
>       (choice :tag "Height"
> -	     :help-echo "Face's font height."
> +             :help-echo "Font size."

Here' I suggest "Face's font size."  There's no need to remove the
reference to the face, since in Emacs a font is just one attribute of
the face.

> -Each positive or negative step scales the default face height by this amount."
> +Each positive or negative step scales the default font size by this amount."

There's no such thing as "the default font", please use "the size of
the default face's font" instead.

> -        (user-error "Cannot %s the default face height more than it already is"
> +        (user-error "Cannot %s the font size any further"

Please keep the reference to the default face here.

> +   +, =   Increase default font size in current buffer by one step
> +   -      Decrease default font size in current buffer by one step

"Default font" again.

>  `:height'
>  
> -VALUE specifies the relative or absolute height of the font.  An
> -absolute height is an integer, and specifies font height in units
> -of 1/10 pt.  A relative height is either a floating point number,
> -which specifies a scaling factor for the underlying face height;
> -or a function that takes a single argument (the underlying face
> -height) and returns the new height.  Note that for the `default'
> -face, you must specify an absolute height (since there is nothing
> -for it to be relative to).
> +VALUE specifies the relative or absolute font size (height of the
> +font).  An absolute height is an integer, and specifies font height in
> +units of 1/10 pt.  A relative height is either a floating point
> +number, which specifies a scaling factor for the underlying face
> +height; or a function that takes a single argument (the underlying
> +face height) and returns the new height.  Note that for the `default'
> +face, you must specify an absolute height (since there is nothing for
> +it to be relative to).

I don't understand the point of this change.  My suggestion would be
to leave the original text intact, and add to it a note saying that
this affects the size of the font, not just its height.

> --- a/lisp/play/gamegrid.el
> +++ b/lisp/play/gamegrid.el
> @@ -452,6 +452,7 @@ gamegrid-init-buffer
>      ;; Adjust the height of the default face to the height of the
>      ;; images. Unlike XEmacs, Emacs doesn't allow making the default
>      ;; face buffer-local; so we do this with an overlay.
> +    ;; FIXME: Is the above correct?  See face-remap.el.

No, this was written before we had face-remap.el.  But that doesn't
belong to this issue.

Message #44 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 46853 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Mon, 01 Mar 2021 21:48:46 +0200

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Date: Mon, 01 Mar 2021 20:33:00 +0100
> Cc: 46853 <at> debbugs.gnu.org
> 
> Playing with this a bit more, I'm getting a bit confused here...
> `C-x C-+' does indeed change the size of all the faces -- I had
> 
> (set-face-attribute 'variable-pitch nil :height 120)
> 
> in my .emacs.

Which exactly demonstrates that not all the faces will have their size
changed.  Right?

Message #47 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 46853 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Mon, 01 Mar 2021 21:50:26 +0200

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Date: Mon, 01 Mar 2021 20:37:07 +0100
> Cc: 46853 <at> debbugs.gnu.org
> 
> Lars Ingebrigtsen <larsi <at> gnus.org> writes:
> 
> > So you're totally right; sorry for the confusion here.
> 
> So now I don't understand the point of this:
> 
>     (when text-scale-remap-header-line
>       (face-remap--remap-face 'header-line)))
> 
> The variable is nil in emacs -Q, but this face, like all other faces, is
> resized by `C-x C-+'.

Not if the face is customized to define its own size, instead of
inheriting from the default face.

Message #50 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 46853 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Mon, 01 Mar 2021 21:59:41 +0200

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Cc: stefan <at> marxist.se,  46853 <at> debbugs.gnu.org
> Date: Mon, 01 Mar 2021 20:45:28 +0100
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> > No, it's because enlarging _all_ faces makes no sense.
> 
> I really thought that's how this command worked, but
> 
> emacs -Q -f list-faces-display
> 
> and then `C-x C-+' in the buffer enlarges all the faces, even
> variable-pitch...

It only enlarges those faces which inherit their size from 'default'.

Message #53 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 46853 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Mon, 01 Mar 2021 21:05:11 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

>> (set-face-attribute 'variable-pitch nil :height 120)
>> 
>> in my .emacs.
>
> Which exactly demonstrates that not all the faces will have their size
> changed.  Right?

Sure.  But the rules are a bit more subtle, so I wonder whether talking
about the "default face" everywhere is the best way of doing it.

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.

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? 

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #56 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 46853 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Mon, 01 Mar 2021 22:17:09 +0200

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Cc: stefan <at> marxist.se,  46853 <at> debbugs.gnu.org
> Date: Mon, 01 Mar 2021 21:05:11 +0100
> 
> > Which exactly demonstrates that not all the faces will have their size
> > changed.  Right?
> 
> Sure.  But the rules are a bit more subtle, so I wonder whether talking
> about the "default face" everywhere is the best way of doing it.
> 
> 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.
> 
> 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.  (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).

Message #59 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>, Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 46853 <at> debbugs.gnu.org
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Wed, 3 Mar 2021 16:43:07 -0600

Eli Zaretskii <eliz <at> 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.

Message #62 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>, Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 46853 <at> debbugs.gnu.org
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Wed, 3 Mar 2021 18:16:02 -0600

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Lars Ingebrigtsen <larsi <at> gnus.org>
>> Cc: stefan <at> marxist.se,  46853 <at> debbugs.gnu.org
>> Date: Mon, 01 Mar 2021 20:45:28 +0100
>>
>> Eli Zaretskii <eliz <at> gnu.org> writes:
>>
>> > No, it's because enlarging _all_ faces makes no sense.
>>
>> I really thought that's how this command worked, but
>>
>> emacs -Q -f list-faces-display
>>
>> and then `C-x C-+' in the buffer enlarges all the faces, even
>> variable-pitch...
>
> It only enlarges those faces which inherit their size from 'default'.

I find the semantics here confusing.  I do this in emacs -Q:

    (progn
      (defface foo-bar '((t :weight bold)) "foo")
      (pop-to-buffer (get-buffer-create "foo"))
      (insert "aaa " (propertize "bbb" 'face 'foo-bar) " ccc")
      (text-scale-adjust 3))

And I see that "bbb" has its font size increased together with "aaa" and
"ccc".  But `M-x describe-face RET foo-bar' says that "Inherit:
unspecified".

Looking at the manual, the node `(elisp) Basic Faces' says:

    ‘default’
         The default face, whose attributes are all specified.  All other
         faces implicitly inherit from it: any unspecified attribute
         defaults to the attribute on this face (*note Face Attributes::).

So when you say that "it only enlarges those faces which inherit their
size from 'default'", doesn't that just mean that *any* face is resized,
unless that face itself or any its parents specify an absolute :height
(an integer)?

Message #65 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 46853 <at> debbugs.gnu.org, larsi <at> gnus.org
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Thu, 04 Mar 2021 15:41:34 +0200

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

Message #68 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 46853 <at> debbugs.gnu.org, larsi <at> gnus.org
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Thu, 04 Mar 2021 15:46:08 +0200

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Wed, 3 Mar 2021 18:16:02 -0600
> Cc: 46853 <at> debbugs.gnu.org
> 
> >> and then `C-x C-+' in the buffer enlarges all the faces, even
> >> variable-pitch...
> >
> > It only enlarges those faces which inherit their size from 'default'.
> 
> I find the semantics here confusing.  I do this in emacs -Q:
> 
>     (progn
>       (defface foo-bar '((t :weight bold)) "foo")
>       (pop-to-buffer (get-buffer-create "foo"))
>       (insert "aaa " (propertize "bbb" 'face 'foo-bar) " ccc")
>       (text-scale-adjust 3))
> 
> And I see that "bbb" has its font size increased together with "aaa" and
> "ccc".  But `M-x describe-face RET foo-bar' says that "Inherit:
> unspecified".

All the faces implicitly inherit from 'default'.

> Looking at the manual, the node `(elisp) Basic Faces' says:
> 
>     ‘default’
>          The default face, whose attributes are all specified.  All other
>          faces implicitly inherit from it: any unspecified attribute
>          defaults to the attribute on this face (*note Face Attributes::).

Exactly.

> So when you say that "it only enlarges those faces which inherit their
> size from 'default'", doesn't that just mean that *any* face is resized,
> unless that face itself or any its parents specify an absolute :height
> (an integer)?

No, it doesn't have to be an absolute :height attribute.  It can also
be:

  . a face that inherits from a face other than 'default', which has
    an absolute :height attribute
  . a face that specifies a relative :height attribute and inherits
    from a face other than 'default that specifies an absolute :height
  . any other situation where a face recursively inherits from some
    other face with a non-default absolute :height

Message #71 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 46853 <at> debbugs.gnu.org, larsi <at> gnus.org
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Thu, 4 Mar 2021 09:35:04 -0800

Eli Zaretskii <eliz <at> gnu.org> writes:

>> So when you say that "it only enlarges those faces which inherit their
>> size from 'default'", doesn't that just mean that *any* face is resized,
>> unless that face itself or any its parents specify an absolute :height
>> (an integer)?
>
> No, it doesn't have to be an absolute :height attribute.  It can also
> be:
>
>   . a face that inherits from a face other than 'default', which has
>     an absolute :height attribute
>   . a face that specifies a relative :height attribute and inherits
>     from a face other than 'default that specifies an absolute :height
>   . any other situation where a face recursively inherits from some
>     other face with a non-default absolute :height

AFAICT, we are saying the same thing.  So we agree here.

Message #74 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 46853 <at> debbugs.gnu.org, larsi <at> gnus.org
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Thu, 4 Mar 2021 10:05:28 -0800

Eli Zaretskii <eliz <at> gnu.org> writes:

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

(Right, but I didn't write "the font in the current buffer".  ;-))

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

Perhaps we are in violent agreement, because I agree completely.

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

I'll rework the patch (more carefully this time) so we have a better
basis for such a discussion.

Message #77 received at 46853 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 46853 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#46853: Confusing terminology "face height" instead of "font
 size"
Date: Mon, 20 Jun 2022 01:27:54 +0200

Lars Ingebrigtsen <larsi <at> gnus.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.
>
> 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?

I've now applied Stefan's patch to Emacs 29, adjusting for most of Eli's
comments -- but not the ones about mentioning the default face as much.
Instead I've explicitly explained the above in both the manual and the
doc string, which should make things less confusing, I think.

Feel free to adjust further, of course.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.