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

[Stefan Kangas <stefan@marxist.se>]

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