[elpa] externals/modus-operandi-theme 2ffe984 16/54: Clarify docs for scaled headings and their values

[Stefan Monnier]

branch: externals/modus-operandi-theme
commit 2ffe9848acb3f728f5d338646053646fdf619eb9
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Clarify docs for scaled headings and their values
    
    This is meant to address the lack of clarity regarding the possible
    values that these variables may accept.  Refer to issue 43 for more on
    the matter: https://gitlab.com/protesilaos/modus-themes/-/issues/43
---
 README.org              | 18 +++++++++++++-----
 modus-operandi-theme.el | 45 ++++++++++++++++++++++++++++++++++++++++-----
 modus-vivendi-theme.el  | 45 ++++++++++++++++++++++++++++++++++++++++-----
 3 files changed, 93 insertions(+), 15 deletions(-)

diff --git a/README.org b/README.org
index 22ed876..bd440f6 100644
--- a/README.org
+++ b/README.org
@@ -210,11 +210,19 @@ noticeable in modes like Org.  The default is to use the 
same size for
 headers and body copy.
 
 In addition to toggles for enabling scaled headings, users can also
-specify the exact multiplier relative to the base font size.  These are
-the variables in their default sizes, from the smallest to the largest
-(the numbers are very conservative, but you are free to increase them a
-bit, such as =1.2=, =1.4=, =1.6=, =1.8=, =2.0=---or use a resource for finding 
a
-consistent scale, like [[https://www.modularscale.com][modularscale.com]]):
+specify a number of their own.
+
++ If it is a *floating point*, say, =1.5= then it is interpreted as a
+  multiple of the base font size (there are many ways to set the main
+  font on Emacs, such as those 
[[https://gitlab.com/protesilaos/modus-themes/-/issues/43#note_337308289][I 
documented in issue 43]]).
++ If it is an *integer*, it is read as an absolute font height.  The
+  number is basically the point size multiplied by a hundred.  So if you
+  want it to be =18pt= you must pass =180=.
+
+Below are the variables in their default values, using the floating
+point paradigm.  The numbers are very conservative, but you are free to
+change them to your liking, such as =1.2=, =1.4=, =1.6=, =1.8=, =2.0=---or use 
a
+resource for finding a consistent scale, like 
[[https://www.modularscale.com][modularscale.com]]:
 
 #+begin_src emacs-lisp
 (setq modus-operandi-theme-scale-1 1.05
diff --git a/modus-operandi-theme.el b/modus-operandi-theme.el
index 93429d3..003737f 100644
--- a/modus-operandi-theme.el
+++ b/modus-operandi-theme.el
@@ -400,23 +400,58 @@ between foreground and background is >= 7:1)."
   :type 'boolean)
 
 (defcustom modus-operandi-theme-scale-1 1.05
-  "Font size that is slightly larger than the base value."
+  "Font size that is slightly larger than the base value.
+The default is a floating point that is interpreted as a multiple
+of the base font size.  However, the variable also accepts an
+integer, understood as an absolute height (e.g. a value of 140 is
+the same as setting the font at 14 point size).
+
+For more on the matter, read the documentation of
+`set-face-attribute', specifically the ':height' section."
   :type 'number)
 
 (defcustom modus-operandi-theme-scale-2 1.1
-  "Font size slightly larger than `modus-operandi-theme-scale-1'."
+  "Font size slightly larger than `modus-operandi-theme-scale-1'.
+The default is a floating point that is interpreted as a multiple
+of the base font size.  However, the variable also accepts an
+integer, understood as an absolute height (e.g. a value of 140 is
+the same as setting the font at 14 point size).
+
+For more on the matter, read the documentation of
+`set-face-attribute', specifically the ':height' section."
   :type 'number)
 
 (defcustom modus-operandi-theme-scale-3 1.15
-  "Font size slightly larger than `modus-operandi-theme-scale-2'."
+  "Font size slightly larger than `modus-operandi-theme-scale-2'.
+The default is a floating point that is interpreted as a multiple
+of the base font size.  However, the variable also accepts an
+integer, understood as an absolute height (e.g. a value of 140 is
+the same as setting the font at 14 point size).
+
+For more on the matter, read the documentation of
+`set-face-attribute', specifically the ':height' section."
   :type 'number)
 
 (defcustom modus-operandi-theme-scale-4 1.2
-  "Font size slightly larger than `modus-operandi-theme-scale-3'."
+  "Font size slightly larger than `modus-operandi-theme-scale-3'.
+The default is a floating point that is interpreted as a multiple
+of the base font size.  However, the variable also accepts an
+integer, understood as an absolute height (e.g. a value of 140 is
+the same as setting the font at 14 point size).
+
+For more on the matter, read the documentation of
+`set-face-attribute', specifically the ':height' section."
   :type 'number)
 
 (defcustom modus-operandi-theme-scale-5 1.3
-  "Font size slightly larger than `modus-operandi-theme-scale-4'."
+  "Font size slightly larger than `modus-operandi-theme-scale-4'.
+The default is a floating point that is interpreted as a multiple
+of the base font size.  However, the variable also accepts an
+integer, understood as an absolute height (e.g. a value of 140 is
+the same as setting the font at 14 point size).
+
+For more on the matter, read the documentation of
+`set-face-attribute', specifically the ':height' section."
   :type 'number)
 
 (defcustom modus-operandi-theme-visible-fringes nil
diff --git a/modus-vivendi-theme.el b/modus-vivendi-theme.el
index 0fea2d0..169db5a 100644
--- a/modus-vivendi-theme.el
+++ b/modus-vivendi-theme.el
@@ -400,23 +400,58 @@ between foreground and background is >= 7:1)."
   :type 'boolean)
 
 (defcustom modus-vivendi-theme-scale-1 1.05
-  "Font size that is slightly larger than the base value."
+  "Font size that is slightly larger than the base value.
+The default is a floating point that is interpreted as a multiple
+of the base font size.  However, the variable also accepts an
+integer, understood as an absolute height (e.g. a value of 140 is
+the same as setting the font at 14 point size).
+
+For more on the matter, read the documentation of
+`set-face-attribute', specifically the ':height' section."
   :type 'number)
 
 (defcustom modus-vivendi-theme-scale-2 1.1
-  "Font size slightly larger than `modus-vivendi-theme-scale-1'."
+  "Font size slightly larger than `modus-vivendi-theme-scale-1'.
+The default is a floating point that is interpreted as a multiple
+of the base font size.  However, the variable also accepts an
+integer, understood as an absolute height (e.g. a value of 140 is
+the same as setting the font at 14 point size).
+
+For more on the matter, read the documentation of
+`set-face-attribute', specifically the ':height' section."
   :type 'number)
 
 (defcustom modus-vivendi-theme-scale-3 1.15
-  "Font size slightly larger than `modus-vivendi-theme-scale-2'."
+  "Font size slightly larger than `modus-vivendi-theme-scale-2'.
+The default is a floating point that is interpreted as a multiple
+of the base font size.  However, the variable also accepts an
+integer, understood as an absolute height (e.g. a value of 140 is
+the same as setting the font at 14 point size).
+
+For more on the matter, read the documentation of
+`set-face-attribute', specifically the ':height' section."
   :type 'number)
 
 (defcustom modus-vivendi-theme-scale-4 1.2
-  "Font size slightly larger than `modus-vivendi-theme-scale-3'."
+  "Font size slightly larger than `modus-vivendi-theme-scale-3'.
+The default is a floating point that is interpreted as a multiple
+of the base font size.  However, the variable also accepts an
+integer, understood as an absolute height (e.g. a value of 140 is
+the same as setting the font at 14 point size).
+
+For more on the matter, read the documentation of
+`set-face-attribute', specifically the ':height' section."
   :type 'number)
 
 (defcustom modus-vivendi-theme-scale-5 1.3
-  "Font size slightly larger than `modus-vivendi-theme-scale-4'."
+  "Font size slightly larger than `modus-vivendi-theme-scale-4'.
+The default is a floating point that is interpreted as a multiple
+of the base font size.  However, the variable also accepts an
+integer, understood as an absolute height (e.g. a value of 140 is
+the same as setting the font at 14 point size).
+
+For more on the matter, read the documentation of
+`set-face-attribute', specifically the ':height' section."
   :type 'number)
 
 (defcustom modus-vivendi-theme-visible-fringes nil