branch: externals/modus-themes
commit 6fc763066624f79f316e56a5fb933d79cf19b2c9
Author: Protesilaos Stavrou <[email protected]>
Commit: Protesilaos Stavrou <[email protected]>
Document how to activate derivative themes
---
doc/modus-themes.info | 329 +++++++++++++++++++++++++++++---------------------
doc/modus-themes.org | 60 +++++++++
2 files changed, 253 insertions(+), 136 deletions(-)
diff --git a/doc/modus-themes.info b/doc/modus-themes.info
index d8524aa138..a4662e20fc 100644
--- a/doc/modus-themes.info
+++ b/doc/modus-themes.info
@@ -191,6 +191,7 @@ Build on top of the Modus themes
* Complete example of a Modus derivative theme::
* Determine what counts as a Modus theme::
* Create convenience commands to load a derivative theme::
+* Arrange to activate your derivative themes::
Complete example of a Modus derivative theme
@@ -4458,6 +4459,7 @@ corresponds to some named color in the palette of the
active theme.
* Complete example of a Modus derivative theme::
* Determine what counts as a Modus theme::
* Create convenience commands to load a derivative theme::
+* Arrange to activate your derivative themes::
File: modus-themes.info, Node: Complete example of a Modus derivative theme,
Next: Determine what counts as a Modus theme, Up: Build on top of the Modus
themes
@@ -4571,6 +4573,8 @@ Packages such as the ‘ef-themes’ and ‘standard-themes’
are exceptions
because they existed for years before they were based on Modus and must
remain backward compatible.
+ *note Arrange to activate your derivative themes::.
+
File: modus-themes.info, Node: Complete example of a private theme derived
from Modus, Next: Complete example of a custom theme with its own palette,
Prev: Complete example of a package that is derived from Modus, Up: Complete
example of a Modus derivative theme
@@ -4606,6 +4610,8 @@ example of a custom theme with its own palette::):
nil
nil)
+ *note Arrange to activate your derivative themes::.
+
File: modus-themes.info, Node: Complete example of a custom theme with its
own palette, Next: Complete example that also uses
modus-themes-generate-palette, Prev: Complete example of a private theme
derived from Modus, Up: Complete example of a Modus derivative theme
@@ -4720,6 +4726,8 @@ this example, ‘bg-ochre’ comes from the
‘modus-operandi-palette’ though
it would work the same way if, say, ‘prot-light-palette’ defined
‘bg-soil’ and then referenced it in ‘prot-light-custom-faces’.
+ *note Arrange to activate your derivative themes::.
+
File: modus-themes.info, Node: Complete example that also uses
modus-themes-generate-palette, Prev: Complete example of a custom theme with
its own palette, Up: Complete example of a Modus derivative theme
@@ -5090,6 +5098,8 @@ package that is derived from Modus::).
nil
nil)
+ *note Arrange to activate your derivative themes::.
+
File: modus-themes.info, Node: Determine what counts as a Modus theme, Next:
Create convenience commands to load a derivative theme, Prev: Complete example
of a Modus derivative theme, Up: Build on top of the Modus themes
@@ -5161,7 +5171,7 @@ on.
modus-themes-items))
-File: modus-themes.info, Node: Create convenience commands to load a
derivative theme, Prev: Determine what counts as a Modus theme, Up: Build on
top of the Modus themes
+File: modus-themes.info, Node: Create convenience commands to load a
derivative theme, Next: Arrange to activate your derivative themes, Prev:
Determine what counts as a Modus theme, Up: Build on top of the Modus themes
8.3 Create convenience commands to load a derivative theme
==========================================================
@@ -5211,6 +5221,52 @@ command. For example, if ‘SUFFIX’ is ‘rotate’ and
‘FAMILY’ is
what the command is doing), though this approach with the ‘cl-letf’ can
still prove useful.
+
+File: modus-themes.info, Node: Arrange to activate your derivative themes,
Prev: Create convenience commands to load a derivative theme, Up: Build on top
of the Modus themes
+
+8.4 Arrange to activate your derivative themes
+==============================================
+
+The ‘modus-themes-theme’ function is responsible for instantiating a
+theme and registering it for use by the various Modus commands that act
+on a theme (*note Build on top of the Modus themes::). Due to how Emacs
+themes are designed to be bound to files, ‘modus-themes-theme’ can only
+work if the given theme file is already loaded. Otherwise our function
+is never called and the theme is never created.
+
+ To this end, users need to call the function ‘modus-themes-activate’
+with each theme they want as an argument. Remember that themes are
+files with a ‘-theme.el’ suffix inside one of the directories listed in
+the value of the variable ‘custom-theme-load-path’. In its simplest
+form, the activation looks as follows, assuming the theme's file
+‘modus-solarized-dark-theme.el’ exists:
+
+ (modus-themes-activate 'modus-solarized-dark)
+
+ To load multiple themes at once we can define a function like the
+following:
+
+ (defun my-modus-derivatives-activate-themes (directory)
+ "Activate all themes in DIRECTORY.
+ This makes all Modus derivatives available to commands such as
+ `modus-themes-select' if `modus-themes-include-derivatives-mode' is
+ enabled."
+ (let* ((files (directory-files directory :full-path "-theme\\.el"))
+ (names (mapcar
+ (lambda (file)
+ (intern (replace-regexp-in-string "-theme\\.el" ""
file)))
+ files)))
+ (mapc #'modus-themes-activate names)))
+
+ Then call it thus:
+
+ (my-modus-derivatives-activate-themes
"/path/to/my/custom/theme/directory/")
+
+ Again, remember that the directory is in the
+‘custom-theme-load-path’:
+
+ (add-to-list 'custom-theme-load-path
"/path/to/my/custom/theme/directory/")
+
File: modus-themes.info, Node: Face coverage, Next: Notes on individual
packages, Prev: Build on top of the Modus themes, Up: Top
@@ -7576,141 +7632,142 @@ B.3 Concept index
Tag Table:
Node: Top874
-Node: Overview9105
-Node: How do the themes look like11871
-Node: Learn about the latest changes12230
-Node: Installation12618
-Node: Install manually from source13529
-Node: Install from the archives14352
-Node: Install on GNU/Linux14951
-Node: Debian 11 Bullseye15442
-Node: GNU Guix15850
-Node: Dealing with byte compilation errors16133
-Node: Enable and load17291
-Node: The require-theme for built-in Emacs themes21570
-Node: Sample configuration22487
-Node: Differences between loading and enabling24763
-Node: Customization options26828
-Node: Disable other themes30597
-Node: Bold constructs31951
-Node: Italic constructs32823
-Node: Option for which themes to toggle33651
-Node: Option for which themes to rotate34414
-Node: Mixed fonts35411
-Node: Command prompts36465
-Node: Completion UIs38306
-Node: Org mode blocks41155
-Node: Heading styles41798
-Node: UI typeface46224
-Node: Palette overrides47197
-Node: Palette extension51554
-Node: Preview theme colors54030
-Node: Commands for the preview palette buffer55685
-Node: Use colors from the Modus themes palette57763
-Node: Get a single color from the palette with
modus-themes-get-color-value58627
-Node: Use theme colors in code with modus-themes-with-colors60988
-Node: Advanced customization63242
-Node: DIY Palette override presets65020
-Node: DIY Add support for engrave-faces67854
-Node: DIY Stylistic variants using palette overrides77837
-Node: DIY Make the mode line borderless79896
-Node: DIY Make the active mode line colorful81271
-Node: DIY Make the tab bar more or less colorful83489
-Node: DIY Make the fringe invisible or another color85426
-Node: DIY Make links use subtle or no underlines86623
-Node: DIY Make prompts more or less colorful87741
-Node: DIY Make completion matches more or less colorful89064
-Node: DIY Make comments yellow and strings green92623
-Node: DIY Make code syntax use the old alt-syntax style94330
-Node: DIY Make use of alternative styles for code syntax97443
-Node: DIY Make matching parenthesis more or less intense100905
-Node: DIY Make box buttons more or less gray102277
-Node: DIY Make TODO and DONE more or less intense103290
-Node: DIY Make headings more or less colorful104791
-Node: DIY Make Org block colors more or less colorful106908
-Node: DIY Make Org agenda more or less colorful111280
-Node: DIY Make inline code in prose use alternative styles114455
-Node: DIY Make mail citations and headers more or less colorful116695
-Node: DIY Make the region preserve text colors plus other styles119095
-Node: DIY Make mouse highlights more or less colorful120651
-Node: DIY Make language underlines less colorful121664
-Node: DIY Make line numbers use alternative styles122816
-Node: DIY Make diffs use only a foreground124459
-Node: DIY Make deuteranopia diffs red and blue instead of yellow and
blue127346
-Node: DIY More accurate colors in terminal emulators129818
-Node: DIY Range of color with terminal emulators131126
-Node: DIY Per-theme customization settings133913
-Node: DIY Do not extend the region background135346
-Node: DIY Add padding to the mode line136144
-Node: DIY Remap face with local value139072
-Node: DIY Font configurations for Org and others141611
-Ref: DIY Font configurations for Org and others-Footnote-1144594
-Node: DIY Configure bold and italic faces144781
-Node: DIY Custom Org todo keyword and priority faces149403
-Node: DIY Custom Org emphasis faces153144
-Node: DIY Use colored Org source blocks per language158021
-Node: DIY Measure color contrast162661
-Node: DIY Load theme depending on time of day165378
-Node: DIY Backdrop for pdf-tools166406
-Node: DIY Toggle themes without reloading them169567
-Node: DIY Use more spacious margins or padding in Emacs frames170876
-Node: DIY Custom hl-todo colors175113
-Node: DIY Add support for solaire-mode176930
-Node: DIY Add support for meow-mode180022
-Node: DIY Add support for combobulate181832
-Node: DIY Use a hook at the post-load-theme phase185455
-Node: DIY A theme-agnostic hook for theme loading187576
-Node: Build on top of the Modus themes190207
-Node: Complete example of a Modus derivative theme196380
-Node: Complete example of a package that is derived from Modus197386
-Node: Complete example of a private theme derived from Modus200325
-Node: Complete example of a custom theme with its own palette201891
-Node: Complete example that also uses modus-themes-generate-palette206502
-Node: Determine what counts as a Modus theme223215
-Node: Create convenience commands to load a derivative theme226625
-Node: Face coverage228842
-Node: Supported packages229304
-Node: Indirectly covered packages235170
-Node: Notes on individual packages236526
-Node: Note on calendarel weekday and weekend colors237628
-Node: Note on git-gutter in Doom Emacs238778
-Node: Note on php-mode multiline comments241280
-Node: Note on underlines in compilation buffers242042
-Node: Note on inline Latex in Org buffers242916
-Node: Note on dimmerel243528
-Node: Note on display-fill-column-indicator-mode245015
-Node: Note on highlight-parenthesesel246468
-Node: Note on mmm-modeel background colors252547
-Node: Note for prism254901
-Node: Note on company-mode overlay pop-up258115
-Ref: Note on company-mode overlay pop-up-Footnote-1258845
-Ref: Note on company-mode overlay pop-up-Footnote-2258912
-Node: Note on ERC escaped color sequences258967
-Ref: Note on ERC escaped color sequences-Footnote-1260397
-Node: Note on powerline or spaceline260507
-Node: Note on SHR colors260923
-Node: Note on SHR fonts261345
-Node: Note on Ement colors and fonts262034
-Node: Note on pdf-tools link hints263540
-Node: Note on the Notmuch logo265998
-Node: Note on goto-address-mode faces266532
-Node: Frequently Asked Questions267652
-Node: Is the contrast ratio about adjacent colors?268283
-Node: What does it mean to avoid exaggerations?269792
-Node: Why are colors mostly variants of blue magenta cyan?271642
-Node: What is the best setup for legibility?275976
-Node: Are these color schemes?278618
-Node: Port the Modus themes to other platforms?282272
-Node: Contributing285106
-Node: Sources of the themes285505
-Node: Issues you can help with286401
-Node: Patches require copyright assignment to the FSF287793
-Node: Acknowledgements290015
-Node: GNU Free Documentation License294635
-Node: Indices319798
-Node: Function index319977
-Node: Variable index325135
-Node: Concept index329852
+Node: Overview9152
+Node: How do the themes look like11918
+Node: Learn about the latest changes12277
+Node: Installation12665
+Node: Install manually from source13576
+Node: Install from the archives14399
+Node: Install on GNU/Linux14998
+Node: Debian 11 Bullseye15489
+Node: GNU Guix15897
+Node: Dealing with byte compilation errors16180
+Node: Enable and load17338
+Node: The require-theme for built-in Emacs themes21617
+Node: Sample configuration22534
+Node: Differences between loading and enabling24810
+Node: Customization options26875
+Node: Disable other themes30644
+Node: Bold constructs31998
+Node: Italic constructs32870
+Node: Option for which themes to toggle33698
+Node: Option for which themes to rotate34461
+Node: Mixed fonts35458
+Node: Command prompts36512
+Node: Completion UIs38353
+Node: Org mode blocks41202
+Node: Heading styles41845
+Node: UI typeface46271
+Node: Palette overrides47244
+Node: Palette extension51601
+Node: Preview theme colors54077
+Node: Commands for the preview palette buffer55732
+Node: Use colors from the Modus themes palette57810
+Node: Get a single color from the palette with
modus-themes-get-color-value58674
+Node: Use theme colors in code with modus-themes-with-colors61035
+Node: Advanced customization63289
+Node: DIY Palette override presets65067
+Node: DIY Add support for engrave-faces67901
+Node: DIY Stylistic variants using palette overrides77884
+Node: DIY Make the mode line borderless79943
+Node: DIY Make the active mode line colorful81318
+Node: DIY Make the tab bar more or less colorful83536
+Node: DIY Make the fringe invisible or another color85473
+Node: DIY Make links use subtle or no underlines86670
+Node: DIY Make prompts more or less colorful87788
+Node: DIY Make completion matches more or less colorful89111
+Node: DIY Make comments yellow and strings green92670
+Node: DIY Make code syntax use the old alt-syntax style94377
+Node: DIY Make use of alternative styles for code syntax97490
+Node: DIY Make matching parenthesis more or less intense100952
+Node: DIY Make box buttons more or less gray102324
+Node: DIY Make TODO and DONE more or less intense103337
+Node: DIY Make headings more or less colorful104838
+Node: DIY Make Org block colors more or less colorful106955
+Node: DIY Make Org agenda more or less colorful111327
+Node: DIY Make inline code in prose use alternative styles114502
+Node: DIY Make mail citations and headers more or less colorful116742
+Node: DIY Make the region preserve text colors plus other styles119142
+Node: DIY Make mouse highlights more or less colorful120698
+Node: DIY Make language underlines less colorful121711
+Node: DIY Make line numbers use alternative styles122863
+Node: DIY Make diffs use only a foreground124506
+Node: DIY Make deuteranopia diffs red and blue instead of yellow and
blue127393
+Node: DIY More accurate colors in terminal emulators129865
+Node: DIY Range of color with terminal emulators131173
+Node: DIY Per-theme customization settings133960
+Node: DIY Do not extend the region background135393
+Node: DIY Add padding to the mode line136191
+Node: DIY Remap face with local value139119
+Node: DIY Font configurations for Org and others141658
+Ref: DIY Font configurations for Org and others-Footnote-1144641
+Node: DIY Configure bold and italic faces144828
+Node: DIY Custom Org todo keyword and priority faces149450
+Node: DIY Custom Org emphasis faces153191
+Node: DIY Use colored Org source blocks per language158068
+Node: DIY Measure color contrast162708
+Node: DIY Load theme depending on time of day165425
+Node: DIY Backdrop for pdf-tools166453
+Node: DIY Toggle themes without reloading them169614
+Node: DIY Use more spacious margins or padding in Emacs frames170923
+Node: DIY Custom hl-todo colors175160
+Node: DIY Add support for solaire-mode176977
+Node: DIY Add support for meow-mode180069
+Node: DIY Add support for combobulate181879
+Node: DIY Use a hook at the post-load-theme phase185502
+Node: DIY A theme-agnostic hook for theme loading187623
+Node: Build on top of the Modus themes190254
+Node: Complete example of a Modus derivative theme196474
+Node: Complete example of a package that is derived from Modus197480
+Node: Complete example of a private theme derived from Modus200475
+Node: Complete example of a custom theme with its own palette202097
+Node: Complete example that also uses modus-themes-generate-palette206764
+Node: Determine what counts as a Modus theme223533
+Node: Create convenience commands to load a derivative theme226943
+Node: Arrange to activate your derivative themes229211
+Node: Face coverage231267
+Node: Supported packages231729
+Node: Indirectly covered packages237595
+Node: Notes on individual packages238951
+Node: Note on calendarel weekday and weekend colors240053
+Node: Note on git-gutter in Doom Emacs241203
+Node: Note on php-mode multiline comments243705
+Node: Note on underlines in compilation buffers244467
+Node: Note on inline Latex in Org buffers245341
+Node: Note on dimmerel245953
+Node: Note on display-fill-column-indicator-mode247440
+Node: Note on highlight-parenthesesel248893
+Node: Note on mmm-modeel background colors254972
+Node: Note for prism257326
+Node: Note on company-mode overlay pop-up260540
+Ref: Note on company-mode overlay pop-up-Footnote-1261270
+Ref: Note on company-mode overlay pop-up-Footnote-2261337
+Node: Note on ERC escaped color sequences261392
+Ref: Note on ERC escaped color sequences-Footnote-1262822
+Node: Note on powerline or spaceline262932
+Node: Note on SHR colors263348
+Node: Note on SHR fonts263770
+Node: Note on Ement colors and fonts264459
+Node: Note on pdf-tools link hints265965
+Node: Note on the Notmuch logo268423
+Node: Note on goto-address-mode faces268957
+Node: Frequently Asked Questions270077
+Node: Is the contrast ratio about adjacent colors?270708
+Node: What does it mean to avoid exaggerations?272217
+Node: Why are colors mostly variants of blue magenta cyan?274067
+Node: What is the best setup for legibility?278401
+Node: Are these color schemes?281043
+Node: Port the Modus themes to other platforms?284697
+Node: Contributing287531
+Node: Sources of the themes287930
+Node: Issues you can help with288826
+Node: Patches require copyright assignment to the FSF290218
+Node: Acknowledgements292440
+Node: GNU Free Documentation License297060
+Node: Indices322223
+Node: Function index322402
+Node: Variable index327560
+Node: Concept index332277
End Tag Table
diff --git a/doc/modus-themes.org b/doc/modus-themes.org
index acffe8a09b..129c3581b7 100644
--- a/doc/modus-themes.org
+++ b/doc/modus-themes.org
@@ -4398,6 +4398,8 @@ Packages such as the ~ef-themes~ and ~standard-themes~
are exceptions
because they existed for years before they were based on Modus and
must remain backward compatible.
+[[#h:6eb0dba7-89cb-4b21-bc5d-97f6b5eb3caa][Arrange to activate your derivative
themes]].
+
*** Complete example of a private theme derived from Modus
:PROPERTIES:
:CUSTOM_ID: h:48e391a6-831b-48ec-b92d-4e7e6871b043
@@ -4435,6 +4437,8 @@ At minimum, the contents of a theme file are these
([[#h:ca3031b5-5f7a-46d4-bc83
nil)
#+end_src
+[[#h:6eb0dba7-89cb-4b21-bc5d-97f6b5eb3caa][Arrange to activate your derivative
themes]].
+
*** Complete example of a custom theme with its own palette
:PROPERTIES:
:CUSTOM_ID: h:ca3031b5-5f7a-46d4-bc83-e84e8bed038c
@@ -4551,6 +4555,8 @@ this example, =bg-ochre= comes from the
~modus-operandi-palette~
though it would work the same way if, say, ~prot-light-palette~
defined ~bg-soil~ and then referenced it in ~prot-light-custom-faces~.
+[[#h:6eb0dba7-89cb-4b21-bc5d-97f6b5eb3caa][Arrange to activate your derivative
themes]].
+
*** Complete example that also uses ~modus-themes-generate-palette~
:PROPERTIES:
:CUSTOM_ID: h:3a7ede17-f0d4-4322-8e69-1804ed69012b
@@ -4938,6 +4944,8 @@ And the light variant:
nil)
#+end_src
+[[#h:6eb0dba7-89cb-4b21-bc5d-97f6b5eb3caa][Arrange to activate your derivative
themes]].
+
** Determine what counts as a Modus theme
:PROPERTIES:
:CUSTOM_ID: h:412e3017-81fe-4a95-97a6-225de1867757
@@ -5066,6 +5074,58 @@ because the developer wants to introduce a user option
to affect what
the command is doing), though this approach with the ~cl-letf~ can
still prove useful.
+** Arrange to activate your derivative themes
+:PROPERTIES:
+:CUSTOM_ID: h:6eb0dba7-89cb-4b21-bc5d-97f6b5eb3caa
+:END:
+
+The ~modus-themes-theme~ function is responsible for instantiating a
+theme and registering it for use by the various Modus commands that
+act on a theme ([[#h:86eb375b-9be4-43ce-879a-0686a524a63b][Build on top of the
Modus themes]]). Due to how Emacs
+themes are designed to be bound to files, ~modus-themes-theme~ can
+only work if the given theme file is already loaded. Otherwise our
+function is never called and the theme is never created.
+
+To this end, users need to call the function ~modus-themes-activate~
+with each theme they want as an argument. Remember that themes are
+files with a =-theme.el= suffix inside one of the directories listed
+in the value of the variable ~custom-theme-load-path~. In its simplest
+form, the activation looks as follows, assuming the theme's file
+=modus-solarized-dark-theme.el= exists:
+
+#+begin_src emacs-lisp
+(modus-themes-activate 'modus-solarized-dark)
+#+end_src
+
+To load multiple themes at once we can define a function like the
+following:
+
+#+begin_src emacs-lisp
+(defun my-modus-derivatives-activate-themes (directory)
+ "Activate all themes in DIRECTORY.
+This makes all Modus derivatives available to commands such as
+`modus-themes-select' if `modus-themes-include-derivatives-mode' is
+enabled."
+ (let* ((files (directory-files directory :full-path "-theme\\.el"))
+ (names (mapcar
+ (lambda (file)
+ (intern (replace-regexp-in-string "-theme\\.el" "" file)))
+ files)))
+ (mapc #'modus-themes-activate names)))
+#+end_src
+
+Then call it thus:
+
+#+begin_src emacs-lisp
+(my-modus-derivatives-activate-themes "/path/to/my/custom/theme/directory/")
+#+end_src
+
+Again, remember that the directory is in the ~custom-theme-load-path~:
+
+#+begin_src emacs-lisp
+(add-to-list 'custom-theme-load-path "/path/to/my/custom/theme/directory/")
+#+end_src
+
* Face coverage
:properties:
:custom_id: h:a9c8f29d-7f72-4b54-b74b-ddefe15d6a19
