master 9bf520593c: Update font scaling documentation to not talk about "face height"

[Lars Ingebrigtsen]

branch: master
commit 9bf520593c81735398c3a8369df9854586218913
Author: Stefan Kangas <stefan@marxist.se>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    Update font scaling documentation to not talk about "face height"
    
    * lisp/play/gamegrid.el (gamegrid-init-buffer):
    * lisp/mwheel.el (mouse-wheel-scroll-amount):
    (mouse-wheel-text-scale):
    * lisp/faces.el (set-face-attribute):
    * lisp/face-remap.el (text-scale-mode-step):
    (text-scale-increase):
    (text-scale-adjust):
    * lisp/cus-face.el (custom-face-attributes):
    * doc/emacs/frames.texi (Mouse Commands):
    * doc/emacs/display.texi (Text Scale): Talk about font sized instead
    of "face height" (bug#46853).
---
 doc/emacs/display.texi | 42 +++++++++++++++++++++++-------------------
 doc/emacs/frames.texi  |  4 ++--
 lisp/cus-face.el       |  4 ++--
 lisp/face-remap.el     | 27 ++++++++++++++++-----------
 lisp/faces.el          | 16 ++++++++--------
 lisp/mwheel.el         |  8 +++++---
 lisp/play/gamegrid.el  |  1 +
 7 files changed, 57 insertions(+), 45 deletions(-)

diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index 16d6d5567e..e065155845 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -854,7 +854,8 @@ would be selected if you click a mouse or press @key{RET}.
 @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--
@@ -862,17 +863,21 @@ would be selected if you click a mouse or press @key{RET}.
 @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.
+
+  Most faces are affected by these font size changes, but not faces
+that have an explicit @code{:height} setting.  The two exceptions to
+this are the @code{default} and @code{header} faces: They will both be
+scaled even if they have an explicit @code{:height} setting.
 
   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
@@ -882,21 +887,20 @@ of 1.2; to change this factor, customize the variable
 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
-default face, just like @kbd{C-x C-+} and @kbd{C-x C--} respectively.
-You may find it convenient to bind to these commands, rather than
-@code{text-scale-adjust}.
+@code{text-scale-decrease} increase or decrease the size of the font
+in the current buffer, just like @kbd{C-x C-+} and @kbd{C-x C--}
+respectively.  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
-prefix argument.
+  The command @code{text-scale-set} scales the size of the font in the
+current buffer to an absolute level specified by its prefix argument.
 
 @findex text-scale-mode
   The above commands automatically enable the minor mode
diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index fa248c1a58..d90a6ac672 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -223,8 +223,8 @@ mouse-wheel-mode}.  The variables 
@code{mouse-wheel-follow-mouse} and
 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 80d0aaa0d5..73a33f064c 100644
--- a/lisp/cus-face.el
+++ b/lisp/cus-face.el
@@ -83,9 +83,9 @@
 
     (:height
      (choice :tag "Height"
-            :help-echo "Face's font height."
+             :help-echo "Face's 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 50306a5e8a..75d7333f8a 100644
--- a/lisp/face-remap.el
+++ b/lisp/face-remap.el
@@ -230,7 +230,8 @@ not to inherit from the global definition of FACE at all."
 
 (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 size of the `default'
+face's font by this amount."
   :group 'display
   :type 'number
   :version "23.1")
@@ -335,7 +336,7 @@ the same amount)."
 
 ;;;###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
@@ -347,14 +348,14 @@ will remove any scaling currently active."
          (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)))
@@ -365,19 +366,18 @@ See `text-scale-increase' for more details."
 ;;;###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 the font size in the 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
 keybinding 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 font size in current buffer by one step
+   -      Decrease 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
@@ -389,7 +389,12 @@ This command is a special-purpose wrapper around the
 `text-scale-increase' command which makes repetition convenient
 even when it is bound in a non-top-level keymap.  For binding in
 a top-level keymap, `text-scale-increase' or
-`text-scale-decrease' may be more appropriate."
+`text-scale-decrease' may be more appropriate.
+
+Most faces are affected by these font size changes, but not faces
+that have an explicit `:height' setting.  The two exceptions to
+this are the `default' and `header' faces: They will both be
+scaled even if they have an explicit `:height' setting."
   (interactive "p")
   (let ((ev last-command-event)
        (echo-keystrokes nil))
diff --git a/lisp/faces.el b/lisp/faces.el
index d92569e7cd..d104fdbc2f 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -709,14 +709,14 @@ a.k.a. `regular'), `semi-expanded' (a.k.a. 
`demi-expanded'),
 
 `: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 be493b3653..99ba9cb687 100644
--- a/lisp/mwheel.el
+++ b/lisp/mwheel.el
@@ -128,8 +128,9 @@ If AMOUNT is the symbol `hscroll', this means that with 
MODIFIER,
 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"
@@ -417,7 +418,8 @@ value of ARG, and the command uses it in subsequent 
scrolls."
 (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 55c9244f2e..7a850b07ee 100644
--- a/lisp/play/gamegrid.el
+++ b/lisp/play/gamegrid.el
@@ -458,6 +458,7 @@ convert to an Emacs image-spec instead")
     ;; 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: This is not correct.  See face-remap.el.
     (when (eq gamegrid-display-mode 'glyph)
       (overlay-put (make-overlay (point-min) (point-max))
                   'face gamegrid-face))