[elpa] externals/modus-operandi-theme 4d594f0 050/153: Important update in manual entry about font config

[Stefan Monnier]

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

    Important update in manual entry about font config
    
    Only the 'default' face should ever use an absolute height.  Every other
    face should be configured to use a relative height.
---
 doc/modus-themes.info | 83 +++++++++++++++++++++++++++------------------------
 doc/modus-themes.org  | 47 +++++++++++++++--------------
 2 files changed, 69 insertions(+), 61 deletions(-)

diff --git a/doc/modus-themes.info b/doc/modus-themes.info
index 878d319..abe1b92 100644
--- a/doc/modus-themes.info
+++ b/doc/modus-themes.info
@@ -1050,7 +1050,7 @@ Currently this applies to ‘org-mode’ and ‘markdown-mode’.
 
    In practice it means that the user can safely opt for a more
 prose-friendly proportionately spaced typeface as their default, while
-letting spacing-sensitive elements like tables and inline code to always
+letting spacing-sensitive elements like tables and inline code always
 use a monospaced font, by inheriting from the ‘fixed-pitch’ face.
 
    Users can try the built-in ‘M-x variable-pitch-mode’ to see the
@@ -1059,7 +1059,7 @@ effect in action.
    To make everything use your desired font families, you need to
 configure the ‘variable-pitch’ (proportional spacing) and ‘fixed-pitch’
 (monospaced) faces respectively.  It may also be convenient to set your
-main typeface by configuring the ‘default’ face in the same way.
+main typeface by configuring the ‘default’ face the same way.
 
    Put something like this in your initialisation file (make sure to
 read the documentation of ‘set-face-attribute’, with ‘M-x
@@ -1067,29 +1067,34 @@ describe-function’):
 
      ;; Main typeface
      (set-face-attribute 'default nil :family "DejaVu Sans Mono" :height 110)
-     ;; Proportionately spaced typeface
-     (set-face-attribute 'variable-pitch nil :family "DejaVu Serif" :height 
110)
-     ;; Monospaced typeface
-     (set-face-attribute 'fixed-pitch nil :family "DejaVu Sans Mono" :height 
110)
 
-   The value of the ‘:height’ attribute essentially is the point size ×
-100.  So if you want to use a font at point size ‘11’, you set the
-height at ‘110’.  Values do not need to be rounded to multiples of ten:
-the likes of ‘115’ are perfectly valid.
+     ;; Proportionately spaced typeface
+     (set-face-attribute 'variable-pitch nil :family "DejaVu Serif" :height 
1.0)
 
-   An alternative syntax, which the author of this documents prefers, is
-to pass all typeface parameters directly to a ‘font’ property.(1)  Note
-that here we use a standard point size:
+     ;; Monospaced typeface
+     (set-face-attribute 'fixed-pitch nil :family "DejaVu Sans Mono" :height 
1.0)
+
+   Note the differences in the ‘:height’ property.  The ‘default’ face
+must specify an absolute value, which is the point size × 100.  So if
+you want to use a font at point size ‘11’, you set the height at
+‘110’.[fn:: ‘:height’ values do not need to be rounded to multiples of
+ten: the likes of ‘115’ are perfectly valid—some typefaces will change
+to account for those finer increments.)  Whereas every other face must
+have a value that is relative to the default, represented as a floating
+point (if you use an integer, say, ‘15’ then that means an absolute
+height).  This is of paramount importantance: it ensures that all fonts
+can scale gracefully when using something like the ‘text-scale-adjust’
+command which only operates on the base font size (i.e.  the ‘default’
+face’s absolute height).
+
+   An alternative syntax for the ‘default’ face, which the author of
+this documents prefers, is to pass all typeface parameters directly to a
+‘font’ property.(1)  Note that here we use a standard point size:
 
      (set-face-attribute 'default nil :font "DejaVu Sans Mono-11")
-     (set-face-attribute 'variable-pitch nil :font "DejaVu Serif-11")
-     (set-face-attribute 'fixed-pitch nil :font "DejaVu Sans Mono-11")
-
-   For a more succinct setup, you can configure the same value for
-multiple faces like this:
 
-     (dolist (face '(default fixed-pitch))
-       (set-face-attribute face nil :font "DejaVu Sans Mono-11"))
+   Again, remember to only ever specify an absolute height for the
+‘default’.
 
    ---------- Footnotes ----------
 
@@ -2275,25 +2280,25 @@ Node: Headings' font32998
 Node: Advanced customisation (do-it-yourself)33622
 Node: Tweak colours (DIY)34626
 Node: Font configs (DIY)38260
-Ref: Font configs (DIY)-Footnote-140692
-Node: Org user faces (DIY)40914
-Node: Face coverage43746
-Node: Supported packages44248
-Node: Covered indirectly50170
-Node: Will NOT be supported50522
-Node: Notes for individual packages51240
-Node: Note for powerline or spaceline51646
-Node: Note on shr colours52018
-Node: Note for Helm grep52431
-Node: Note on vc-annotate-background-mode53878
-Node: Contributing54732
-Node: Sources of the themes55151
-Node: Issues you can help with55913
-Node: Merge requests57100
-Node: Acknowledgements58182
-Node: Meta59639
-Node: External projects (ports)60692
-Node: GNU Free Documentation License61515
+Ref: Font configs (DIY)-Footnote-141024
+Node: Org user faces (DIY)41246
+Node: Face coverage44078
+Node: Supported packages44580
+Node: Covered indirectly50502
+Node: Will NOT be supported50854
+Node: Notes for individual packages51572
+Node: Note for powerline or spaceline51978
+Node: Note on shr colours52350
+Node: Note for Helm grep52763
+Node: Note on vc-annotate-background-mode54210
+Node: Contributing55064
+Node: Sources of the themes55483
+Node: Issues you can help with56245
+Node: Merge requests57432
+Node: Acknowledgements58514
+Node: Meta59971
+Node: External projects (ports)61024
+Node: GNU Free Documentation License61847
 
 End Tag Table
 
diff --git a/doc/modus-themes.org b/doc/modus-themes.org
index 241d283..159bbac 100644
--- a/doc/modus-themes.org
+++ b/doc/modus-themes.org
@@ -928,7 +928,7 @@ Currently this applies to =org-mode= and =markdown-mode=.
 
 In practice it means that the user can safely opt for a more
 prose-friendly proportionately spaced typeface as their default, while
-letting spacing-sensitive elements like tables and inline code to always
+letting spacing-sensitive elements like tables and inline code always
 use a monospaced font, by inheriting from the =fixed-pitch= face.
 
 Users can try the built-in =M-x variable-pitch-mode= to see the effect in
@@ -937,7 +937,7 @@ action.
 To make everything use your desired font families, you need to configure
 the =variable-pitch= (proportional spacing) and =fixed-pitch= (monospaced)
 faces respectively.  It may also be convenient to set your main typeface
-by configuring the =default= face in the same way.
+by configuring the =default= face the same way.
 
 Put something like this in your initialisation file (make sure to read
 the documentation of =set-face-attribute=, with =M-x describe-function=):
@@ -945,37 +945,40 @@ the documentation of =set-face-attribute=, with =M-x 
describe-function=):
 #+begin_src emacs-lisp
 ;; Main typeface
 (set-face-attribute 'default nil :family "DejaVu Sans Mono" :height 110)
+
 ;; Proportionately spaced typeface
-(set-face-attribute 'variable-pitch nil :family "DejaVu Serif" :height 110)
+(set-face-attribute 'variable-pitch nil :family "DejaVu Serif" :height 1.0)
+
 ;; Monospaced typeface
-(set-face-attribute 'fixed-pitch nil :family "DejaVu Sans Mono" :height 110)
+(set-face-attribute 'fixed-pitch nil :family "DejaVu Sans Mono" :height 1.0)
 #+end_src
 
-The value of the =:height= attribute essentially is the point size × 100.
-So if you want to use a font at point size =11=, you set the height at
-=110=.  Values do not need to be rounded to multiples of ten: the likes of
-=115= are perfectly valid.
-
-An alternative syntax, which the author of this documents prefers, is to
-pass all typeface parameters directly to a =font= property.[fn:: Has the
-benefit of accepting =fontconfig= parameters (GNU/Linux), such as ="DejaVu
-Sans Mono-11:hintstyle=hintslight:autohint=false"=.
+Note the differences in the =:height= property.  The =default= face must
+specify an absolute value, which is the point size × 100.  So if you
+want to use a font at point size =11=, you set the height at =110=.[fn::
+=:height= values do not need to be rounded to multiples of ten: the likes
+of =115= are perfectly valid—some typefaces will change to account for
+those finer increments.)  Whereas every other face must have a value
+that is relative to the default, represented as a floating point (if you
+use an integer, say, =15= then that means an absolute height).  This is of
+paramount importantance: it ensures that all fonts can scale gracefully
+when using something like the =text-scale-adjust= command which only
+operates on the base font size (i.e. the =default= face's absolute
+height).
+
+An alternative syntax for the =default= face, which the author of this
+documents prefers, is to pass all typeface parameters directly to a =font=
+property.[fn:: Has the benefit of accepting =fontconfig= parameters
+(GNU/Linux), such as ="DejaVu Sans
+Mono-11:hintstyle=hintslight:autohint=false"=.
 https://www.freedesktop.org/software/fontconfig/fontconfig-user.html]
 Note that here we use a standard point size:
 
 #+begin_src emacs-lisp
 (set-face-attribute 'default nil :font "DejaVu Sans Mono-11")
-(set-face-attribute 'variable-pitch nil :font "DejaVu Serif-11")
-(set-face-attribute 'fixed-pitch nil :font "DejaVu Sans Mono-11")
 #+end_src
 
-For a more succinct setup, you can configure the same value for multiple
-faces like this:
-
-#+begin_src emacs-lisp
-(dolist (face '(default fixed-pitch))
-  (set-face-attribute face nil :font "DejaVu Sans Mono-11"))
-#+end_src
+Again, remember to only ever specify an absolute height for the =default=.
 
 ** Org user faces (DIY)
 :PROPERTIES: