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

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

[Stefan Kangas]

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

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@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).

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

[Lars Ingebrigtsen]

Stefan Kangas <stefan@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

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

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Mon, 01 Mar 2021 18:12:59 +0100
> Cc: 46853@debbugs.gnu.org
> 
> Stefan Kangas <stefan@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).

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

[Stefan Kangas]

Lars Ingebrigtsen <larsi@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'?

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

[Lars Ingebrigtsen]

Stefan Kangas <stefan@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

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

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 415 bytes --]

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

[-- Attachment #2: font-size.diff --]
[-- Type: text/x-diff, Size: 9349 bytes --]

diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index 58d08b43c0..6b9b8e84c2 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -809,7 +809,8 @@ Standard Faces
 @node Text Scale
 @section Text Scale
 
-@cindex adjust buffer face height
+@cindex adjust buffer font size
+@cindex font size, increase or decrease
 @findex text-scale-adjust
 @kindex C-x C-+
 @kindex C-x C--
@@ -817,17 +818,16 @@ Text Scale
 @kindex C-x C-0
 @kindex C-wheel-down
 @kindex C-wheel-up
-  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-+}
+or @kbd{C-x C-=}.  To decrease it, type @kbd{C-x C--}.  To restore the
+default (global) font size, 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 and adjusts the
+font size accordingly by changing the height of the default face.
 
   Similarly, scrolling the mouse wheel with the @kbd{Ctrl} modifier
 pressed, when the mouse pointer is above buffer text, will increase or
-decrease the height of the default face, depending on the direction of
-the scrolling.
+decrease the font size, depending on the direction of the scrolling.
 
   The final key of these commands may be repeated without the leading
 @kbd{C-x}.  For instance, @kbd{C-x C-= C-= C-=} increases the face
@@ -837,9 +837,9 @@ Text Scale
 to the @code{text-scale-adjust} command restores the default height,
 the same as typing @kbd{C-x C-0}.
 
-@cindex increase buffer face height
+@cindex increase buffer font size
 @findex text-scale-increase
-@cindex decrease buffer face height
+@cindex decrease buffer font size
 @findex text-scale-decrease
   The commands @code{text-scale-increase} and
 @code{text-scale-decrease} increase or decrease the height of the
@@ -847,7 +847,7 @@ Text Scale
 You may find it convenient to bind to these commands, rather than
 @code{text-scale-adjust}.
 
-@cindex set buffer face height
+@cindex set buffer font size
 @findex text-scale-set
   The command @code{text-scale-set} scales the height of the default
 face in the current buffer to an absolute level specified by its
diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index e1a4e64a7d..63de33498f 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -211,8 +211,8 @@ Mouse Commands
 buffers are scrolled.  The variable
 @code{mouse-wheel-progressive-speed} determines whether the scroll
 speed is linked to how fast you move the wheel.  This mode also
-supports increasing or decreasing the height of the default face, by
-default bound to scrolling with the @key{Ctrl} modifier.
+supports increasing or decreasing the font size, by default bound to
+scrolling with the @key{Ctrl} modifier.
 
 @vindex mouse-wheel-scroll-amount-horizontal
 Emacs also supports horizontal scrolling with the @key{Shift}
diff --git a/lisp/cus-face.el b/lisp/cus-face.el
index 21fe89c621..8de701b8b4 100644
--- 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."
 	     :value 1.0			; default
-	     (integer :tag "Height in 1/10 pt")
+             (integer :tag "Font size in 1/10 pt")
 	     (number :tag "Scale" 1.0)))
 
     (:weight
diff --git a/lisp/face-remap.el b/lisp/face-remap.el
index 5914ee4a20..543b673c37 100644
--- a/lisp/face-remap.el
+++ b/lisp/face-remap.el
@@ -212,7 +212,7 @@ face-remap-set-base
 
 (defcustom text-scale-mode-step 1.2
   "Scale factor used by `text-scale-mode'.
-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."
   :group 'display
   :type 'number
   :version "23.1")
@@ -317,7 +317,7 @@ text-scale-set
 
 ;;;###autoload
 (defun text-scale-increase (inc)
-  "Increase the height of the default face in the current buffer by INC steps.
+  "Increase the font size of the default face in current buffer by INC steps.
 If the new height is other than the default, `text-scale-mode' is enabled.
 
 Each step scales the height of the default face by the variable
@@ -329,14 +329,14 @@ text-scale-increase
          (new-value (if (= inc 0) 0 (+ current-value inc))))
     (if (or (> new-value (text-scale-max-amount))
             (< new-value (text-scale-min-amount)))
-        (user-error "Cannot %s the default face height more than it already is"
+        (user-error "Cannot %s the font size any further"
                     (if (> inc 0) "increase" "decrease")))
     (setq text-scale-mode-amount new-value))
   (text-scale-mode (if (zerop text-scale-mode-amount) -1 1)))
 
 ;;;###autoload
 (defun text-scale-decrease (dec)
-  "Decrease the height of the default face in the current buffer by DEC steps.
+  "Decrease the font size of the default face in the current buffer by DEC steps.
 See `text-scale-increase' for more details."
   (interactive "p")
   (text-scale-increase (- dec)))
@@ -347,19 +347,19 @@ text-scale-decrease
 ;;;###autoload (define-key ctl-x-map [(control ?0)] 'text-scale-adjust)
 ;;;###autoload
 (defun text-scale-adjust (inc)
-  "Adjust the height of the default face by INC.
+  "Adjust font size of the default face in current buffer by INC steps.
 
 INC may be passed as a numeric prefix argument.
 
 The actual adjustment made depends on the final component of the
 key-binding used to invoke the command, with all modifiers removed:
 
-   +, =   Increase the height of the default face by one step
-   -      Decrease the height of the default face by one step
-   0      Reset the height of the default face to the global default
+   +, =   Increase default font size in current buffer by one step
+   -      Decrease default font size in current buffer by one step
+   0      Reset the font size to the global default
 
 After adjusting, continue to read input events and further adjust
-the face height as long as the input event read
+the font size as long as the input event read
 \(with all modifiers removed) is one of the above characters.
 
 Each step scales the height of the default face by the variable
diff --git a/lisp/faces.el b/lisp/faces.el
index 90f11bbe3b..8e882f19ed 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -671,14 +671,14 @@ set-face-attribute
 
 `: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).
 
 `:weight'
 
diff --git a/lisp/mwheel.el b/lisp/mwheel.el
index adfeaccb29..01c223dd5a 100644
--- a/lisp/mwheel.el
+++ b/lisp/mwheel.el
@@ -100,8 +100,9 @@ mouse-wheel-scroll-amount
 the mouse wheel will scroll horizontally instead of vertically.
 
 If AMOUNT is the symbol text-scale, this means that with
-MODIFIER, the mouse wheel will change the face height instead of
-scrolling."
+MODIFIER, the mouse wheel will change the font size instead of
+scrolling (by adjusting the font height of the default face).
+For more information, see `text-scale-adjust'."
   :group 'mouse
   :type '(cons
 	  (choice :tag "Normal"
@@ -364,7 +365,8 @@ mwheel-scroll
 (put 'mwheel-scroll 'scroll-command t)
 
 (defun mouse-wheel-text-scale (event)
-  "Increase or decrease the height of the default face according to the EVENT."
+  "Adjust font size of the default face according to EVENT.
+See also `text-scale-adjust'."
   (interactive (list last-input-event))
   (let ((selected-window (selected-window))
         (scroll-window (mouse-wheel--get-scroll-window event))
diff --git a/lisp/play/gamegrid.el b/lisp/play/gamegrid.el
index 8b64dfdf9b..f58b3936e6 100644
--- 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.
     (when (eq gamegrid-display-mode 'glyph)
       (overlay-put (make-overlay (point-min) (point-max))
 		   'face gamegrid-face))

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

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@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

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Mon, 1 Mar 2021 13:15:57 -0600
> Cc: 46853@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.

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

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Mon, 01 Mar 2021 20:25:18 +0100
> Cc: 46853@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.

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

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@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

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

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@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

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Mon, 1 Mar 2021 13:31:44 -0600
> Cc: 46853@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.

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

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Mon, 01 Mar 2021 20:33:00 +0100
> Cc: 46853@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?

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

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Mon, 01 Mar 2021 20:37:07 +0100
> Cc: 46853@debbugs.gnu.org
> 
> Lars Ingebrigtsen <larsi@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.

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

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: stefan@marxist.se,  46853@debbugs.gnu.org
> Date: Mon, 01 Mar 2021 20:45:28 +0100
> 
> Eli Zaretskii <eliz@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'.

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

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@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

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

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: stefan@marxist.se,  46853@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).

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.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Lars Ingebrigtsen <larsi@gnus.org>
>> Cc: stefan@marxist.se,  46853@debbugs.gnu.org
>> Date: Mon, 01 Mar 2021 20:45:28 +0100
>>
>> Eli Zaretskii <eliz@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)?

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

[Eli Zaretskii]

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

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

[Eli Zaretskii]

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

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

[Stefan Kangas]

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

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

[Stefan Kangas]

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

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

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@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