[elpa] externals/modus-themes 7ee0bcba71: Document how to add padding to Emacs frames and windows

[ELPA Syncer]

branch: externals/modus-themes
commit 7ee0bcba71d29483b3e7ec9c43688703c90fbf6c
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Document how to add padding to Emacs frames and windows
---
 doc/modus-themes.info | 326 +++++++++++++++++++++++++++++++-------------------
 doc/modus-themes.org  |  82 +++++++++++++
 2 files changed, 286 insertions(+), 122 deletions(-)

diff --git a/doc/modus-themes.info b/doc/modus-themes.info
index e11e74c5a6..4dbcef5465 100644
--- a/doc/modus-themes.info
+++ b/doc/modus-themes.info
@@ -140,6 +140,7 @@ Advanced customization
 * Backdrop for pdf-tools::
 * Toggle themes without reloading them::
 * A theme-agnostic hook for theme loading::
+* Use more spacious padding in Emacs frames::
 * Custom hl-todo colors::
 * Add support for solaire-mode::
 
@@ -1335,6 +1336,7 @@ such, they are labeled as “do-it-yourself” or “DIY”.
 * Backdrop for pdf-tools::
 * Toggle themes without reloading them::
 * A theme-agnostic hook for theme loading::
+* Use more spacious padding in Emacs frames::
 * Custom hl-todo colors::
 * Add support for solaire-mode::
 
@@ -3662,7 +3664,7 @@ their own command which calls ‘enable-theme’ instead of 
‘load-theme’:
    Recall that ‘modus-themes-toggle’ uses ‘load-theme’.
 
 
-File: modus-themes.info,  Node: A theme-agnostic hook for theme loading,  
Next: Custom hl-todo colors,  Prev: Toggle themes without reloading them,  Up: 
Advanced customization
+File: modus-themes.info,  Node: A theme-agnostic hook for theme loading,  
Next: Use more spacious padding in Emacs frames,  Prev: Toggle themes without 
reloading them,  Up: Advanced customization
 
 5.21 A theme-agnostic hook for theme loading
 ============================================
@@ -3713,9 +3715,88 @@ though the user can replace it with 
‘after-enable-theme-hook’ should
 they need to (provided they understand the implications).
 
 
-File: modus-themes.info,  Node: Custom hl-todo colors,  Next: Add support for 
solaire-mode,  Prev: A theme-agnostic hook for theme loading,  Up: Advanced 
customization
+File: modus-themes.info,  Node: Use more spacious padding in Emacs frames,  
Next: Custom hl-todo colors,  Prev: A theme-agnostic hook for theme loading,  
Up: Advanced customization
 
-5.22 Custom hl-todo colors
+5.22 Use more spacious padding in Emacs frames
+==============================================
+
+By default, Emacs frames try to maximize the number of characters that
+fit in the current visible portion of the buffer.  Users may prefer to
+have some extra padding instead.  This can make Emacs frames look more
+pleasant, but also make it easier to identify the currently active
+window.
+
+   The way to implement such padding is two-fold:
+
+  1. Instrument Emacs to use a higher value for the
+     ‘internal-border-width’ of all frames, as well as for the
+     ‘right-divider-width’.  The former concerns the outer boundaries of
+     Emacs frames, while the latter pertains to dividers between Emacs
+     windows.
+
+  2. Make the relevant faces invisible by changing the value of their
+     relevant attributes to that of the current theme’s main background.
+
+   The parameters of Emacs frames are specified in the variables
+‘initial-frame-alist’ and ‘default-frame-alist’.  The “initial frame”
+refers to the first frame that appears on Emacs startup.  The “default”
+refers to the fallback values that apply to all other frames that Emacs
+creates (unless those are explicitly overridden by a bespoke
+‘make-frame’ call).
+
+   In detail, first we use the same values for the two frame alist
+variables:
+
+     (dolist (var '(default-frame-alist initial-frame-alist))
+       (add-to-list var '(right-divider-width . 20))
+       (add-to-list var '(internal-border-width . 20)))
+
+   What the ‘dolist’ does is to call ‘add-to-list’ for the two variables
+we specify there.  This economizes on typing.
+
+   Then we define a function that makes the relevant faces invisible.
+The reason we do this with a function is so we can hook it to the “post
+load” phase of a theme, thus applying the new background value
+(otherwise you keep the old background, which likely means that the
+faces will no longer be invisible).
+
+     (defun prot-emacs-invisible-dividers ()
+       "Make window dividers invisible.
+     Add this to the `modus-themes-post-load-hook'."
+       (let ((bg (face-background 'default)))
+         (custom-set-faces
+          `(fringe ((t :background ,bg :foreground ,bg)))
+          `(window-divider ((t :background ,bg :foreground ,bg)))
+          `(window-divider-first-pixel ((t :background ,bg :foreground ,bg)))
+          `(window-divider-last-pixel ((t :background ,bg :foreground ,bg))))))
+
+     (add-hook 'modus-themes-post-load-hook #'prot-emacs-invisible-dividers)
+
+   The above will work only for themes that belong to the Modus family.
+For users of Emacs version 29 or higher, there exists a theme-agnostic
+hook that takes a function with one argument—that of the theme—and calls
+in the the “post enable” phase of theme loading.  Here is the above
+snippet, with the necessary tweaks:
+
+     (defun prot-emacs-invisible-dividers (_theme)
+       "Make window dividers for THEME invisible."
+       (let ((bg (face-background 'default)))
+         (custom-set-faces
+          `(fringe ((t :background ,bg :foreground ,bg)))
+          `(window-divider ((t :background ,bg :foreground ,bg)))
+          `(window-divider-first-pixel ((t :background ,bg :foreground ,bg)))
+          `(window-divider-last-pixel ((t :background ,bg :foreground ,bg))))))
+
+     (add-hook 'enable-theme-functions #'prot-emacs-invisible-dividers)
+
+   Users of older versions of Emacs can read the entry herein about
+defining their own theme-agnostic hook (*note A theme-agnostic hook for
+theme loading::).
+
+
+File: modus-themes.info,  Node: Custom hl-todo colors,  Next: Add support for 
solaire-mode,  Prev: Use more spacious padding in Emacs frames,  Up: Advanced 
customization
+
+5.23 Custom hl-todo colors
 ==========================
 
 The ‘hl-todo’ package provides the user option ‘hl-todo-keyword-faces’:
@@ -3750,7 +3831,7 @@ otherwise the defaults are not always legible.
 
 File: modus-themes.info,  Node: Add support for solaire-mode,  Prev: Custom 
hl-todo colors,  Up: Advanced customization
 
-5.23 Add support for solaire-mode
+5.24 Add support for solaire-mode
 =================================
 
 The ‘solaire-mode’ package dims the background of what it considers
@@ -6038,124 +6119,125 @@ B.3 Concept index
 
 Tag Table:
 Node: Top874
-Node: Overview8072
-Node: How do the themes look like10470
-Node: Learn about the latest changes10829
-Node: Installation11217
-Node: Install manually from source12147
-Node: Install from the archives12972
-Node: Install on GNU/Linux13571
-Node: Debian 11 Bullseye14064
-Node: GNU Guix14474
-Node: Dealing with byte compilation errors14757
-Node: Enable and load15915
-Node: The require-theme for built-in Emacs themes18769
-Node: Sample configuration with and without use-package19889
-Node: Differences between loading and enabling22800
-Node: Customization options24838
-Node: Custom reload theme28586
-Node: Disable other themes29494
-Node: Bold constructs30674
-Node: Italic constructs31511
-Node: Mixed fonts32282
-Node: Command prompts33278
-Node: Completion UIs35083
-Node: Org mode blocks37873
-Node: Heading styles39753
-Node: UI typeface44107
-Node: Palette overrides45038
-Node: Advanced customization49259
-Node: Palette override presets50865
-Node: Stylistic variants using palette overrides53739
-Node: Make the mode line borderless55651
-Node: Make the active mode line colorful57253
-Node: Make the tab bar more or less colorful59198
-Node: Make the fringe invisible or another color61429
-Node: Make links use subtle or no underlines62923
-Node: Make prompts more or less colorful63920
-Node: Make completion matches more or less colorful65584
-Node: Make comments yellow and strings green69484
-Node: Make code syntax use the old alt-syntax style71387
-Node: Make use of alternative styles for code syntax74668
-Node: Make matching parenthesis more or less intense78332
-Node: Make box buttons more or less gray79768
-Node: Make TODO and DONE more or less intense81074
-Node: Make headings more or less colorful82777
-Node: Make Org agenda more or less colorful85177
-Node: Make inline code in prose use alternative styles88637
-Node: Make mail citations and headers more or less colorful91178
-Node: Make the region preserve text colors plus other styles93873
-Node: Make mouse highlights more or less colorful95684
-Node: Make language underlines less colorful96991
-Node: Make line numbers use alternative styles98437
-Node: Make diffs use only a foreground100374
-Node: Make deuteranopia diffs red and blue instead of yellow and blue103145
-Node: Make the themes look like what the maintainer uses105567
-Node: More accurate colors in terminal emulators110265
-Node: Range of color with terminal emulators111557
-Node: Preview theme colors114271
-Node: Per-theme customization settings116116
-Node: Get a single color from the palette117462
-Node: Use theme colors in code with modus-themes-with-colors119771
-Node: Do not extend the region background122104
-Node: Add padding to mode line122902
-Node: Remap face with local value125460
-Node: Font configurations for Org and others127883
-Ref: Font configurations for Org and others-Footnote-1130792
-Node: Configure bold and italic faces130979
-Node: Custom Org todo keyword and priority faces135136
-Node: Custom Org emphasis faces138701
-Node: Update Org block delimiter fontification143524
-Node: Measure color contrast145441
-Node: Load theme depending on time of day148139
-Node: Backdrop for pdf-tools149149
-Node: Toggle themes without reloading them152048
-Node: A theme-agnostic hook for theme loading153324
-Node: Custom hl-todo colors155746
-Node: Add support for solaire-mode157271
-Node: Face coverage160182
-Node: Supported packages160634
-Node: Indirectly covered packages166147
-Node: Notes on individual packages167500
-Node: Note on calendarel weekday and weekend colors168600
-Node: Note on git-gutter in Doom Emacs169748
-Node: Note on php-mode multiline comments172089
-Node: Note on underlines in compilation buffers172842
-Node: Note on inline Latex in Org buffers173679
-Node: Note on dimmerel174289
-Node: Note on display-fill-column-indicator-mode175774
-Node: Note on highlight-parenthesesel177173
-Node: Note on mmm-modeel background colors183151
-Node: Note for prism185451
-Node: Note on company-mode overlay pop-up188619
-Ref: Note on company-mode overlay pop-up-Footnote-1189349
-Ref: Note on company-mode overlay pop-up-Footnote-2189416
-Node: Note on ERC escaped color sequences189471
-Ref: Note on ERC escaped color sequences-Footnote-1190899
-Node: Note on powerline or spaceline191009
-Node: Note on SHR colors191423
-Node: Note on SHR fonts191847
-Node: Note on Ement colors and fonts192486
-Node: Note on pdf-tools link hints193996
-Node: Note on the Notmuch logo196456
-Node: Note on goto-address-mode faces196994
-Node: Frequently Asked Questions198106
-Node: Is the contrast ratio about adjacent colors?198737
-Node: What does it mean to avoid exaggerations?200244
-Node: Why are colors mostly variants of blue magenta cyan?202094
-Node: What is the best setup for legibility?206400
-Node: Are these color schemes?209045
-Node: Port the Modus themes to other platforms?212727
-Node: Contributing215499
-Node: Sources of the themes215896
-Node: Issues you can help with216790
-Node: Patches require copyright assignment to the FSF218181
-Node: Acknowledgements220401
-Node: GNU Free Documentation License224443
-Node: Indices249807
-Node: Function index249986
-Node: Variable index251169
-Node: Concept index253348
+Node: Overview8118
+Node: How do the themes look like10516
+Node: Learn about the latest changes10875
+Node: Installation11263
+Node: Install manually from source12193
+Node: Install from the archives13018
+Node: Install on GNU/Linux13617
+Node: Debian 11 Bullseye14110
+Node: GNU Guix14520
+Node: Dealing with byte compilation errors14803
+Node: Enable and load15961
+Node: The require-theme for built-in Emacs themes18815
+Node: Sample configuration with and without use-package19935
+Node: Differences between loading and enabling22846
+Node: Customization options24884
+Node: Custom reload theme28632
+Node: Disable other themes29540
+Node: Bold constructs30720
+Node: Italic constructs31557
+Node: Mixed fonts32328
+Node: Command prompts33324
+Node: Completion UIs35129
+Node: Org mode blocks37919
+Node: Heading styles39799
+Node: UI typeface44153
+Node: Palette overrides45084
+Node: Advanced customization49305
+Node: Palette override presets50957
+Node: Stylistic variants using palette overrides53831
+Node: Make the mode line borderless55743
+Node: Make the active mode line colorful57345
+Node: Make the tab bar more or less colorful59290
+Node: Make the fringe invisible or another color61521
+Node: Make links use subtle or no underlines63015
+Node: Make prompts more or less colorful64012
+Node: Make completion matches more or less colorful65676
+Node: Make comments yellow and strings green69576
+Node: Make code syntax use the old alt-syntax style71479
+Node: Make use of alternative styles for code syntax74760
+Node: Make matching parenthesis more or less intense78424
+Node: Make box buttons more or less gray79860
+Node: Make TODO and DONE more or less intense81166
+Node: Make headings more or less colorful82869
+Node: Make Org agenda more or less colorful85269
+Node: Make inline code in prose use alternative styles88729
+Node: Make mail citations and headers more or less colorful91270
+Node: Make the region preserve text colors plus other styles93965
+Node: Make mouse highlights more or less colorful95776
+Node: Make language underlines less colorful97083
+Node: Make line numbers use alternative styles98529
+Node: Make diffs use only a foreground100466
+Node: Make deuteranopia diffs red and blue instead of yellow and blue103237
+Node: Make the themes look like what the maintainer uses105659
+Node: More accurate colors in terminal emulators110357
+Node: Range of color with terminal emulators111649
+Node: Preview theme colors114363
+Node: Per-theme customization settings116208
+Node: Get a single color from the palette117554
+Node: Use theme colors in code with modus-themes-with-colors119863
+Node: Do not extend the region background122196
+Node: Add padding to mode line122994
+Node: Remap face with local value125552
+Node: Font configurations for Org and others127975
+Ref: Font configurations for Org and others-Footnote-1130884
+Node: Configure bold and italic faces131071
+Node: Custom Org todo keyword and priority faces135228
+Node: Custom Org emphasis faces138793
+Node: Update Org block delimiter fontification143616
+Node: Measure color contrast145533
+Node: Load theme depending on time of day148231
+Node: Backdrop for pdf-tools149241
+Node: Toggle themes without reloading them152140
+Node: A theme-agnostic hook for theme loading153416
+Node: Use more spacious padding in Emacs frames155858
+Node: Custom hl-todo colors159570
+Node: Add support for solaire-mode161097
+Node: Face coverage164008
+Node: Supported packages164460
+Node: Indirectly covered packages169973
+Node: Notes on individual packages171326
+Node: Note on calendarel weekday and weekend colors172426
+Node: Note on git-gutter in Doom Emacs173574
+Node: Note on php-mode multiline comments175915
+Node: Note on underlines in compilation buffers176668
+Node: Note on inline Latex in Org buffers177505
+Node: Note on dimmerel178115
+Node: Note on display-fill-column-indicator-mode179600
+Node: Note on highlight-parenthesesel180999
+Node: Note on mmm-modeel background colors186977
+Node: Note for prism189277
+Node: Note on company-mode overlay pop-up192445
+Ref: Note on company-mode overlay pop-up-Footnote-1193175
+Ref: Note on company-mode overlay pop-up-Footnote-2193242
+Node: Note on ERC escaped color sequences193297
+Ref: Note on ERC escaped color sequences-Footnote-1194725
+Node: Note on powerline or spaceline194835
+Node: Note on SHR colors195249
+Node: Note on SHR fonts195673
+Node: Note on Ement colors and fonts196312
+Node: Note on pdf-tools link hints197822
+Node: Note on the Notmuch logo200282
+Node: Note on goto-address-mode faces200820
+Node: Frequently Asked Questions201932
+Node: Is the contrast ratio about adjacent colors?202563
+Node: What does it mean to avoid exaggerations?204070
+Node: Why are colors mostly variants of blue magenta cyan?205920
+Node: What is the best setup for legibility?210226
+Node: Are these color schemes?212871
+Node: Port the Modus themes to other platforms?216553
+Node: Contributing219325
+Node: Sources of the themes219722
+Node: Issues you can help with220616
+Node: Patches require copyright assignment to the FSF222007
+Node: Acknowledgements224227
+Node: GNU Free Documentation License228269
+Node: Indices253633
+Node: Function index253812
+Node: Variable index254995
+Node: Concept index257174
 
 End Tag Table
 
diff --git a/doc/modus-themes.org b/doc/modus-themes.org
index 8c6903f9ee..aa89fead69 100644
--- a/doc/modus-themes.org
+++ b/doc/modus-themes.org
@@ -3621,6 +3621,88 @@ In this document, we cover 
~modus-themes-after-load-theme-hook~ though
 the user can replace it with ~after-enable-theme-hook~ should they
 need to (provided they understand the implications).
 
+** Use more spacious padding in Emacs frames
+:PROPERTIES:
+:CUSTOM_ID: h:43bcb5d0-e25f-470f-828c-662cee9e21f1
+:END:
+
+By default, Emacs frames try to maximize the number of characters that
+fit in the current visible portion of the buffer.  Users may prefer to
+have some extra padding instead.  This can make Emacs frames look more
+pleasant, but also make it easier to identify the currently active
+window.
+
+The way to implement such padding is two-fold:
+
+1. Instrument Emacs to use a higher value for the
+   ~internal-border-width~ of all frames, as well as for the
+   ~right-divider-width~.  The former concerns the outer boundaries of
+   Emacs frames, while the latter pertains to dividers between Emacs
+   windows.
+
+2. Make the relevant faces invisible by changing the value of their
+   relevant attributes to that of the current theme's main background.
+
+The parameters of Emacs frames are specified in the variables
+~initial-frame-alist~ and ~default-frame-alist~.  The "initial frame"
+refers to the first frame that appears on Emacs startup.  The
+"default" refers to the fallback values that apply to all other frames
+that Emacs creates (unless those are explicitly overridden by a
+bespoke ~make-frame~ call).
+
+In detail, first we use the same values for the two frame alist variables:
+
+#+begin_src emacs-lisp
+(dolist (var '(default-frame-alist initial-frame-alist))
+  (add-to-list var '(right-divider-width . 20))
+  (add-to-list var '(internal-border-width . 20)))
+#+end_src
+
+What the ~dolist~ does is to call ~add-to-list~ for the two variables
+we specify there.  This economizes on typing.
+
+Then we define a function that makes the relevant faces invisible.
+The reason we do this with a function is so we can hook it to the
+"post load" phase of a theme, thus applying the new background value
+(otherwise you keep the old background, which likely means that the
+faces will no longer be invisible).
+
+#+begin_src emacs-lisp
+(defun prot-emacs-invisible-dividers ()
+  "Make window dividers invisible.
+Add this to the `modus-themes-post-load-hook'."
+  (let ((bg (face-background 'default)))
+    (custom-set-faces
+     `(fringe ((t :background ,bg :foreground ,bg)))
+     `(window-divider ((t :background ,bg :foreground ,bg)))
+     `(window-divider-first-pixel ((t :background ,bg :foreground ,bg)))
+     `(window-divider-last-pixel ((t :background ,bg :foreground ,bg))))))
+
+(add-hook 'modus-themes-post-load-hook #'prot-emacs-invisible-dividers)
+#+end_src
+
+The above will work only for themes that belong to the Modus family.
+For users of Emacs version 29 or higher, there exists a theme-agnostic
+hook that takes a function with one argument---that of the theme---and
+calls in the the "post enable" phase of theme loading.  Here is the
+above snippet, with the necessary tweaks:
+
+#+begin_src emacs-lisp
+(defun prot-emacs-invisible-dividers (_theme)
+  "Make window dividers for THEME invisible."
+  (let ((bg (face-background 'default)))
+    (custom-set-faces
+     `(fringe ((t :background ,bg :foreground ,bg)))
+     `(window-divider ((t :background ,bg :foreground ,bg)))
+     `(window-divider-first-pixel ((t :background ,bg :foreground ,bg)))
+     `(window-divider-last-pixel ((t :background ,bg :foreground ,bg))))))
+
+(add-hook 'enable-theme-functions #'prot-emacs-invisible-dividers)
+#+end_src
+
+Users of older versions of Emacs can read the entry herein about
+defining their own theme-agnostic hook 
([[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][A theme-agnostic hook for theme 
loading]]).
+
 ** Custom hl-todo colors
 :PROPERTIES:
 :CUSTOM_ID: h:2ef83a21-2f0a-441e-9634-473feb940743