Facilitate font scaling and document the appearance section

README.org

@@ -1191,6 +1191,16 @@ Look into:
 
 * Appearance
 
+See the [[https://protesilaos.com/codelog/2020-09-05-emacs-note-mixed-font-heights/][note on mixed font heights in Emacs]] for how to setup fonts properly.  It
+boils down to two rules:
+1. The height of the default face must be an integer number to make the height a
+   physical quantity.
+2. The heights of all other faces must be real numbers to scale those heights
+   with respect to the height of the face (those heights default to 1.0 for no
+   scaling).
+
+The next source code blocks implement those rules.
+
 #+attr_latex: :options bgcolor=LightGoldenrodYellow
 #+begin_src emacs-lisp
   (unless noninteractive
@@ -1210,9 +1220,29 @@ Look into:
       (set-face-attribute 'variable-pitch nil :family "DejaVu Sans"))))
 #+end_src
 
+In case of proper initialization of all face heigths, font scaling is easy as
+the next source code block shows.
+
+#+begin_src emacs-lisp
+  (defun my-set-default-face-height ()
+    "Set the default face height in all current and future frames.
+
+  Scale all other faces with a height that is a real number."
+    (interactive)
+    (let* ((prompt (format "face heigth (%s): " (face-attribute 'default :height)))
+           (height (string-to-number
+                    (completing-read
+                     prompt
+                     (mapcar #'number-to-string (number-sequence 50 200 10))
+                     nil 'require-match))))
+      (message "Setting the height of the default face to %s" new)
+      (set-face-attribute 'default nil :height new)))
+#+end_src
+
 This setup prefers the ~leuven~ and ~leuven-dark~ themes from [[https://melpa.org/#/][MELPA]], because the
 very popular ~modus-operandi~ and ~modus-vivendi~ themes feel quirky: for
-instance those themes fail to display ~hl-line-mode~ with Emacs-27.2 on Darwin.
+instance those themes fail to display ~hl-line-mode~ properly with Emacs-27.2 on
+Darwin.
 
 [[https://emacs.stackexchange.com/questions/17431/how-do-i-change-portions-of-a-custom-theme][How to change custom theme faces]]