[elpa] externals/modus-themes 8bbebd2f39 1/4: Document how users can add support for meow

[ELPA Syncer]

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

    Document how users can add support for meow
    
    This is in response to the question raised by ZharMeny in issue 116:
    <https://github.com/protesilaos/modus-themes/issues/116>.
---
 doc/modus-themes.info | 288 ++++++++++++++++++++++++++++----------------------
 doc/modus-themes.org  |  31 ++++++
 2 files changed, 192 insertions(+), 127 deletions(-)

diff --git a/doc/modus-themes.info b/doc/modus-themes.info
index 941b766439..82223a4509 100644
--- a/doc/modus-themes.info
+++ b/doc/modus-themes.info
@@ -145,6 +145,7 @@ Advanced customization
 * DIY Use more spacious margins or padding in Emacs frames::
 * DIY Custom hl-todo colors::
 * DIY Add support for solaire-mode::
+* DIY Add support for meow-mode::
 * DIY Use a hook at the post-load-theme phase::
 
 DIY Stylistic variants using palette overrides
@@ -1615,6 +1616,7 @@ such, they are labeled as "do-it-yourself" or "DIY".
 * DIY Use more spacious margins or padding in Emacs frames::
 * DIY Custom hl-todo colors::
 * DIY Add support for solaire-mode::
+* DIY Add support for meow-mode::
 * DIY Use a hook at the post-load-theme phase::
 
 
@@ -3924,7 +3926,7 @@ otherwise the defaults are not always legible.
    Reload the theme for changes to take effect.
 
 
-File: modus-themes.info,  Node: DIY Add support for solaire-mode,  Next: DIY 
Use a hook at the post-load-theme phase,  Prev: DIY Custom hl-todo colors,  Up: 
Advanced customization
+File: modus-themes.info,  Node: DIY Add support for solaire-mode,  Next: DIY 
Add support for meow-mode,  Prev: DIY Custom hl-todo colors,  Up: Advanced 
customization
 
 7.20 DIY Add support for solaire-mode
 =====================================
@@ -3985,9 +3987,40 @@ the post-load-theme phase.
    Reload the theme for changes to take effect.
 
 
-File: modus-themes.info,  Node: DIY Use a hook at the post-load-theme phase,  
Prev: DIY Add support for solaire-mode,  Up: Advanced customization
+File: modus-themes.info,  Node: DIY Add support for meow-mode,  Next: DIY Use 
a hook at the post-load-theme phase,  Prev: DIY Add support for solaire-mode,  
Up: Advanced customization
 
-7.21 DIY Use a hook at the post-load-theme phase
+7.21 DIY Add support for meow-mode
+==================================
+
+The ‘meow’ package provides a modal editing experience.  It is meant to
+build on top of the key bindings the user is already familiar with.  My
+problem as an outsider is that I cannot make sense of all the contexts
+where its faces are used in, so I cannot make a good choice of which
+styles to use.  The following is but a basic attempt to get started.
+
+     ;; This is not complete, because it is difficult for a non-user to
+     ;; make sense of where all the faces are used in.
+     (defun my-modus-themes-custom-faces (&rest _)
+       (modus-themes-with-colors
+         (custom-set-faces
+          ;; FIXME: What is a "region cursor" and should it differ from the 
position highlights below?
+          `(meow-region-cursor-1 ((,c :inherit (bold modus-themes-reset-soft) 
:background ,bg-char-0)))
+          `(meow-region-cursor-2 ((,c :inherit (bold modus-themes-reset-soft) 
:background ,bg-char-1)))
+          `(meow-region-cursor-3 ((,c :inherit (bold modus-themes-reset-soft) 
:background ,bg-char-2)))
+
+          `(meow-position-highlight-number-1 ((,c :inherit (bold 
modus-themes-reset-soft) :background ,bg-char-0)))
+          `(meow-position-highlight-number-2 ((,c :inherit (bold 
modus-themes-reset-soft) :background ,bg-char-1)))
+          `(meow-position-highlight-number-3 ((,c :inherit (bold 
modus-themes-reset-soft) :background ,bg-char-2))))))
+
+     (add-hook 'enable-theme-functions #'my-modus-themes-custom-faces)
+
+   *note Using a hook at the post-load-theme phase: DIY Use a hook at
+the post-load-theme phase.
+
+
+File: modus-themes.info,  Node: DIY Use a hook at the post-load-theme phase,  
Prev: DIY Add support for meow-mode,  Up: Advanced customization
+
+7.22 DIY Use a hook at the post-load-theme phase
 ================================================
 
 Many of the Do-It-Yourself (DIY) snippets provided herein make use of a
@@ -4035,7 +4068,7 @@ it will not use them (in plain terms, the code works with 
or without
 
 File: modus-themes.info,  Node: DIY A theme-agnostic hook for theme loading,  
Up: DIY Use a hook at the post-load-theme phase
 
-7.21.1 DIY A theme-agnostic hook for theme loading
+7.22.1 DIY A theme-agnostic hook for theme loading
 --------------------------------------------------
 
 [ NOTE: The following is for versions of Emacs before 29.  For Emacs 29
@@ -6372,129 +6405,130 @@ B.3 Concept index
 
 Tag Table:
 Node: Top872
-Node: Overview8498
-Node: How do the themes look like11264
-Node: Learn about the latest changes11623
-Node: Installation12011
-Node: Install manually from source12937
-Node: Install from the archives13760
-Node: Install on GNU/Linux14359
-Node: Debian 11 Bullseye14850
-Node: GNU Guix15258
-Node: Dealing with byte compilation errors15541
-Node: Enable and load16699
-Node: The require-theme for built-in Emacs themes20643
-Node: Sample configuration with and without use-package21763
-Node: Differences between loading and enabling24609
-Node: Customization options26732
-Node: Custom reload theme30603
-Node: Disable other themes31523
-Node: Bold constructs32765
-Node: Italic constructs33637
-Node: Option for which themes to toggle34465
-Node: Mixed fonts35240
-Node: Command prompts36294
-Node: Completion UIs38135
-Node: Org mode blocks40984
-Node: Heading styles41627
-Node: UI typeface46053
-Node: Palette overrides47026
-Node: Palette extension51412
-Node: Preview theme colors53888
-Node: Use colors from the Modus themes palette55691
-Node: Get a single color from the palette with 
modus-themes-get-color-value56555
-Node: Use theme colors in code with modus-themes-with-colors58915
-Node: Advanced customization61169
-Node: DIY Palette override presets62820
-Node: DIY Stylistic variants using palette overrides65667
-Node: DIY Make the mode line borderless67721
-Node: DIY Make the active mode line colorful69096
-Node: DIY Make the tab bar more or less colorful71314
-Node: DIY Make the fringe invisible or another color73251
-Node: DIY Make links use subtle or no underlines74448
-Node: DIY Make prompts more or less colorful75566
-Node: DIY Make completion matches more or less colorful76889
-Node: DIY Make comments yellow and strings green80448
-Node: DIY Make code syntax use the old alt-syntax style82155
-Node: DIY Make use of alternative styles for code syntax85268
-Node: DIY Make matching parenthesis more or less intense88730
-Node: DIY Make box buttons more or less gray90102
-Node: DIY Make TODO and DONE more or less intense91115
-Node: DIY Make headings more or less colorful92616
-Node: DIY Make Org block colors more or less colorful94733
-Node: DIY Make Org agenda more or less colorful99105
-Node: DIY Make inline code in prose use alternative styles102280
-Node: DIY Make mail citations and headers more or less colorful104520
-Node: DIY Make the region preserve text colors plus other styles106920
-Node: DIY Make mouse highlights more or less colorful108476
-Node: DIY Make language underlines less colorful109489
-Node: DIY Make line numbers use alternative styles110641
-Node: DIY Make diffs use only a foreground112284
-Node: DIY Make deuteranopia diffs red and blue instead of yellow and 
blue115171
-Node: DIY More accurate colors in terminal emulators117643
-Node: DIY Range of color with terminal emulators118951
-Node: DIY Per-theme customization settings121738
-Node: DIY Do not extend the region background123171
-Node: DIY Add padding to the mode line123973
-Node: DIY Remap face with local value126901
-Node: DIY Font configurations for Org and others129440
-Ref: DIY Font configurations for Org and others-Footnote-1132421
-Node: DIY Configure bold and italic faces132608
-Node: DIY Custom Org todo keyword and priority faces137230
-Node: DIY Custom Org emphasis faces140971
-Node: DIY Use colored Org source blocks per language145848
-Node: DIY Measure color contrast150488
-Node: DIY Load theme depending on time of day153205
-Node: DIY Backdrop for pdf-tools154233
-Node: DIY Toggle themes without reloading them157394
-Node: DIY Use more spacious margins or padding in Emacs frames158703
-Node: DIY Custom hl-todo colors162940
-Node: DIY Add support for solaire-mode164757
-Node: DIY Use a hook at the post-load-theme phase167869
-Node: DIY A theme-agnostic hook for theme loading169991
-Node: Face coverage172622
-Node: Supported packages173074
-Node: Indirectly covered packages178818
-Node: Notes on individual packages180174
-Node: Note on calendarel weekday and weekend colors181274
-Node: Note on git-gutter in Doom Emacs182422
-Node: Note on php-mode multiline comments184922
-Node: Note on underlines in compilation buffers185682
-Node: Note on inline Latex in Org buffers186554
-Node: Note on dimmerel187164
-Node: Note on display-fill-column-indicator-mode188649
-Node: Note on highlight-parenthesesel190100
-Node: Note on mmm-modeel background colors196177
-Node: Note for prism198529
-Node: Note on company-mode overlay pop-up201741
-Ref: Note on company-mode overlay pop-up-Footnote-1202469
-Ref: Note on company-mode overlay pop-up-Footnote-2202536
-Node: Note on ERC escaped color sequences202591
-Ref: Note on ERC escaped color sequences-Footnote-1204019
-Node: Note on powerline or spaceline204129
-Node: Note on SHR colors204543
-Node: Note on SHR fonts204963
-Node: Note on Ement colors and fonts205650
-Node: Note on pdf-tools link hints207154
-Node: Note on the Notmuch logo209610
-Node: Note on goto-address-mode faces210142
-Node: Frequently Asked Questions211260
-Node: Is the contrast ratio about adjacent colors?211891
-Node: What does it mean to avoid exaggerations?213400
-Node: Why are colors mostly variants of blue magenta cyan?215250
-Node: What is the best setup for legibility?219584
-Node: Are these color schemes?222226
-Node: Port the Modus themes to other platforms?225880
-Node: Contributing228714
-Node: Sources of the themes229113
-Node: Issues you can help with230009
-Node: Patches require copyright assignment to the FSF231401
-Node: Acknowledgements233623
-Node: GNU Free Documentation License237884
-Node: Indices263047
-Node: Function index263226
-Node: Variable index264524
-Node: Concept index267875
+Node: Overview8532
+Node: How do the themes look like11298
+Node: Learn about the latest changes11657
+Node: Installation12045
+Node: Install manually from source12971
+Node: Install from the archives13794
+Node: Install on GNU/Linux14393
+Node: Debian 11 Bullseye14884
+Node: GNU Guix15292
+Node: Dealing with byte compilation errors15575
+Node: Enable and load16733
+Node: The require-theme for built-in Emacs themes20677
+Node: Sample configuration with and without use-package21797
+Node: Differences between loading and enabling24643
+Node: Customization options26766
+Node: Custom reload theme30637
+Node: Disable other themes31557
+Node: Bold constructs32799
+Node: Italic constructs33671
+Node: Option for which themes to toggle34499
+Node: Mixed fonts35274
+Node: Command prompts36328
+Node: Completion UIs38169
+Node: Org mode blocks41018
+Node: Heading styles41661
+Node: UI typeface46087
+Node: Palette overrides47060
+Node: Palette extension51446
+Node: Preview theme colors53922
+Node: Use colors from the Modus themes palette55725
+Node: Get a single color from the palette with 
modus-themes-get-color-value56589
+Node: Use theme colors in code with modus-themes-with-colors58949
+Node: Advanced customization61203
+Node: DIY Palette override presets62888
+Node: DIY Stylistic variants using palette overrides65735
+Node: DIY Make the mode line borderless67789
+Node: DIY Make the active mode line colorful69164
+Node: DIY Make the tab bar more or less colorful71382
+Node: DIY Make the fringe invisible or another color73319
+Node: DIY Make links use subtle or no underlines74516
+Node: DIY Make prompts more or less colorful75634
+Node: DIY Make completion matches more or less colorful76957
+Node: DIY Make comments yellow and strings green80516
+Node: DIY Make code syntax use the old alt-syntax style82223
+Node: DIY Make use of alternative styles for code syntax85336
+Node: DIY Make matching parenthesis more or less intense88798
+Node: DIY Make box buttons more or less gray90170
+Node: DIY Make TODO and DONE more or less intense91183
+Node: DIY Make headings more or less colorful92684
+Node: DIY Make Org block colors more or less colorful94801
+Node: DIY Make Org agenda more or less colorful99173
+Node: DIY Make inline code in prose use alternative styles102348
+Node: DIY Make mail citations and headers more or less colorful104588
+Node: DIY Make the region preserve text colors plus other styles106988
+Node: DIY Make mouse highlights more or less colorful108544
+Node: DIY Make language underlines less colorful109557
+Node: DIY Make line numbers use alternative styles110709
+Node: DIY Make diffs use only a foreground112352
+Node: DIY Make deuteranopia diffs red and blue instead of yellow and 
blue115239
+Node: DIY More accurate colors in terminal emulators117711
+Node: DIY Range of color with terminal emulators119019
+Node: DIY Per-theme customization settings121806
+Node: DIY Do not extend the region background123239
+Node: DIY Add padding to the mode line124041
+Node: DIY Remap face with local value126969
+Node: DIY Font configurations for Org and others129508
+Ref: DIY Font configurations for Org and others-Footnote-1132489
+Node: DIY Configure bold and italic faces132676
+Node: DIY Custom Org todo keyword and priority faces137298
+Node: DIY Custom Org emphasis faces141039
+Node: DIY Use colored Org source blocks per language145916
+Node: DIY Measure color contrast150556
+Node: DIY Load theme depending on time of day153273
+Node: DIY Backdrop for pdf-tools154301
+Node: DIY Toggle themes without reloading them157462
+Node: DIY Use more spacious margins or padding in Emacs frames158771
+Node: DIY Custom hl-todo colors163008
+Node: DIY Add support for solaire-mode164825
+Node: DIY Add support for meow-mode167923
+Node: DIY Use a hook at the post-load-theme phase169715
+Node: DIY A theme-agnostic hook for theme loading171834
+Node: Face coverage174465
+Node: Supported packages174917
+Node: Indirectly covered packages180661
+Node: Notes on individual packages182017
+Node: Note on calendarel weekday and weekend colors183117
+Node: Note on git-gutter in Doom Emacs184265
+Node: Note on php-mode multiline comments186765
+Node: Note on underlines in compilation buffers187525
+Node: Note on inline Latex in Org buffers188397
+Node: Note on dimmerel189007
+Node: Note on display-fill-column-indicator-mode190492
+Node: Note on highlight-parenthesesel191943
+Node: Note on mmm-modeel background colors198020
+Node: Note for prism200372
+Node: Note on company-mode overlay pop-up203584
+Ref: Note on company-mode overlay pop-up-Footnote-1204312
+Ref: Note on company-mode overlay pop-up-Footnote-2204379
+Node: Note on ERC escaped color sequences204434
+Ref: Note on ERC escaped color sequences-Footnote-1205862
+Node: Note on powerline or spaceline205972
+Node: Note on SHR colors206386
+Node: Note on SHR fonts206806
+Node: Note on Ement colors and fonts207493
+Node: Note on pdf-tools link hints208997
+Node: Note on the Notmuch logo211453
+Node: Note on goto-address-mode faces211985
+Node: Frequently Asked Questions213103
+Node: Is the contrast ratio about adjacent colors?213734
+Node: What does it mean to avoid exaggerations?215243
+Node: Why are colors mostly variants of blue magenta cyan?217093
+Node: What is the best setup for legibility?221427
+Node: Are these color schemes?224069
+Node: Port the Modus themes to other platforms?227723
+Node: Contributing230557
+Node: Sources of the themes230956
+Node: Issues you can help with231852
+Node: Patches require copyright assignment to the FSF233244
+Node: Acknowledgements235466
+Node: GNU Free Documentation License239727
+Node: Indices264890
+Node: Function index265069
+Node: Variable index266367
+Node: Concept index269718
 
 End Tag Table
 
diff --git a/doc/modus-themes.org b/doc/modus-themes.org
index 76d76d3b00..404bb553b0 100644
--- a/doc/modus-themes.org
+++ b/doc/modus-themes.org
@@ -3848,6 +3848,37 @@ on what we cover at length elsewhere in this manual:
 
 Reload the theme for changes to take effect.
 
+** DIY Add support for meow-mode
+:PROPERTIES:
+:CUSTOM_ID: h:caa5a5c4-18fb-4b9f-91f9-883f216fce41
+:END:
+
+The ~meow~ package provides a modal editing experience. It is meant to
+build on top of the key bindings the user is already familiar with. My
+problem as an outsider is that I cannot make sense of all the contexts
+where its faces are used in, so I cannot make a good choice of which
+styles to use. The following is but a basic attempt to get started.
+
+#+begin_src emacs-lisp
+;; This is not complete, because it is difficult for a non-user to
+;; make sense of where all the faces are used in.
+(defun my-modus-themes-custom-faces (&rest _)
+  (modus-themes-with-colors
+    (custom-set-faces
+     ;; FIXME: What is a "region cursor" and should it differ from the 
position highlights below?
+     `(meow-region-cursor-1 ((,c :inherit (bold modus-themes-reset-soft) 
:background ,bg-char-0)))
+     `(meow-region-cursor-2 ((,c :inherit (bold modus-themes-reset-soft) 
:background ,bg-char-1)))
+     `(meow-region-cursor-3 ((,c :inherit (bold modus-themes-reset-soft) 
:background ,bg-char-2)))
+
+     `(meow-position-highlight-number-1 ((,c :inherit (bold 
modus-themes-reset-soft) :background ,bg-char-0)))
+     `(meow-position-highlight-number-2 ((,c :inherit (bold 
modus-themes-reset-soft) :background ,bg-char-1)))
+     `(meow-position-highlight-number-3 ((,c :inherit (bold 
modus-themes-reset-soft) :background ,bg-char-2))))))
+
+(add-hook 'enable-theme-functions #'my-modus-themes-custom-faces)
+#+end_src
+
+[[#h:d87673fe-2ce1-4c80-a4b8-be36ca9f2d24][Using a hook at the post-load-theme 
phase]].
+
 ** DIY Use a hook at the post-load-theme phase
 :PROPERTIES:
 :CUSTOM_ID: h:d87673fe-2ce1-4c80-a4b8-be36ca9f2d24