diff options
| author | Protesilaos <info@protesilaos.com> | 2026-05-01 21:52:03 +0300 |
|---|---|---|
| committer | Protesilaos <info@protesilaos.com> | 2026-05-01 21:52:03 +0300 |
| commit | 010ed945271bbf98e2bd46cd419ab41878cc279f (patch) | |
| tree | 11585082b09fd35558955d4dda80757085fca8e1 | |
| parent | 0164619a09d8bd4a46892028afd7cfb5b6c300d3 (diff) | |
Start rewriting the manual
I will review the entire document, but this is enough for the evening.
| -rw-r--r-- | doc/modus-themes.info | 1626 | ||||
| -rw-r--r-- | doc/modus-themes.org | 923 |
2 files changed, 1135 insertions, 1414 deletions
diff --git a/doc/modus-themes.info b/doc/modus-themes.info index 7990215..6178532 100644 --- a/doc/modus-themes.info +++ b/doc/modus-themes.info @@ -64,6 +64,7 @@ as such. * Overview:: * Installation:: +* Sample configuration:: * Enable and load:: * Customization options:: * Preview theme colors:: @@ -88,20 +89,17 @@ Overview Installation * Install manually from source:: -* Install from the archives:: -* Install on GNU/Linux:: +* Install from source with package-vc-install:: +* Install from GNU ELPA:: * Dealing with byte compilation errors:: -Install on GNU/Linux +Sample configuration -* Debian 11 Bullseye:: -* GNU Guix:: +* The require-theme for built-in Emacs themes:: Enable and load -* The require-theme for built-in Emacs themes:: -* Sample configuration:: -* Differences between loading and enabling:: +* Difference between loading and enabling:: Customization options @@ -275,11 +273,11 @@ Main themes Tinted themes ‘modus-operandi-tinted’ and ‘modus-vivendi-tinted’ are variants of - the two main themes. They slightly tone down the intensity of the - background and provide a bit more color variety. - ‘modus-operandi-tinted’ has a set of base tones that are shades of - light ochre (earthly colors), while ‘modus-vivendi-tinted’ gives a - night sky impression. + the two main themes. They tone down the intensity of the + background and rely on a marginally altered palette for stylistic + harmony. ‘modus-operandi-tinted’ has a set of base tones that are + shades of light ochre (earthly colors), while + ‘modus-vivendi-tinted’ gives a night sky impression. Deuteranopia themes ‘modus-operandi-deuteranopia’ and its companion @@ -287,8 +285,8 @@ Deuteranopia themes color deficiency. This means that they do not use red and green hues for color-coding purposes, such as for diff removed and added lines. Instead, they implement colors that are discernible by - users with deueteranopia or deuteranomaly (mostly yellow and blue - hues). + users with deueteranopia or deuteranomaly (those colors are mostly + shades of yellow and blue). Tritanopia themes ‘modus-operandi-tritanopia’ and its counterpart @@ -303,10 +301,10 @@ themes strive to achieve as close to full face coverage as possible, while still targeting a curated list of well-maintained packages (*note Face coverage: Face coverage.). - The overarching objective of this project is to always offer + The overarching objective of this project is to consistently offer accessible color combinations. There shall never be a compromise on this principle. If there arises an inescapable trade-off between -usability and stylistic considerations, we will always opt for the +usability and stylistic considerations, I will always opt for the former. Starting with version 0.12.0 and onwards, the themes are built into @@ -336,43 +334,40 @@ File: modus-themes.info, Node: Learn about the latest changes, Prev: How do th Please refer to the web page with the change log (https://protesilaos.com/emacs/modus-themes-changelog). It is -comprehensive and covers everything that goes into every tagged release +comprehensive and covers everything that goes into each tagged release of the themes. -File: modus-themes.info, Node: Installation, Next: Enable and load, Prev: Overview, Up: Top +File: modus-themes.info, Node: Installation, Next: Sample configuration, Prev: Overview, Up: Top 2 Installation ************** The Modus themes are distributed with Emacs starting with version 28.1. -On Emacs 27, they can be installed using Emacs' package manager or -manually from their code repository. There also exist packages for -distributions of GNU/Linux. +They are also available as a standalone package. Emacs 28 ships with ‘modus-themes’ version ‘1.6.0’. Emacs 29 -includes version ‘3.0.0’. Emacs 30 provides a newer, refactored version -that thoroughly refashions how the themes are implemented and -customized. Such major versions are not backward-compatible due to the -limited resources at the maintainer's disposal to support multiple -versions of Emacs and of the themes across the years. +includes version ‘3.0.0’. Emacs 30 provides version ‘4.4.0’, while +Emacs 31 has version ‘5.2.0’ (soon to be updated to 5.3.0-dev). * Menu: * Install manually from source:: -* Install from the archives:: -* Install on GNU/Linux:: +* Install from source with package-vc-install:: +* Install from GNU ELPA:: * Dealing with byte compilation errors:: -File: modus-themes.info, Node: Install manually from source, Next: Install from the archives, Up: Installation +File: modus-themes.info, Node: Install manually from source, Next: Install from source with package-vc-install, Up: Installation 2.1 Install manually from source ================================ -In the following example, we are assuming that your Emacs files are -stored in ‘~/.emacs.d’ and that you want to place the Modus themes in -‘~/.emacs.d/modus-themes’. +In the following example, I am assuming that your Emacs files are stored +in ‘~/.emacs.d’ and that you want to place the Modus themes in +‘~/.emacs.d/modus-themes’. If you are using Emacs 29, you do not need +to do this manually (*note Install from source with +‘package-vc-install’: Install from source with package-vc-install.). 1. Get the source and store it in the desired path by running the following in the command line shell: @@ -388,73 +383,42 @@ stored in ‘~/.emacs.d’ and that you want to place the Modus themes in and load. -File: modus-themes.info, Node: Install from the archives, Next: Install on GNU/Linux, Prev: Install manually from source, Up: Installation - -2.2 Install from the archives -============================= - -The ‘modus-themes’ package is available from the GNU ELPA archive, which -is configured by default. - - Prior to querying any package archive, make sure to update the index, -with ‘M-x package-refresh-contents’. Then all you need to do is type -‘M-x package-install’ and specify the ‘modus-themes’. - - Once installed, the themes are ready to be used: *note Enable and -load: Enable and load. - - -File: modus-themes.info, Node: Install on GNU/Linux, Next: Dealing with byte compilation errors, Prev: Install from the archives, Up: Installation - -2.3 Install on GNU/Linux -======================== - -The themes are also available from the archives of some distributions of -GNU/Linux. These should correspond to a tagged release rather than -building directly from the latest Git commit. It all depends on the -distro's packaging policies. - -* Menu: - -* Debian 11 Bullseye:: -* GNU Guix:: - - -File: modus-themes.info, Node: Debian 11 Bullseye, Next: GNU Guix, Up: Install on GNU/Linux +File: modus-themes.info, Node: Install from source with package-vc-install, Next: Install from GNU ELPA, Prev: Install manually from source, Up: Installation -2.3.1 Debian 11 Bullseye ------------------------- - -The themes are part of Debian 11 Bullseye. Get them with: - - sudo apt install elpa-modus-themes +2.2 Install from source with ‘package-vc-install’ +================================================= - They are now ready to be used: *note Enable and load: Enable and -load. +Starting with Emacs version 29, you can install the ‘modus-themes’ +directly from source with the function ‘package-vc-install’: - NOTE that Debian's package is severely out-of-date as of this writing -2022-07-24 09:57 +0300. + ;; Install from source. Do not do it if the package is already installed. + ;; + ;; To upgrade packages installed with `package-vc-install', use the + ;; commands `package-vc-upgrade' or `package-vc-upgrade-all'. + (unless (package-installed-p 'modus-themes) + (package-vc-install "https://github.com/protesilaos/modus-themes.git")) -File: modus-themes.info, Node: GNU Guix, Prev: Debian 11 Bullseye, Up: Install on GNU/Linux +File: modus-themes.info, Node: Install from GNU ELPA, Next: Dealing with byte compilation errors, Prev: Install from source with package-vc-install, Up: Installation -2.3.2 GNU Guix --------------- +2.3 Install from GNU ELPA +========================= -Users of Guix can get the themes with this command: +The ‘modus-themes’ package is available from the official GNU ELPA +archive. Prior to querying any package archive, make sure to update the +index, with ‘M-x package-refresh-contents’. Then all you need to do is +type ‘M-x package-install’ and specify the ‘modus-themes’ at the prompt. - guix package -i emacs-modus-themes - - They are now ready to be used: *note Enable and load: Enable and -load. + Once installed, the themes are ready for use: *note Enable and load: +Enable and load. -File: modus-themes.info, Node: Dealing with byte compilation errors, Prev: Install on GNU/Linux, Up: Installation +File: modus-themes.info, Node: Dealing with byte compilation errors, Prev: Install from GNU ELPA, Up: Installation 2.4 Dealing with byte compilation errors ======================================== -From time to time, we receive bug reports pertaining to errors with byte +From time to time, I receive bug reports pertaining to errors with byte compilation. These seldom have to do with faulty code in the themes: it might be a shortcoming of ‘package.el’, some regression in the current development target of Emacs, a misconfiguration in an otherwise exotic @@ -469,280 +433,190 @@ setup, and the like. For those building Emacs directly from source, the solution may involve reverting to an earlier commit in emacs.git. - At any rate, if you encounter such an issue please report it: we will -either fix the bug on our end if it is truly ours, or help forward it to -the relevant upstream maintainer. Whatever you do, please understand -that a build failure does not mean we are necessarily doing something -wrong. + At any rate, if you encounter such an issue please report it: I will +either fix the bug or help forward it to the relevant upstream +maintainer. Whatever you do, please understand that a build failure +does not mean I am necessarily doing something wrong. *note Issues you can help with: Issues you can help with. -File: modus-themes.info, Node: Enable and load, Next: Customization options, Prev: Installation, Up: Top - -3 Enable and load -***************** - -NOTE that Emacs can load multiple themes, which typically produces -undesirable results and undoes the work of the designer. Use the -‘disable-theme’ command if you are trying other themes beside the Modus -collection (*note Option for disabling other themes while loading Modus: -Disable other themes.). - - Users of the built-in themes cannot ‘require’ the package as usual -because there is no package to speak of. Instead, things are simpler as -built-in themes are considered safe. All one needs is to load the theme -of their preference by adding either form to their init file: - - (load-theme 'modus-operandi) ; Light theme - (load-theme 'modus-vivendi) ; Dark theme - - Remember that there are multiple Modus themes (*note Overview: -Overview.). Adapt the above snippet accordingly. - - Users of packaged variants of the themes must add a few more lines to -ensure that everything works as intended. First, one has to require the -main library before loading one of the themes: - - (require 'modus-themes) - - One can activate a theme with something like the following -expression, replacing ‘modus-operandi’ with their preferred Modus theme: - - (load-theme 'modus-operandi :no-confirm) - - Changes to the available customization options must always be -evaluated before loading a theme (*note Customization Options: -Customization options.). Reload a theme for new changes to take effect. - - This is how a basic setup could look like (*note The require-theme -for built-in Emacs themes: The require-theme for built-in Emacs -themes.): - - ;;; For the built-in themes which cannot use `require'. - (require-theme 'modus-themes) +File: modus-themes.info, Node: Sample configuration, Next: Enable and load, Prev: Installation, Up: Top - ;; Add all your customizations prior to loading the themes. - (setq modus-themes-italic-constructs t - modus-themes-bold-constructs nil) +3 Sample configuration +********************** - ;; Load the theme of your choice. - (load-theme 'modus-operandi) +It is common for Emacs users to rely on ‘use-package’ for declaring +package configurations in their setup (*note The ‘require-theme’ for +built-in Emacs themes: The require-theme for built-in Emacs themes.): - ;; Optionally define a key to switch between Modus themes. Also check - ;; the user option `modus-themes-to-toggle'. - (define-key global-map (kbd "<f5>") #'modus-themes-toggle) + (use-package modus-themes + :ensure t + :config + ;; Your customizations here. All customizations must be evaluated + ;; BEFORE loading the theme. Reload the theme for new customizations + ;; to take effect. + (setq modus-themes-italic-constructs t + modus-themes-bold-constructs nil) + (modus-themes-load-theme 'modus-operandi) + (define-key global-map (kbd "<f5>") #'modus-themes-toggle)) - ;;; For packaged versions which must use `require'. + The same without ‘use-package’: (require 'modus-themes) - ;; Add all your customizations prior to loading the themes + ;; Your customizations here. All customizations must be evaluated + ;; BEFORE loading the theme. Reload the theme for new customizations + ;; to take effect. (setq modus-themes-italic-constructs t modus-themes-bold-constructs nil) - ;; Load the theme of your choice. - (load-theme 'modus-operandi :no-confirm) - - (define-key global-map (kbd "<f5>") #'modus-themes-toggle) - - *note Sample configuration with and without use-package: Sample -configuration. - - To disable other themes before loading a Modus theme, use something -like this: - - (mapc #'disable-theme custom-enabled-themes) - (load-theme 'modus-operandi :no-confirm) - - Instead of using the basic ‘load-theme’ function, users can rely on -the ‘modus-themes-load-theme’. It accepts a single argument, which is a -symbol representing the Modus theme of choice, such as: - (modus-themes-load-theme 'modus-operandi) - The ‘modus-themes-load-theme’ takes care to disable other themes, if -the user opts in (*note Option for disabling other themes while loading -Modus: Disable other themes.). After loading the theme of choice, this -function calls the hook ‘modus-themes-after-load-theme-hook’ (alias -‘modus-themes-post-load-hook’). Users can add their own functions to -this hook to make further customizations (*note Advanced customization: -Advanced customization.). - - The commands ‘modus-themes-toggle’, ‘modus-themes-rotate’, -‘modus-themes-load-random’, and ‘modus-themes-select’ use -‘modus-themes-load-theme’ internally (*note Option for which themes to -toggle: Option for which themes to toggle.). The aforementioned hold -true for them as well. - - Convenience commands for loading only dark or light themes are: - - • ‘modus-themes-select-dark’ - - • ‘modus-themes-select-light’ + (define-key global-map (kbd "<f5>") #'modus-themes-toggle) - • ‘modus-themes-load-random-dark’ + *note Difference between loading and enabling: Difference between +loading and enabling. - • ‘modus-themes-load-random-light’ + Note: make sure not to customize the variable +‘custom-theme-load-path’ or ‘custom-theme-directory’ after the themes' +package declaration. That will lead to failures in loading the files. +If either or both of those variables need to be changed, their values +should be defined before the package declaration of the themes. * Menu: * The require-theme for built-in Emacs themes:: -* Sample configuration:: -* Differences between loading and enabling:: -File: modus-themes.info, Node: The require-theme for built-in Emacs themes, Next: Sample configuration, Up: Enable and load +File: modus-themes.info, Node: The require-theme for built-in Emacs themes, Up: Sample configuration 3.1 The ‘require-theme’ for built-in Emacs themes ================================================= The version of the Modus themes that is included in Emacs CANNOT use the -standard ‘require’. This is because the built-in themes are not -included in the ‘load-path’ (not my decision). The ‘require-theme’ -function must be used in this case as a replacement. For example: +standard ‘require’ that ‘use-package’ calls internally. This is because +the built-in themes are not included in the ‘load-path’ (not my +decision). The ‘require-theme’ function must be used instead. For +example: (require-theme 'modus-themes) - ;; All customizations here + ;; Your customizations here. All customizations must be evaluated + ;; BEFORE loading the theme. Reload the theme for new customizations + ;; to take effect. (setq modus-themes-bold-constructs t modus-themes-italic-constructs t) - ;; Load the theme of choice (built-in themes are always "safe" so they - ;; do not need the `no-require' argument of `load-theme'). - (load-theme 'modus-operandi) + (modus-themes-load-theme 'modus-operandi) (define-key global-map (kbd "<f5>") #'modus-themes-toggle) - -File: modus-themes.info, Node: Sample configuration, Next: Differences between loading and enabling, Prev: The require-theme for built-in Emacs themes, Up: Enable and load - -3.2 Sample configuration -======================== - -What follows is a variant of what we demonstrate in the previous section -(*note Enable and load: Enable and load.). - - It is common for Emacs users to rely on ‘use-package’ for declaring -package configurations in their setup. We use this as an example: + Same principle but with ‘use-package’: - ;;; For the built-in themes which cannot use `require'. (use-package emacs :init - (require-theme 'modus-themes) ; `require-theme' is ONLY for the built-in Modus themes + ;; `require-theme' is ONLY for the built-in Modus themes + (require-theme 'modus-themes) :config - ;; Your customizations here. All customizations must evaluated - ;; BEFORE loading the theme. + ;; Your customizations here. All customizations must be evaluated + ;; BEFORE loading the theme. Reload the theme for new customizations + ;; to take effect. (setq modus-themes-italic-constructs t modus-themes-bold-constructs nil) - ;; Load the theme of your choice. (modus-themes-load-theme 'modus-operandi) (define-key global-map (kbd "<f5>") #'modus-themes-toggle)) + +File: modus-themes.info, Node: Enable and load, Next: Customization options, Prev: Sample configuration, Up: Top +4 Enable and load +***************** - ;;; For packaged versions which must use `require'. - (use-package modus-themes - :ensure t - :config - ;; Your customizations here. All customizations must evaluated - ;; BEFORE loading the theme. - (setq modus-themes-italic-constructs t - modus-themes-bold-constructs nil) - - ;; Load the theme of your choice. - (modus-themes-load-theme 'modus-operandi) - - (define-key global-map (kbd "<f5>") #'modus-themes-toggle)) +Emacs provides the generic ‘load-theme’ function to load the given +theme. Modus themes work with it as expected. Though I also define the +function ‘modus-themes-load-theme’ which (i) calls the +‘modus-themes-after-load-theme-hook’ (alias +‘modus-themes-post-load-hook’) and (ii) disables all other color themes +if the relevant user option is enabled (*note Option to disable other +color themes when loading a Modus theme: Disable other themes.). - The same without ‘use-package’: + The ‘modus-themes-after-load-theme-hook’ is specific to the Modus +themes. As such, users can rely on it to work as expected with the +functions and macros that Modus defines (*note Advanced customization: +Advanced customization.). - (require 'modus-themes) ; OR for the built-in themes: (require-theme 'modus-themes) + The commands ‘modus-themes-toggle’, ‘modus-themes-rotate’, +‘modus-themes-load-random’, and ‘modus-themes-select’ use +‘modus-themes-load-theme’ internally: - ;; Your customizations here. All customizations must evaluated - ;; BEFORE loading the theme. - (setq modus-themes-italic-constructs t - modus-themes-bold-constructs nil) +‘modus-themes-toggle’ + Switches between two predefined Modus themes (*note Option for + which themes to toggle: Option for which themes to toggle.). - ;; Load the theme of your choice: - (modus-themes-load-theme 'modus-operandi :no-confirm) +‘modus-themes-rotate’ + Cycles through a list of Modus themes in rotation from left to + right (*note Option for which themes to rotate: Option for which + themes to rotate.). - (define-key global-map (kbd "<f5>") #'modus-themes-toggle) +‘modus-themes-select’ + Selects a Modus theme using the minibuffer. When called with a + prefix argument (‘C-u’ by default), it first prompts for a light or + dark subset and then loads a theme accordingly. - *note Differences between loading and enabling: Differences between -loading and enabling. +‘modus-themes-load-random’ + Loads a Modus theme at random. When called with a prefix argument, + it behaves like the aforementioned ‘modus-themes-select’. - Note: make sure not to customize the variable -‘custom-theme-load-path’ or ‘custom-theme-directory’ after the themes' -package declaration. That will lead to failures in loading the files. -If either or both of those variables need to be changed, their values -should be defined before the package declaration of the themes. + Convenience commands for loading only dark or light themes are: - -File: modus-themes.info, Node: Differences between loading and enabling, Prev: Sample configuration, Up: Enable and load + • ‘modus-themes-select-dark’ -3.3 Differences between loading and enabling -============================================ + • ‘modus-themes-select-light’ -The reason we recommend ‘load-theme’ instead of the other option of -‘enable-theme’ is that the former does a kind of "reset" on the face -specs. It quite literally loads (or reloads) the theme. Whereas the -‘enable-theme’ function simply puts an already loaded theme to the top -of the list of enabled items, reusing whatever state was last loaded. + • ‘modus-themes-load-random-dark’ - As such, ‘load-theme’ reads all customizations that may happen during -any given Emacs session: even after the initial setup of a theme. -Examples are calls to ‘custom-set-faces’, as well as new values assigned -to the options the Modus themes provide (*note Customization Options: -Customization options.). + • ‘modus-themes-load-random-light’ - Our tests show that ‘enable-theme’ does not read such variables anew, -so it might appear to the unsuspecting user that the themes are somehow -broken whenever they try to assign a new value to a customization option -or some face. +* Menu: - This "reset" that ‘load-theme’ brings about does, however, come at -the cost of being somewhat slower than ‘enable-theme’. Users who have a -stable setup and who seldom update their variables during a given Emacs -session, are better off using something like this: +* Difference between loading and enabling:: - (require 'modus-themes) + +File: modus-themes.info, Node: Difference between loading and enabling, Up: Enable and load - ;; Activate your desired themes here - (load-theme 'modus-operandi t t) - (load-theme 'modus-vivendi t t) +4.1 Difference between loading and enabling +=========================================== - ;; Enable the preferred one - (enable-theme 'modus-operandi) +Emacs differentiates between loading and enabling a theme. The former +refers to the process of loading and evaluating the theme. While the +latter is about moving the given theme to the front of the +‘custom-enabled-themes’. Concretely, loading a theme always aaccounts +for the user options and updates the presentation accordingly (*note +Customization Options: Customization options.). Whereas enabling a +theme will not perform any further computations. *note Toggle themes without reloading them: DIY Toggle themes without reloading them. *note Sample configuration: Sample configuration. - With the above granted, other sections of the manual discuss how to -configure custom faces, where ‘load-theme’ is expected, though -‘enable-theme’ could still apply in stable setups: - - *note Use theme colors in code with modus-themes-with-colors: Use -theme colors in code with modus-themes-with-colors. - File: modus-themes.info, Node: Customization options, Next: Preview theme colors, Prev: Enable and load, Up: Top -4 Customization options +5 Customization options *********************** The Modus themes are highly configurable, though they should work well -without any further tweaks. We provide a variety of user options. The +without any further tweaks. I provide a variety of user options. The following code block provides an overview. In addition to those variables, the themes support a comprehensive system of overrides: it can be used to make thoroughgoing changes to the looks of the themes -(*note Option for palette overrides: Palette overrides.). We document +(*note Option for palette overrides: Palette overrides.). I document everything at length in the pages of this manual and also provide ready-to-use code samples. @@ -788,7 +662,7 @@ is already active, it must be reloaded for changes to take effect. (agenda-structure . (variable-pitch light 1.8)) (t . (1.1)))) - ;; Remember that more (MUCH MORE) can be done with overrides, which we + ;; Remember that more (MUCH MORE) can be done with overrides, which I ;; document extensively in this manual. * Menu: @@ -810,10 +684,10 @@ is already active, it must be reloaded for changes to take effect. File: modus-themes.info, Node: Disable other themes, Next: Bold constructs, Up: Customization options -4.1 Option to disable other themes when loading a Modus theme -============================================================= +5.1 Option to disable other color themes when loading a Modus theme +=================================================================== -Brief: Disable all other themes when loading a Modus theme. +Brief: Disable all other color themes when loading a Modus theme. Symbol: ‘modus-themes-disable-other-themes’ (‘boolean’ type) @@ -843,7 +717,7 @@ variable to a ‘nil’ value. File: modus-themes.info, Node: Bold constructs, Next: Italic constructs, Prev: Disable other themes, Up: Customization options -4.2 Option for more bold constructs +5.2 Option for more bold constructs =================================== Brief: Use bold for code syntax highlighting and related. @@ -872,7 +746,7 @@ faces. File: modus-themes.info, Node: Italic constructs, Next: Option for which themes to toggle, Prev: Bold constructs, Up: Customization options -4.3 Option for more italic constructs +5.3 Option for more italic constructs ===================================== Brief: Use italics for code syntax highlighting and related. @@ -899,7 +773,7 @@ faces. File: modus-themes.info, Node: Option for which themes to toggle, Next: Option for which themes to rotate, Prev: Italic constructs, Up: Customization options -4.4 Option for which themes to toggle +5.4 Option for which themes to toggle ===================================== Brief: Specify which two themes to toggle between when using the command @@ -909,21 +783,13 @@ Brief: Specify which two themes to toggle between when using the command Default value: ‘'(modus-operandi modus-vivendi)’ - Possible values: - - • ‘modus-operandi’ - • ‘modus-operandi-tinted’ - • ‘modus-operandi-deuteranopia’ - • ‘modus-operandi-tritanopia’ - • ‘modus-vivendi’ - • ‘modus-vivendi-tinted’ - • ‘modus-vivendi-deuteranopia’ - • ‘modus-vivendi-tritanopia’ + Possible values include all themes returned by the function +‘modus-themes-get-themes’. File: modus-themes.info, Node: Option for which themes to rotate, Next: Mixed fonts, Prev: Option for which themes to toggle, Up: Customization options -4.5 Option for which themes to rotate +5.5 Option for which themes to rotate ===================================== Brief: Specify which themes to rotate through when using the command @@ -950,7 +816,7 @@ function ‘modus-themes-get-themes’. File: modus-themes.info, Node: Mixed fonts, Next: Command prompts, Prev: Option for which themes to rotate, Up: Customization options -4.6 Option for font mixing +5.6 Option for font mixing ========================== Brief: Toggle the use of monospaced fonts for spacing-sensitive @@ -979,7 +845,7 @@ for Org and others. File: modus-themes.info, Node: Command prompts, Next: Completion UIs, Prev: Mixed fonts, Up: Customization options -4.7 Option for command prompt styles +5.7 Option for command prompt styles ==================================== Brief: Control the style of command prompts (e.g. minibuffer, shell, @@ -1036,7 +902,7 @@ less colorful. File: modus-themes.info, Node: Completion UIs, Next: Org mode blocks, Prev: Command prompts, Up: Customization options -4.8 Option for completion framework aesthetics +5.8 Option for completion framework aesthetics ============================================== Brief: Set the overall style of completion framework interfaces. @@ -1102,7 +968,7 @@ completion matches more or less colorful. File: modus-themes.info, Node: Org mode blocks, Next: Heading styles, Prev: Completion UIs, Up: Customization options -4.9 Option for org-mode block styles +5.9 Option for org-mode block styles ==================================== As part of version ‘4.4.0’, the ‘modus-themes-org-blocks’ is no more. @@ -1111,14 +977,14 @@ preference (purple, blue, yellow, green, etc.). It is more flexible and more powerful (*note DIY Make Org block colors more or less colorful: DIY Make Org block colors more or less colorful.) - For the option to change the background of Org source blocks, we + For the option to change the background of Org source blocks, I provide the relevant setup (*note DIY Use colored Org source blocks per language: DIY Use colored Org source blocks per language.). File: modus-themes.info, Node: Heading styles, Next: UI typeface, Prev: Org mode blocks, Up: Customization options -4.10 Option for the headings' overall style +5.10 Option for the headings' overall style =========================================== Brief: Heading styles with optional list of values per heading level. @@ -1131,7 +997,7 @@ through 8) or ‘t’, which pertains to the fallback style. The named keys ‘agenda-date’ and ‘agenda-structure’ apply to the Org agenda. Level 0 is a special heading: it is used for what counts as a -document title or equivalent, such as the ‘#+title’ construct we find in +document title or equivalent, such as the ‘#+title’ construct I find in Org files. Levels 1-8 are regular headings. The ‘LIST-OF-VALUES’ covers symbols that refer to properties, as @@ -1231,7 +1097,7 @@ less colorful. File: modus-themes.info, Node: UI typeface, Next: Palette overrides, Prev: Heading styles, Up: Customization options -4.11 Option for variable-pitch font in UI elements +5.11 Option for variable-pitch font in UI elements ================================================== Brief: Toggle the use of proportionately spaced (‘variable-pitch’) fonts @@ -1261,11 +1127,11 @@ for Org and others. File: modus-themes.info, Node: Palette overrides, Next: Palette extension, Prev: UI typeface, Up: Customization options -4.12 Option for palette overrides +5.12 Option for palette overrides ================================= This section describes palette overrides in detail. For a simpler -alternative, use the presets we provide (*note Palette override presets: +alternative, use the presets I provide (*note Palette override presets: DIY Palette override presets.). Each Modus theme specifies a color palette that declares named color @@ -1380,7 +1246,7 @@ watch: File: modus-themes.info, Node: Palette extension, Prev: Palette overrides, Up: Customization options -4.13 Option to extend the palette +5.13 Option to extend the palette ================================= It is possible to extend the palette of each theme. For example, the @@ -1394,7 +1260,7 @@ leverages either the ‘modus-themes-with-colors’ macro or the function definitions that are shared among the themes or on a per-theme basis. The common values are stored in the user option -‘modus-themes-common-palette-user’. As for per-theme variables, we have +‘modus-themes-common-palette-user’. As for per-theme variables, I have the following user options: • ‘modus-operandi-palette-user’ @@ -1455,7 +1321,7 @@ the following user options: File: modus-themes.info, Node: Preview theme colors, Next: Use colors from the Modus themes palette, Prev: Customization options, Up: Top -5 Preview theme colors +6 Preview theme colors ********************** The command ‘modus-themes-list-colors’ uses minibuffer completion to @@ -1493,7 +1359,7 @@ the palette (named colors as well as semantic color mappings) and File: modus-themes.info, Node: Commands for the preview palette buffer, Up: Preview theme colors -5.1 Commands for the preview palette buffer +6.1 Commands for the preview palette buffer =========================================== The palette preview buffer uses the major mode @@ -1534,7 +1400,7 @@ aforementioned commands for copying colors and palette entries. File: modus-themes.info, Node: Use colors from the Modus themes palette, Next: Advanced customization, Prev: Preview theme colors, Up: Top -6 Use colors from the Modus themes palette +7 Use colors from the Modus themes palette ****************************************** The Modus themes provide the means to access the palette of (i) the @@ -1559,7 +1425,7 @@ Macro File: modus-themes.info, Node: Get a single color from the palette with modus-themes-get-color-value, Next: Use theme colors in code with modus-themes-with-colors, Up: Use colors from the Modus themes palette -6.1 Get a single color from the palette with ‘modus-themes-get-color-value’ +7.1 Get a single color from the palette with ‘modus-themes-get-color-value’ =========================================================================== The function ‘modus-themes-get-color-value’ can be called from Lisp to @@ -1589,7 +1455,7 @@ value. An example with ‘modus-operandi’ to show how this function behaves with/without overrides and when recursive mappings are introduced. - ;; Here we show the recursion of palette mappings. In general, it is + ;; Here I show the recursion of palette mappings. In general, it is ;; better for the user to specify named colors to avoid possible ;; confusion with their configuration, though those still work as ;; expected. @@ -1610,11 +1476,11 @@ with/without overrides and when recursive mappings are introduced. File: modus-themes.info, Node: Use theme colors in code with modus-themes-with-colors, Prev: Get a single color from the palette with modus-themes-get-color-value, Up: Use colors from the Modus themes palette -6.2 Use theme colors in code with ‘modus-themes-with-colors’ +7.2 Use theme colors in code with ‘modus-themes-with-colors’ ============================================================ [ Note that for common cases the following is not not needed. Just rely -on the comprehensive overrides we provide (*note Option for palette +on the comprehensive overrides I provide (*note Option for palette overrides: Palette overrides.). ] Advanced users may want to apply many colors from the palette of the @@ -1642,7 +1508,7 @@ Overview.)). The same with ‘modus-vivendi’ as the active theme: The ‘modus-themes-with-colors’ has access to the whole palette of the active theme, meaning that it can instantiate both (i) named colors like -‘blue-warmer’ and (ii) semantic color mappings like ‘warning’. We +‘blue-warmer’ and (ii) semantic color mappings like ‘warning’. I provide commands to inspect those (*note Preview theme colors: Preview theme colors.). @@ -1655,7 +1521,7 @@ phase.). File: modus-themes.info, Node: Advanced customization, Next: Build on top of the Modus themes, Prev: Use colors from the Modus themes palette, Up: Top -7 Advanced customization +8 Advanced customization ************************ Unlike the predefined customization options which follow a clear pattern @@ -1700,11 +1566,11 @@ such, they are labeled as "do-it-yourself" or "DIY". File: modus-themes.info, Node: DIY Palette override presets, Next: DIY Add support for vc-annotate, Up: Advanced customization -7.1 DIY Palette override presets +8.1 DIY Palette override presets ================================ This section shows how to refashion the themes by opting in to the -stylistic presets we provide. Those presets override the default color +stylistic presets I provide. Those presets override the default color mappings to amplify, tone down, or refashion the overall coloration of the themes. @@ -1717,7 +1583,7 @@ the themes. gray backgrounds are removed from some contexts, and almost all accent colors are desaturated. It makes the themes less attention-grabbing. - On the opposite end of the stylistic spectrum, we have this + On the opposite end of the stylistic spectrum, I have this ;; Always remember to reload the theme for changes to take effect! (setq modus-themes-common-palette-overrides modus-themes-preset-overrides-intense) @@ -1735,7 +1601,7 @@ places. Colors stand out more and are made easier to spot. (setq modus-themes-common-palette-overrides modus-themes-preset-overrides-warmer) Note that the user is not limited to those presets. The system of -overrides we provide makes it possible to tweak the value of each +overrides I provide makes it possible to tweak the value of each individual named color and to change how values are assigned to semantic color mappings (*note Option for palette overrides: Palette overrides.). Subsequent sections provide examples (*note Stylistic variants using @@ -1756,14 +1622,14 @@ the general idea (extra space for didactic purposes): (underline-paren-match fg-main) ;; And expand the preset here. Note that the ,@ works because - ;; we use the backtick for this list, instead of a straight + ;; I use the backtick for this list, instead of a straight ;; quote. ,@modus-themes-preset-overrides-intense)) File: modus-themes.info, Node: DIY Add support for vc-annotate, Next: DIY Add support for engrave-faces, Prev: DIY Palette override presets, Up: Advanced customization -7.2 DIY Add support for ‘vc-annotate’ +8.2 DIY Add support for ‘vc-annotate’ ===================================== The built-in ‘vc-annotate’ command relies on a user option to read color @@ -1802,16 +1668,16 @@ the post-load-theme phase.): File: modus-themes.info, Node: DIY Add support for engrave-faces, Next: DIY Stylistic variants using palette overrides, Prev: DIY Add support for vc-annotate, Up: Advanced customization -7.3 DIY Add support for ‘engrave-faces’ +8.3 DIY Add support for ‘engrave-faces’ ======================================= The ‘engraved-faces’ package is used as part of an Org export process to produce decent colors in the output. Its default style though requires changes to use the colors of the active Modus theme. - In the code below we show how to map everything that ‘engrave-faces’ + In the code below I show how to map everything that ‘engrave-faces’ defines to the corresponding entry in the palette of the active Modus -theme. We then use a hook to ensure that the value is updated after we +theme. I then use a hook to ensure that the value is updated after I switch to another theme in the collection (*note DIY Use a hook at the post-load-theme phase: DIY Use a hook at the post-load-theme phase.). @@ -1897,7 +1763,7 @@ post-load-theme phase: DIY Use a hook at the post-load-theme phase.). File: modus-themes.info, Node: DIY Stylistic variants using palette overrides, Next: DIY More accurate colors in terminal emulators, Prev: DIY Add support for engrave-faces, Up: Advanced customization -7.4 DIY Stylistic variants using palette overrides +8.4 DIY Stylistic variants using palette overrides ================================================== This section contains practical examples of overriding the palette of @@ -1905,7 +1771,7 @@ the themes (*note Option for palette overrides: Palette overrides.). Users can copy the code to their init file, evaluate it, and then re-load the theme for changes to take effect. To apply overrides at startup simply define them before the call that loads the theme. -Remember that we also provide presets that are easier to apply (*note +Remember that I also provide presets that are easier to apply (*note Palette override presets: DIY Palette override presets.). * Menu: @@ -1938,14 +1804,14 @@ Palette override presets: DIY Palette override presets.). File: modus-themes.info, Node: DIY Make the mode line borderless, Next: DIY Make the active mode line colorful, Up: DIY Stylistic variants using palette overrides -7.4.1 DIY Make the mode line borderless +8.4.1 DIY Make the mode line borderless --------------------------------------- -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY Stylistic variants using palette overrides.). To hide the border around -the active and inactive mode lines, we need to set their color to that -of the underlying background. +the active and inactive mode lines, I need to set their color to that of +the underlying background. *note Make the active mode line colorful: DIY Make the active mode line colorful. @@ -1970,15 +1836,15 @@ line colorful. File: modus-themes.info, Node: DIY Make the active mode line colorful, Next: DIY Make the tab bar more or less colorful, Prev: DIY Make the mode line borderless, Up: DIY Stylistic variants using palette overrides -7.4.2 DIY Make the active mode line colorful +8.4.2 DIY Make the active mode line colorful -------------------------------------------- -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY -Stylistic variants using palette overrides.). Here we show some -snippets that apply different stylistic variants. Of course, it is -possible to use theme-specific overrides to, say, have a blue mode line -for ‘modus-operandi’ and a red one for ‘modus-vivendi’. +Stylistic variants using palette overrides.). Here I show some snippets +that apply different stylistic variants. Of course, it is possible to +use theme-specific overrides to, say, have a blue mode line for +‘modus-operandi’ and a red one for ‘modus-vivendi’. *note Make the mode line borderless: DIY Make the mode line borderless. @@ -2020,13 +1886,13 @@ borderless. File: modus-themes.info, Node: DIY Make the tab bar more or less colorful, Next: DIY Make the fringe invisible or another color, Prev: DIY Make the active mode line colorful, Up: DIY Stylistic variants using palette overrides -7.4.3 DIY Make the tab bar more or less colorful +8.4.3 DIY Make the tab bar more or less colorful ------------------------------------------------ -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY -Stylistic variants using palette overrides.). Here we show how to -affect the colors of the built-in ‘tab-bar-mode’ and ‘tab-line-mode’. +Stylistic variants using palette overrides.). Here I show how to affect +the colors of the built-in ‘tab-bar-mode’ and ‘tab-line-mode’. For consistent theme-wide results, consider changing the mode line, fringes, and line numbers. These are shown in other sections of this @@ -2064,12 +1930,12 @@ manual. File: modus-themes.info, Node: DIY Make the fringe invisible or another color, Next: DIY Make links use subtle or no underlines, Prev: DIY Make the tab bar more or less colorful, Up: DIY Stylistic variants using palette overrides -7.4.4 DIY Make the fringe invisible or another color +8.4.4 DIY Make the fringe invisible or another color ---------------------------------------------------- -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY -Stylistic variants using palette overrides.). Here we show how to make +Stylistic variants using palette overrides.). Here I show how to make the fringe invisible or how to assign to it a different color. The "fringe" is a small area to the right and left side of the Emacs window which shows indicators such as for truncation or continuation lines. @@ -2091,12 +1957,12 @@ which shows indicators such as for truncation or continuation lines. File: modus-themes.info, Node: DIY Make links use subtle or no underlines, Next: DIY Make prompts more or less colorful, Prev: DIY Make the fringe invisible or another color, Up: DIY Stylistic variants using palette overrides -7.4.5 DIY Make links use subtle or no underlines +8.4.5 DIY Make links use subtle or no underlines ------------------------------------------------ -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY -Stylistic variants using palette overrides.). In this example, we +Stylistic variants using palette overrides.). In this example, I showcase the special use of the ‘unspecified’ symbol that underline mappings can read correctly. @@ -2117,13 +1983,12 @@ mappings can read correctly. File: modus-themes.info, Node: DIY Make prompts more or less colorful, Next: DIY Make completion matches more or less colorful, Prev: DIY Make links use subtle or no underlines, Up: DIY Stylistic variants using palette overrides -7.4.6 DIY Make prompts more or less colorful +8.4.6 DIY Make prompts more or less colorful -------------------------------------------- This section contains practical examples of overriding the palette of the themes (*note Option for palette overrides: Palette overrides.). In -the following code block we show how to add or remove color from -prompts. +the following code block I show how to add or remove color from prompts. *note Option for command prompt styles: Command prompts. @@ -2148,19 +2013,19 @@ prompts. File: modus-themes.info, Node: DIY Make completion matches more or less colorful, Next: DIY Make comments yellow and strings green, Prev: DIY Make prompts more or less colorful, Up: DIY Stylistic variants using palette overrides -7.4.7 DIY Make completion matches more or less colorful +8.4.7 DIY Make completion matches more or less colorful ------------------------------------------------------- This section contains practical examples of overriding the palette of the themes (*note Option for palette overrides: Palette overrides.). -Here we demonstrate how to activate background coloration for completion -matches. We show three different degrees of intensity. +Here I demonstrate how to activate background coloration for completion +matches. I show three different degrees of intensity. *note Option for completion framework aesthetics: Completion UIs. ;; Add a nuanced background color to completion matches, while keeping ;; their foreground intact (foregrounds do not need to be specified in - ;; this case, but we do it for didactic purposes). + ;; this case, but I do it for didactic purposes). (setq modus-themes-common-palette-overrides '((fg-completion-match-0 blue) (fg-completion-match-1 magenta-warmer) @@ -2226,15 +2091,15 @@ colors to two: File: modus-themes.info, Node: DIY Make comments yellow and strings green, Next: DIY Make code syntax use the old alt-syntax style, Prev: DIY Make completion matches more or less colorful, Up: DIY Stylistic variants using palette overrides -7.4.8 DIY Make comments yellow and strings green +8.4.8 DIY Make comments yellow and strings green ------------------------------------------------ -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY Stylistic variants using palette overrides.). In previous versions of -the themes, we provided an option for yellow-ish comments and green-ish +the themes, I provided an option for yellow-ish comments and green-ish strings. For some users, those were still not good enough, as the exact -values were hardcoded. Here we show how to reproduce the effect, but +values were hardcoded. Here I show how to reproduce the effect, but also how to tweak it to one's liking. *note Make code syntax use the old alt-syntax style: DIY Make code @@ -2265,15 +2130,15 @@ alternative styles for code syntax. File: modus-themes.info, Node: DIY Make code syntax use the old alt-syntax style, Next: DIY Make use of alternative styles for code syntax, Prev: DIY Make comments yellow and strings green, Up: DIY Stylistic variants using palette overrides -7.4.9 DIY Make code syntax use the old alt-syntax style +8.4.9 DIY Make code syntax use the old alt-syntax style ------------------------------------------------------- -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY -Stylistic variants using palette overrides.). In this section we show +Stylistic variants using palette overrides.). In this section I show how to reproduce what previous versions of the Modus themes provided as a stylistic alternative for code syntax. The upside of using overrides -for this purpose is that we can tweak the style to our liking, but first +for this purpose is that I can tweak the style to my liking, but first let's start with its recreation: ;; The old "alt-syntax" (before version 4.0.0 of the Modus themes) @@ -2341,10 +2206,10 @@ alternative styles for code syntax. File: modus-themes.info, Node: DIY Make use of alternative styles for code syntax, Next: DIY Make matching parenthesis more or less intense, Prev: DIY Make code syntax use the old alt-syntax style, Up: DIY Stylistic variants using palette overrides -7.4.10 DIY Make use of alternative styles for code syntax +8.4.10 DIY Make use of alternative styles for code syntax --------------------------------------------------------- -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY Stylistic variants using palette overrides.). The idea here is to change how named colors are mapped to code syntax. Each of the @@ -2427,14 +2292,14 @@ syntax use the old alt-syntax style. File: modus-themes.info, Node: DIY Make matching parenthesis more or less intense, Next: DIY Make box buttons more or less gray, Prev: DIY Make use of alternative styles for code syntax, Up: DIY Stylistic variants using palette overrides -7.4.11 DIY Make matching parenthesis more or less intense +8.4.11 DIY Make matching parenthesis more or less intense --------------------------------------------------------- -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY -Stylistic variants using palette overrides.). In this code block we -show how to change the background of matching delimiters when -‘show-paren-mode’ is enabled. We also demonstrate how to enable +Stylistic variants using palette overrides.). In this code block I show +how to change the background of matching delimiters when +‘show-paren-mode’ is enabled. I also demonstrate how to enable underlines for those highlights. ;; Change the background to a shade of magenta @@ -2457,10 +2322,10 @@ underlines for those highlights. File: modus-themes.info, Node: DIY Make box buttons more or less gray, Next: DIY Make TODO and DONE more or less intense, Prev: DIY Make matching parenthesis more or less intense, Up: DIY Stylistic variants using palette overrides -7.4.12 DIY Make box buttons more or less gray +8.4.12 DIY Make box buttons more or less gray --------------------------------------------- -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY Stylistic variants using palette overrides.). By default, the boxed buttons that appear in ‘M-x customize’ and related are distinct shades @@ -2478,14 +2343,14 @@ active buttons and amplifies it for the inactive ones. File: modus-themes.info, Node: DIY Make TODO and DONE more or less intense, Next: DIY Make headings more or less colorful, Prev: DIY Make box buttons more or less gray, Up: DIY Stylistic variants using palette overrides -7.4.13 DIY Make TODO and DONE more or less intense +8.4.13 DIY Make TODO and DONE more or less intense -------------------------------------------------- -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY -Stylistic variants using palette overrides.). Here we show how to -affect just the ‘TODO’ and ‘DONE’ keywords that we encounter in Org -buffers. The idea is to make those pop out more or to subdue them. +Stylistic variants using palette overrides.). Here I show how to affect +just the ‘TODO’ and ‘DONE’ keywords that I encounter in Org buffers. +The idea is to make those pop out more or to subdue them. *note Make headings more or less colorful: DIY Make headings more or less colorful. @@ -2513,15 +2378,15 @@ inline code in prose use alternative styles. File: modus-themes.info, Node: DIY Make headings more or less colorful, Next: DIY Make Org block colors more or less colorful, Prev: DIY Make TODO and DONE more or less intense, Up: DIY Stylistic variants using palette overrides -7.4.14 DIY Make headings more or less colorful +8.4.14 DIY Make headings more or less colorful ---------------------------------------------- -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY -Stylistic variants using palette overrides.). Here we show how to alter +Stylistic variants using palette overrides.). Here I show how to alter the looks of headings, such as in Org mode. Using overrides here offers -far more flexibility than what we could achieve with previous versions -of the themes: the user can mix and match styles at will. +far more flexibility than what I could achieve with previous versions of +the themes: the user can mix and match styles at will. *note Make TODO and DONE more intense: DIY Make TODO and DONE more or less intense. @@ -2563,15 +2428,15 @@ less intense. File: modus-themes.info, Node: DIY Make Org block colors more or less colorful, Next: DIY Make Org agenda more or less colorful, Prev: DIY Make headings more or less colorful, Up: DIY Stylistic variants using palette overrides -7.4.15 DIY Make Org block colors more or less colorful +8.4.15 DIY Make Org block colors more or less colorful ------------------------------------------------------ -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY -Stylistic variants using palette overrides.). Here we show how to -change the presentation of Org blocks (and other such blocks like -Markdown fenced code sections, though the exact presentation depends on -each major mode). +Stylistic variants using palette overrides.). Here I show how to change +the presentation of Org blocks (and other such blocks like Markdown +fenced code sections, though the exact presentation depends on each +major mode). The default style of Org blocks is a subtle gray background for the contents and for the delimiter lines (the ‘#+begin_’ and ‘#+end_’ @@ -2614,9 +2479,9 @@ inline code in prose use alternative styles. (fg-prose-block-delimiter fg-main))) The previous examples differentiate the delimiter lines from the -block's contents. Though we can mimic the default aesthetic of a -uniform background, while changing the applicable colors. Here are some -nice combinations: +block's contents. Though I can mimic the default aesthetic of a uniform +background, while changing the applicable colors. Here are some nice +combinations: ;; Solid green style. (setq modus-themes-common-palette-overrides @@ -2660,16 +2525,16 @@ Org source blocks per language. File: modus-themes.info, Node: DIY Make Org agenda more or less colorful, Next: DIY Make inline code in prose use alternative styles, Prev: DIY Make Org block colors more or less colorful, Up: DIY Stylistic variants using palette overrides -7.4.16 DIY Make Org agenda more or less colorful +8.4.16 DIY Make Org agenda more or less colorful ------------------------------------------------ -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY -Stylistic variants using palette overrides.). Here we provide three +Stylistic variants using palette overrides.). Here I provide three distinct code blocks. The first adds alternative and more varied colors to the Org agenda (and related). The second uses faint coloration. The third makes the agenda use various shades of blue. Mix and match at -will, while also combining these styles with what we show in the other +will, while also combining these styles with what I show in the other chapters with practical stylistic variants. ;; Make the Org agenda use alternative and varied colors. @@ -2730,15 +2595,15 @@ chapters with practical stylistic variants. File: modus-themes.info, Node: DIY Make inline code in prose use alternative styles, Next: DIY Make mail citations and headers more or less colorful, Prev: DIY Make Org agenda more or less colorful, Up: DIY Stylistic variants using palette overrides -7.4.17 DIY Make inline code in prose use alternative styles +8.4.17 DIY Make inline code in prose use alternative styles ----------------------------------------------------------- -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY Stylistic variants using palette overrides.). In the following code -block we show how to affect constructs such as Org's verbatim, code, and -macro entries. We also provide mappings for tables, property drawers, -tags, and code block delimiters, though we do not show every possible +block I show how to affect constructs such as Org's verbatim, code, and +macro entries. I also provide mappings for tables, property drawers, +tags, and code block delimiters, though I do not show every possible permutation. • *note Make TODO and DONE more or less intense: DIY Make TODO and @@ -2784,17 +2649,17 @@ permutation. File: modus-themes.info, Node: DIY Make mail citations and headers more or less colorful, Next: DIY Make the region preserve text colors plus other styles, Prev: DIY Make inline code in prose use alternative styles, Up: DIY Stylistic variants using palette overrides -7.4.18 DIY Make mail citations and headers more or less colorful +8.4.18 DIY Make mail citations and headers more or less colorful ---------------------------------------------------------------- -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY -Stylistic variants using palette overrides.). In this section we show +Stylistic variants using palette overrides.). In this section I show how to change the coloration of email message headers and citations. -Before we show the code, this is the anatomy of a message: +Before I show the code, this is the anatomy of a message: From: Protesilaos <info@protesilaos.com> - To: Modus-Themes Development <~protesilaos/modus-themes@lists.sr.ht> + To: Some Person <test@domain.sample> Subject: Test subject --- Headers above this line; message and citations below --- This is some sample text @@ -2802,7 +2667,7 @@ Before we show the code, this is the anatomy of a message: > > Older quote > Newer quote - We thus have the following: + I thus have the following: ;; Reduce the intensity of mail citations and headers (setq modus-themes-common-palette-overrides @@ -2843,12 +2708,12 @@ Before we show the code, this is the anatomy of a message: File: modus-themes.info, Node: DIY Make the region preserve text colors plus other styles, Next: DIY Make mouse highlights more or less colorful, Prev: DIY Make mail citations and headers more or less colorful, Up: DIY Stylistic variants using palette overrides -7.4.19 DIY Make the region preserve text colors, plus other styles +8.4.19 DIY Make the region preserve text colors, plus other styles ------------------------------------------------------------------ -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY -Stylistic variants using palette overrides.). Here we show how to make +Stylistic variants using palette overrides.). Here I show how to make the region respect the underlying text colors or how to make the background more/less intense while combining it with an appropriate foreground value. @@ -2877,13 +2742,13 @@ region background. File: modus-themes.info, Node: DIY Make mouse highlights more or less colorful, Next: DIY Make language underlines less colorful, Prev: DIY Make the region preserve text colors plus other styles, Up: DIY Stylistic variants using palette overrides -7.4.20 DIY Make mouse highlights more or less colorful +8.4.20 DIY Make mouse highlights more or less colorful ------------------------------------------------------ -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY Stylistic variants using palette overrides.). In the following code -block we show how to affect the semantic color mapping that covers mouse +block I show how to affect the semantic color mapping that covers mouse hover effects and related highlights: ;; Make the background an intense yellow @@ -2899,14 +2764,14 @@ hover effects and related highlights: File: modus-themes.info, Node: DIY Make language underlines less colorful, Next: DIY Make line numbers use alternative styles, Prev: DIY Make mouse highlights more or less colorful, Up: DIY Stylistic variants using palette overrides -7.4.21 DIY Make language underlines less colorful +8.4.21 DIY Make language underlines less colorful ------------------------------------------------- -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY -Stylistic variants using palette overrides.). Here we show how to -affect the color of the underlines that are used by code linters and -prose spell checkers. +Stylistic variants using palette overrides.). Here I show how to affect +the color of the underlines that are used by code linters and prose +spell checkers. ;; Make the underlines less intense (setq modus-themes-common-palette-overrides @@ -2925,12 +2790,12 @@ prose spell checkers. File: modus-themes.info, Node: DIY Make line numbers use alternative styles, Next: DIY Make diffs use only a foreground, Prev: DIY Make language underlines less colorful, Up: DIY Stylistic variants using palette overrides -7.4.22 DIY Make line numbers use alternative styles +8.4.22 DIY Make line numbers use alternative styles --------------------------------------------------- -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY -Stylistic variants using palette overrides.). In this section we show +Stylistic variants using palette overrides.). In this section I show how to affect the ‘display-line-numbers-mode’. ;; Make line numbers less intense @@ -2960,18 +2825,18 @@ how to affect the ‘display-line-numbers-mode’. File: modus-themes.info, Node: DIY Make diffs use only a foreground, Next: DIY Make deuteranopia diffs red and blue instead of yellow and blue, Prev: DIY Make line numbers use alternative styles, Up: DIY Stylistic variants using palette overrides -7.4.23 DIY Make diffs use only a foreground +8.4.23 DIY Make diffs use only a foreground ------------------------------------------- -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY -Stylistic variants using palette overrides.). In this section we show +Stylistic variants using palette overrides.). In this section I show how to change diff buffers (e.g. in ‘magit’) to only use color-coded -text without any added background. What we basically do is to disable +text without any added background. What I basically do is to disable the applicable backgrounds and then intensify the foregrounds. Since the deuteranopia-optimized themes do not use the red-green color coding, -we make an extra set of adjustments for them by overriding their -palettes directly instead of just using the "common" overrides. +I make an extra set of adjustments for them by overriding their palettes +directly instead of just using the "common" overrides. ;; Diffs with only foreground colors. Word-wise ("refined") diffs ;; have a gray background to draw attention to themselves. @@ -2997,8 +2862,8 @@ palettes directly instead of just using the "common" overrides. (bg-diff-context unspecified))) ;; Because deuteranopia cannot use the typical red-yellow-green - ;; combination, we need to arrange for a yellow-purple-blue sequence. - ;; Notice that the above covers the "common" overrides, so we do not + ;; combination, I need to arrange for a yellow-purple-blue sequence. + ;; Notice that the above covers the "common" overrides, so I do not ;; need to reproduce the whole list of them. (setq modus-operandi-deuteranopia-palette-overrides '((fg-added blue) @@ -3025,12 +2890,12 @@ palettes directly instead of just using the "common" overrides. File: modus-themes.info, Node: DIY Make deuteranopia diffs red and blue instead of yellow and blue, Prev: DIY Make diffs use only a foreground, Up: DIY Stylistic variants using palette overrides -7.4.24 DIY Make deuteranopia diffs red and blue instead of yellow and blue +8.4.24 DIY Make deuteranopia diffs red and blue instead of yellow and blue -------------------------------------------------------------------------- -This is one of our practical examples to override the semantic colors of +This is one of my practical examples to override the semantic colors of the Modus themes (*note Stylistic variants using palette overrides: DIY -Stylistic variants using palette overrides.). In this section we show +Stylistic variants using palette overrides.). In this section I show how to implement a red+blue color coding for diffs in the themes ‘modus-operandi-deuteranopia’ and ‘modus-vivendi-deuteranopia’. As those themes are optimized for users with red-green color deficiency, @@ -3077,7 +2942,7 @@ regular ‘modus-operandi’ and ‘modus-vivendi’. File: modus-themes.info, Node: DIY More accurate colors in terminal emulators, Next: DIY Range of color with terminal emulators, Prev: DIY Stylistic variants using palette overrides, Up: Advanced customization -7.5 DIY More accurate colors in terminal emulators +8.5 DIY More accurate colors in terminal emulators ================================================== [ This is based on partial information. Please help verify and/or @@ -3106,7 +2971,7 @@ adapted to shell aliases: File: modus-themes.info, Node: DIY Range of color with terminal emulators, Next: DIY Per-theme customization settings, Prev: DIY More accurate colors in terminal emulators, Up: Advanced customization -7.6 DIY Range of color with terminal emulators +8.6 DIY Range of color with terminal emulators ============================================== [ This is based on partial information. Please help verify and/or @@ -3176,7 +3041,7 @@ Preview theme colors.): File: modus-themes.info, Node: DIY Per-theme customization settings, Next: DIY Do not extend the region background, Prev: DIY Range of color with terminal emulators, Up: Advanced customization -7.7 DIY Per-theme customization settings +8.7 DIY Per-theme customization settings ======================================== If you prefer to maintain different customization options between the @@ -3212,12 +3077,12 @@ of ‘modus-themes-toggle’ and relevant functions. File: modus-themes.info, Node: DIY Do not extend the region background, Next: DIY Add padding to the mode line, Prev: DIY Per-theme customization settings, Up: Advanced customization -7.8 DIY Do not extend the region background +8.8 DIY Do not extend the region background =========================================== By default, the background of the ‘region’ face extends from the end of the line to the edge of the window. To limit it to the end of the line, -we need to override the face's ‘:extend’ attribute. Adding this to the +I need to override the face's ‘:extend’ attribute. Adding this to the Emacs configuration file will suffice: ;; Do not extend `region' background past the end of the line. @@ -3230,18 +3095,17 @@ Make the region preserve text colors plus other styles. File: modus-themes.info, Node: DIY Add padding to the mode line, Next: DIY Remap face with local value, Prev: DIY Do not extend the region background, Up: Advanced customization -7.9 DIY Add padding to the mode line +8.9 DIY Add padding to the mode line ==================================== [ Consider using the ‘spacious-padding’ package from GNU ELPA (by Protesilaos) for more than just the mode line. ] Emacs faces do not have a concept of "padding" for the space between -the text and its box boundaries. We can approximate the effect by -adding a ‘:box’ attribute, making its border several pixels thick, and -using the mode line's background color for it. This way the thick -border will not stand out and will appear as a continuation of the mode -line. +the text and its box boundaries. I can approximate the effect by adding +a ‘:box’ attribute, making its border several pixels thick, and using +the mode line's background color for it. This way the thick border will +not stand out and will appear as a continuation of the mode line. *note Use theme colors in code with modus-themes-with-colors: Use theme colors in code with modus-themes-with-colors. @@ -3259,7 +3123,7 @@ theme colors in code with modus-themes-with-colors. the post-load-theme phase. The above has the effect of removing the border around the mode -lines. In older versions of the themes, we provided the option for a +lines. In older versions of the themes, I provided the option for a padded mode line which could also have borders around it. Those were not real border, however, but an underline and an overline. Adjusting the above: @@ -3280,8 +3144,8 @@ the above: (add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) - The reason we no longer provide this option is because it depends on -a non-‘nil’ value for ‘x-underline-at-descent-line’. That variable + The reason I no longer provide this option is because it depends on a +non-‘nil’ value for ‘x-underline-at-descent-line’. That variable affects ALL underlines, including those of links. The effect is intrusive and looks awkward in prose. @@ -3294,21 +3158,20 @@ state of affairs. File: modus-themes.info, Node: DIY Remap face with local value, Next: DIY Font configurations for Org and others, Prev: DIY Add padding to the mode line, Up: Advanced customization -7.10 DIY Remap face with local value +8.10 DIY Remap face with local value ==================================== -There are cases where we need to change the buffer-local attributes of a -face. This might be because we have our own minor mode that reuses a -face for a particular purpose, such as a line selection tool that -activates ‘hl-line-mode’, but we wish to keep it distinct from other -buffers. This is where ‘face-remap-add-relative’ can be applied and may -be combined with ‘modus-themes-with-colors’ to deliver consistent -results. +There are cases where I need to change the buffer-local attributes of a +face. This might be because I have my own minor mode that reuses a face +for a particular purpose, such as a line selection tool that activates +‘hl-line-mode’, but I wish to keep it distinct from other buffers. This +is where ‘face-remap-add-relative’ can be applied and may be combined +with ‘modus-themes-with-colors’ to deliver consistent results. *note Use theme colors in code with modus-themes-with-colors: Use theme colors in code with modus-themes-with-colors. - In this example we will write a simple interactive function that + In this example I will write a simple interactive function that adjusts the background color of the ‘region’ face. This is the sample code: @@ -3336,7 +3199,7 @@ code: color to use. The list of candidates is drawn from the car of each association in ‘my-rainbow-region-colors’ (so "red", "green", etc.). - To extend this principle, we may write wrapper functions that pass a + To extend this principle, I may write wrapper functions that pass a color directly. Those can be useful in tandem with hooks. Consider this example: @@ -3345,11 +3208,11 @@ this example: (add-hook 'diff-mode-hook #'my-rainbow-region-magenta) - Whenever we enter a ‘diff-mode’ buffer, we now get a magenta-colored + Whenever I enter a ‘diff-mode’ buffer, I now get a magenta-colored region. Perhaps you may wish to generalize those findings in to a set of -functions that also accept an arbitrary face. We shall leave the +functions that also accept an arbitrary face. I shall leave the experimentation up to you. Reload the theme for changes to take effect. @@ -3357,7 +3220,7 @@ experimentation up to you. File: modus-themes.info, Node: DIY Font configurations for Org and others, Next: DIY Configure bold and italic faces, Prev: DIY Remap face with local value, Up: Advanced customization -7.11 DIY Font configurations for Org and others +8.11 DIY Font configurations for Org and others =============================================== [ Consider using the ‘fontaine’ package from GNU ELPA (by Protesilaos) @@ -3428,7 +3291,7 @@ account for those finer increments. File: modus-themes.info, Node: DIY Configure bold and italic faces, Next: DIY Custom Org todo keyword and priority faces, Prev: DIY Font configurations for Org and others, Up: Advanced customization -7.12 DIY Configure bold and italic faces +8.12 DIY Configure bold and italic faces ======================================== [ Consider using the ‘fontaine’ package from GNU ELPA (by Protesilaos) @@ -3465,14 +3328,14 @@ the instructions for all typeface tweaks. *note Font configurations for Org and others: DIY Font configurations for Org and others. - In this example, we set the default font family to Fira Code, while -we choose to render italics in the Hack typeface (obviously you need to + In this example, I set the default font family to Fira Code, while I +choose to render italics in the Hack typeface (obviously you need to pick fonts that work well together): (set-face-attribute 'default nil :family "Fira Code" :height 110) (set-face-attribute 'italic nil :family "Hack") - And here we play with different weights, using Source Code Pro: + And here I play with different weights, using Source Code Pro: (set-face-attribute 'default nil :family "Source Code Pro" :height 110 :weight 'light) (set-face-attribute 'bold nil :weight 'semibold) @@ -3501,7 +3364,7 @@ scale operations (‘custom-set-faces’ follows the format used in the source code of the themes, which can make it easier to redefine faces in bulk). - ;; our generic function + ;; my generic function (defun my-modes-themes-bold-italic-faces (&rest _) (set-face-attribute 'default nil :family "Source Code Pro" :height 110) (set-face-attribute 'bold nil :weight 'semibold)) @@ -3528,7 +3391,7 @@ the post-load-theme phase. File: modus-themes.info, Node: DIY Custom Org todo keyword and priority faces, Next: DIY Custom Org emphasis faces, Prev: DIY Configure bold and italic faces, Up: Advanced customization -7.13 DIY Custom Org todo keyword and priority faces +8.13 DIY Custom Org todo keyword and priority faces =================================================== Users of ‘org-mode’ have the option to configure various keywords and @@ -3537,7 +3400,7 @@ priority cookies to better match their workflow. User options are As those are meant to be custom faces, it is futile to have the themes guess what each user wants to use, which keywords to target, and -so on. Instead, we can provide guidelines on how to customize things to +so on. Instead, I can provide guidelines on how to customize things to one's liking with the intent of retaining the overall aesthetic of the themes. @@ -3611,7 +3474,7 @@ Do it if you plan to control face attributes. File: modus-themes.info, Node: DIY Custom Org emphasis faces, Next: DIY Use colored Org source blocks per language, Prev: DIY Custom Org todo keyword and priority faces, Up: Advanced customization -7.14 DIY Custom Org emphasis faces +8.14 DIY Custom Org emphasis faces ================================== Org provides the user option ‘org-emphasis-alist’ which associates a @@ -3675,9 +3538,9 @@ example, green and yellow hues, respectively: :foreground "#d0bc00")) "My underline emphasis for Org.") - In the case of a strike-through effect, we have no generic face to -inherit from, so we can write it as follows to also change the -foreground to a more subtle gray: + In the case of a strike-through effect, I have no generic face to +inherit from, so I can write it as follows to also change the foreground +to a more subtle gray: (defface my-org-emphasis-strike-through '((default :strike-through t) @@ -3687,7 +3550,7 @@ foreground to a more subtle gray: :foreground "#a8a8a8")) "My strike-through emphasis for Org.") - Or we can just change the color of the line that strikes through the + Or I can just change the color of the line that strikes through the text to, for example, a shade of red: (defface my-org-emphasis-strike-through @@ -3714,7 +3577,7 @@ entry in the palette. *note Visualize the active Modus theme's palette: Preview theme colors. - Once we have defined the faces we need, we must update the + Once I have defined the faces I need, I must update the ‘org-emphasis-alist’. Given that ‘org-verbatim’ and ‘org-code’ are already styled by the themes, it probably is best not to edit them: @@ -3732,7 +3595,7 @@ invoke ‘M-x org-mode-restart’. File: modus-themes.info, Node: DIY Use colored Org source blocks per language, Next: DIY Measure color contrast, Prev: DIY Custom Org emphasis faces, Up: Advanced customization -7.15 DIY Use colored Org source blocks per language +8.15 DIY Use colored Org source blocks per language =================================================== *note DIY Make Org block colors more or less colorful: DIY Make Org @@ -3741,7 +3604,7 @@ block colors more or less colorful. In versions of the Modus themes before ‘4.4.0’ there was an option to change the coloration of Org source blocks so that certain languages would have a distinctly colored background. This was not flexible -enough, because (i) we cannot cover all languages effectively and (ii) +enough, because (i) I cannot cover all languages effectively and (ii) the user had no choice over the ‘language --> color’ mapping. As such, the old user option is no more. Users can use the following @@ -3821,7 +3684,7 @@ idea: File: modus-themes.info, Node: DIY Measure color contrast, Next: DIY Load theme depending on time of day, Prev: DIY Use colored Org source blocks per language, Up: Advanced customization -7.16 DIY Measure color contrast +8.16 DIY Measure color contrast =============================== The themes provide the functions ‘modus-themes-wcag-formula’ and @@ -3886,10 +3749,10 @@ theme's color palette. File: modus-themes.info, Node: DIY Load theme depending on time of day, Next: DIY Backdrop for pdf-tools, Prev: DIY Measure color contrast, Up: Advanced customization -7.17 DIY Load theme depending on time of day +8.17 DIY Load theme depending on time of day ============================================ -While we do provide ‘modus-themes-toggle’ to manually switch between the +While I do provide ‘modus-themes-toggle’ to manually switch between the themes, users may also set up their system to perform such a task automatically at sunrise and sunset. @@ -3913,7 +3776,7 @@ location using the built-in ‘solar.el’ and then configuring the File: modus-themes.info, Node: DIY Backdrop for pdf-tools, Next: DIY Toggle themes without reloading them, Prev: DIY Load theme depending on time of day, Up: Advanced customization -7.18 DIY Backdrop for pdf-tools +8.18 DIY Backdrop for pdf-tools =============================== Most PDF files use a white background for their page, making it @@ -3922,13 +3785,13 @@ the Modus Operandi theme. To introduce a distinction between the buffer's backdrop and the PDF page's background, the former must be rendered as some shade of gray. Ideally, ‘pdf-tools’ would provide a face that the themes could support directly, though this does not seem -to be the case for the time being. We must thus employ the face +to be the case for the time being. I must thus employ the face remapping technique that is documented elsewhere in this document to change the buffer-local value of the ‘default’ face. *note Remap face with local value: DIY Remap face with local value. - To remap the buffer's backdrop, we start with a function like this + To remap the buffer's backdrop, I start with a function like this one: (defun my-pdf-tools-backdrop (&rest _) @@ -3947,10 +3810,10 @@ the face remapping function does not get evaluated anew whenever the theme changes, such as upon invoking ‘M-x modus-themes-toggle’ (*note Option for which themes to toggle: Option for which themes to toggle.). - To have our face remapping adapt gracefully while switching between -the Modus themes, we need to also account for the current theme and + To have my face remapping adapt gracefully while switching between +the Modus themes, I need to also account for the current theme and control the activation of ‘pdf-view-midnight-minor-mode’. To which end -we arrive at something like the following, which builds on the above +I arrive at something like the following, which builds on the above example: (defun my-pdf-tools-backdrop (&rest _) @@ -3988,7 +3851,7 @@ to dark mode when ‘modus-themes-toggle’ is called. File: modus-themes.info, Node: DIY Toggle themes without reloading them, Next: DIY Use more spacious margins or padding in Emacs frames, Prev: DIY Backdrop for pdf-tools, Up: Advanced customization -7.19 DIY Toggle themes without reloading them +8.19 DIY Toggle themes without reloading them ============================================= Users who have a stable setup and who only ever need to toggle between @@ -4008,7 +3871,7 @@ their own command which calls ‘enable-theme’ instead of ‘load-theme’: (disable-theme 'modus-vivendi))) (_ (error "No Modus theme is loaded; evaluate `modus-themes-load-themes' first")))) - *note Differences between loading and enabling: Differences between + *note Difference between loading and enabling: Difference between loading and enabling. Recall that ‘modus-themes-toggle’ uses ‘load-theme’. @@ -4016,7 +3879,7 @@ loading and enabling. File: modus-themes.info, Node: DIY Use more spacious margins or padding in Emacs frames, Next: DIY Custom hl-todo colors, Prev: DIY Toggle themes without reloading them, Up: Advanced customization -7.20 DIY Use more spacious margins or padding in Emacs frames +8.20 DIY Use more spacious margins or padding in Emacs frames ============================================================= [ UPDATE 2023-06-25: Instead of following these instructions, you can @@ -4047,7 +3910,7 @@ 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 + In detail, first I use the same values for the two frame alist variables: ;; This must go in the early-init.el so that it applies to the initial @@ -4057,10 +3920,10 @@ variables: (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. +I 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 + Then I define a function that makes the relevant faces invisible. +The reason I do this with a function is so I 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). @@ -4104,13 +3967,13 @@ theme loading: DIY A theme-agnostic hook for theme loading.). File: modus-themes.info, Node: DIY Custom hl-todo colors, Next: DIY Add support for solaire-mode, Prev: DIY Use more spacious margins or padding in Emacs frames, Up: Advanced customization -7.21 DIY Custom hl-todo colors +8.21 DIY Custom hl-todo colors ============================== The ‘hl-todo’ package provides the user option ‘hl-todo-keyword-faces’: it specifies a pair of keyword and corresponding color value. The Modus themes configure that option in the interest of legibility. While this -works for our purposes, users may still prefer to apply their custom +works for my purposes, users may still prefer to apply their custom values, in which case the following approach is necessary: (defun my-modus-themes-hl-todo-faces (&rest _) @@ -4139,7 +4002,7 @@ the post-load-theme phase. *note Using a hook at the post-load-theme phase: DIY Use a hook at the post-load-theme phase. - Normally, we do not touch user options, though this is an exception: + Normally, I do not touch user options, though this is an exception: otherwise the defaults are not always legible. Reload the theme for changes to take effect. @@ -4147,7 +4010,7 @@ otherwise the defaults are not always legible. 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.22 DIY Add support for solaire-mode +8.22 DIY Add support for solaire-mode ===================================== The ‘solaire-mode’ package dims the background of what it considers @@ -4163,27 +4026,27 @@ practically invisible). always hold true. There are cases where it is enabled by defaultsuch as in the popular Doom Emacs configuration. Thus, the unsuspecting user who loads ‘modus-operandi’ or ‘modus-vivendi’ without the requisite -customizations is getting a sub-par experience; an experience that we -did not intend and cannot genuinely fix. +customizations is getting a sub-par experience; an experience that I did +not intend and cannot genuinely fix. - Because the Modus themes are meant to work everywhere, we cannot make -an exception for Doom Emacs and/or Solaire users. Furthermore, we shall + Because the Modus themes are meant to work everywhere, I cannot make +an exception for Doom Emacs and/or Solaire users. Furthermore, I shall not introduce hacks, such as by adding a check in all relevant faces to be adjusted based on Solaire or whatever other package. Hacks of this sort are unsustainable and penalize the entire userbase. Besides, the -themes are built into Emacs and we must keep their standard high. +themes are built into Emacs and I must keep their standard high. The fundamental constraint with Solaire is that Emacs does not have a real distinction between "content" and "UI" buffers. For themes to work with Solaire, they need to be designed around that package. Such is an -arrangement that compromises on our accessibility standards and/or -hinders our efforts to provide the best possible experience while using +arrangement that compromises on my accessibility standards and/or +hinders my efforts to provide the best possible experience while using the Modus themes. As such, ‘solaire-mode’ is not--and will not be--supported by the Modus themes (or any other of my themes, for that matter). Users who want it must style the faces manually. Below is some sample code, based -on what we cover at length elsewhere in this manual: +on what I cover at length elsewhere in this manual: *note Advanced customization: Advanced customization. @@ -4208,7 +4071,7 @@ the post-load-theme phase. File: modus-themes.info, Node: DIY Add support for meow-mode, Next: DIY Add support for combobulate, Prev: DIY Add support for solaire-mode, Up: Advanced customization -7.23 DIY Add support for meow-mode +8.23 DIY Add support for meow-mode ================================== The ‘meow’ package provides a modal editing experience. It is meant to @@ -4239,7 +4102,7 @@ the post-load-theme phase. File: modus-themes.info, Node: DIY Add support for combobulate, Next: DIY Use a hook at the post-load-theme phase, Prev: DIY Add support for meow-mode, Up: Advanced customization -7.24 DIY Add support for combobulate +8.24 DIY Add support for combobulate ==================================== The ‘combobulate’ package provides the means to operate on text that is @@ -4290,7 +4153,7 @@ 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 combobulate, Up: Advanced customization -7.25 DIY Use a hook at the post-load-theme phase +8.25 DIY Use a hook at the post-load-theme phase ================================================ Many of the Do-It-Yourself (DIY) snippets provided herein make use of a @@ -4345,7 +4208,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.25.1 DIY A theme-agnostic hook for theme loading +8.25.1 DIY A theme-agnostic hook for theme loading -------------------------------------------------- [ NOTE: The following is for versions of Emacs before 29. For Emacs 29 @@ -4354,14 +4217,14 @@ or higher, users can rely on the built-in ‘enable-theme-functions’ post-load-theme phase.). ] The themes are designed with the intent to be useful to Emacs users -of varying skill levels, from beginners to experts. This means that we +of varying skill levels, from beginners to experts. This means that I try to make things easier by not expecting anyone reading this document to be proficient in Emacs Lisp or programming in general. Such a case is with the use of ‘modus-themes-after-load-theme-hook’, which runs after the ‘modus-themes-load-theme’ function (used by the -command ‘modus-themes-toggle’). We recommend using that hook for -advanced customizations, because (1) we know for sure that it is +command ‘modus-themes-toggle’). I recommend using that hook for +advanced customizations, because (1) I know for sure that it is available once the themes are loaded, and (2) anyone consulting this manual, especially the sections on enabling and loading the themes, will be in a good position to benefit from that hook. @@ -4394,14 +4257,14 @@ to it will likely not be able to benefit from macro calls that read the active theme, such as ‘modus-themes-with-colors’. Not all Emacs themes have the same capabilities. - 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). + In this document, I 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). File: modus-themes.info, Node: Build on top of the Modus themes, Next: Face coverage, Prev: Advanced customization, Up: Top -8 Build on top of the Modus themes +9 Build on top of the Modus themes ********************************** This section concerns package developers or advanced users. @@ -4485,7 +4348,7 @@ passing all the mandatory arguments, but not the optional ones: 'ef-summer-palette 'ef-summer-palette-overrides) - Here we notice how ‘ef-summer’ has ‘modus-operandi-palette’ as its + Here I notice how ‘ef-summer’ has ‘modus-operandi-palette’ as its ‘CORE-PALETTE’. This means that if the ‘ef-summer-palette’ lacks some entry, the theme will still work and it will inherit the style of ‘modus-operandi’ for that specific element. @@ -4535,15 +4398,15 @@ corresponds to some named color in the palette of the active theme. 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 -8.1 Complete example of a Modus derivative theme +9.1 Complete example of a Modus derivative theme ================================================ [ For more context: *note Build on top of the Modus themes: Build on top of the Modus themes. ] - In this section, we show how to define a new Modus derivative theme. + In this section, I show how to define a new Modus derivative theme. In its simplest form, a theme is a file called ‘NAME-theme.el’ in a -directory that is part of the ‘custom-theme-load-path’. We show how to +directory that is part of the ‘custom-theme-load-path’. I show how to do this for a package and for a private configuration: • *note Complete example of a package that is derived from Modus: @@ -4561,7 +4424,7 @@ do this for a package and for a private configuration: File: modus-themes.info, Node: Complete example of a package that is derived from Modus, Next: Complete example of a private theme derived from Modus, Up: Complete example of a Modus derivative theme -8.1.1 Complete example of a package that is derived from Modus +9.1.1 Complete example of a package that is derived from Modus -------------------------------------------------------------- For package developers, the following snippet needs to be included in @@ -4581,7 +4444,7 @@ individual theme files. For example, the family of themes that includes ‘prot-light-theme.el’ and ‘prot-dark-theme.el’ has a shared library which is ‘prot-themes.el’ -and therein we find at least the following: +and therein I find at least the following: ;; Package headers here for prot-themes.el... @@ -4654,7 +4517,7 @@ 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 -8.1.2 Complete example of a private theme derived from Modus +9.1.2 Complete example of a private theme derived from Modus ------------------------------------------------------------ If your derivative theme is not going to be distributed as a package @@ -4667,8 +4530,8 @@ can be included thus somewhere in the Emacs initialization file: (add-to-list 'custom-theme-load-path (locate-user-emacs-file "my-custom-themes/")) The function ‘locate-user-emacs-file’ takes care to return a path -relative to where the user's init file is. If, say, we have -‘~/.emacs.d/init.el’ then we get ‘~/.emacs.d/my-custom-themes/’. +relative to where the user's init file is. If, say, I have +‘~/.emacs.d/init.el’ then I get ‘~/.emacs.d/my-custom-themes/’. Create the directory in that path. Then for each derivative Modus theme, write a new file of the form ‘NAME-theme.el’. If, for instance, @@ -4694,7 +4557,7 @@ 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 -8.1.3 Complete example of a custom theme with its own palette +9.1.3 Complete example of a custom theme with its own palette ------------------------------------------------------------- It is a good idea for a derivative theme to use as its core palette one @@ -4711,12 +4574,12 @@ theme colors: Preview theme colors.). (*note Build on top of the Modus themes: Build on top of the Modus themes.). - In the following example, we are defining the ‘prot-light’ theme in -the ‘prot-light-theme.el’ file. This theme declares itself as belonging -to the ‘prot-themes’ family. It is based on the -‘modus-operandi-palette’ but then defines its own palette, the -‘prot-light-palette’ with entries that take precedence over whatever -equivalent is in the ‘modus-operandi-palette’. + In the following example, I am defining the ‘prot-light’ theme in the +‘prot-light-theme.el’ file. This theme declares itself as belonging to +the ‘prot-themes’ family. It is based on the ‘modus-operandi-palette’ +but then defines its own palette, the ‘prot-light-palette’ with entries +that take precedence over whatever equivalent is in the +‘modus-operandi-palette’. (defvar prot-light-palette '((cursor "#ff0000") @@ -4739,7 +4602,7 @@ There is no limit to how comprehensive the user palette is. Depending on the requirements, this theme can make itself further customizable by the end user via theme-specific palette overrides. In -this case, we have the addition of a user option, which we could call +this case, I have the addition of a user option, which I could call anything though it makes sense to name it consistently like ‘prot-light-palette-overrides’. @@ -4763,7 +4626,7 @@ anything though it makes sense to name it consistently like 'prot-light-palette 'prot-light-palette-overrides) - In the above example, we have our ‘prot-light’ theme which is like + In the above example, I have my ‘prot-light’ theme which is like ‘modus-operandi’ except three colors and which can now be customized further by the user via the ‘prot-light-palette-overrides’ (*note Option for palette overrides: Palette overrides.). @@ -4812,7 +4675,7 @@ 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 -8.1.4 Complete example that also uses ‘modus-themes-generate-palette’ +9.1.4 Complete example that also uses ‘modus-themes-generate-palette’ --------------------------------------------------------------------- The guide herein is of use to those who plan to create their own @@ -4824,8 +4687,8 @@ palette that can be passed to ‘modus-themes-theme’ without necessarily depending on any of the core Modus palettes. I will walk you through the steps of working with something like the following code block. - [ We use color values from Solarized as an example for the rest of -this entry, naming them according to our conventions. ] + [ I use color values from Solarized as an example for the rest of +this entry, naming them according to my conventions. ] (defvar modus-solarized-dark-palette (modus-themes-generate-palette @@ -4883,7 +4746,7 @@ the command ‘list-colors-display’. The only two mandatory entries in ‘BASE-COLORS’ are ‘bg-main’ and ‘fg-main’ as shown above. In this scenario, the derived palette will get the job done, but will be very close to what Modus defines. The -more we add to the ‘BASE-COLORS’, the more well defined the character of +more I add to the ‘BASE-COLORS’, the more well defined the character of the new palette will be. For example: (modus-themes-generate-palette @@ -4899,9 +4762,9 @@ the new palette will be. For example: This is already going to be a tolerable port of Solarized. If the ‘BASE-COLORS’ provides ‘bg-main’, ‘fg-main’, and the six hues of ‘red’, -‘green’, ‘yellow’, ‘blue’, ‘magenta’, ‘cyan’, we will get a new palette +‘green’, ‘yellow’, ‘blue’, ‘magenta’, ‘cyan’, I will get a new palette that has no trace of the color values implemented by core Modus. Though -we can go further and greatly improve the results. +I can go further and greatly improve the results. The ‘modus-themes-generate-palette’ will internally calculate colors based on what it receives. Anything missing will be taken from a core @@ -4910,7 +4773,7 @@ the ‘modus-themes-operandi-palette’ is used, otherwise it is ‘modus-themes-vivendi-palette’. If all six of the aforementioned hues are present, the ‘modus-themes-generate-palette’ will not calculate any more color values. It will use those to derive the relevant -permutations (e.g. blue backgrounds from the ‘blue’ we give it). +permutations (e.g. blue backgrounds from the ‘blue’ I give it). What also plays a role in the interal calculations is whether ‘bg-main’ is a ‘cool’ or ‘warm’ color, meaning whether it is closer to @@ -4942,7 +4805,7 @@ background goes together with cooler foreground values. Thus: (blue "#268BD2") (magenta "#D33682") (cyan "#2AA198")) - 'warm) ; but we want to use it with `warm' foregrounds + 'warm) ; but I want to use it with `warm' foregrounds ;; And here is the inverse of the above, now with the light version of ;; Solarized. @@ -4955,9 +4818,9 @@ background goes together with cooler foreground values. Thus: (blue "#268BD2") (magenta "#D33682") (cyan "#2AA198")) - 'cool) ; but we want to use it with `cool' foregrounds + 'cool) ; but I want to use it with `cool' foregrounds - This is now getting better, but we can go further. At this point + This is now getting better, but I can go further. At this point users should be able to do the common work of taking a color scheme that was originally designed for terminal emulators and quickly turning it into a fully fledged Modus palette. All they need is to follow the @@ -4965,8 +4828,8 @@ naming convention for ‘bg-main’, ‘fg-main’, and then ‘{red,green,yellow,blue,magenta,cyan}{,-warmer,-cooler}’. Preview a palette to get the complete list (*note Preview theme colors: Preview theme colors.). And, again, remember that not all colors need to be -defined in ‘BASE-COLORS’ (e.g. we could leave out ‘magenta-cooler’ if -we do not care about it). +defined in ‘BASE-COLORS’ (e.g. I could leave out ‘magenta-cooler’ if I +do not care about it). The next optional parameter of ‘modus-themes-generate-palette’ is the ‘CORE-PALETTE’ it should use. This is to make explicit the decision @@ -4999,7 +4862,7 @@ but, again, users probably should leave this to ‘nil’: (magenta "#D33682") (cyan "#2AA198")) nil ; COOL-OR-WARM-PREFERENCE is derived internally based on `bg-main' - 'modus-themes-vivendi-tritanopia-palette) ; we specifically want this as our CORE-PALETTE + 'modus-themes-vivendi-tritanopia-palette) ; I specifically want this as my CORE-PALETTE With core Modus palettes, the ‘CORE-PALETTE’ should not make much of a difference. Though a completely custom Modus derivative, like one of @@ -5011,13 +4874,13 @@ semantic mappings. parameter. This is a list of semantic mappings where each entry is of the form ‘(NAME OTHER-NAME)’ (*note Option for palette overrides: Palette overrides.). The ‘NAME’ has the same meaning as for the -‘BASE-COLORS’ we have been examining all along, while ‘OTHER-NAME’ is -the symbol of another ‘NAME’ that exists in the palette, hence the -mapping. This manual contains lots of examples along those lines (*note -DIY Stylistic variants using palette overrides: DIY Stylistic variants -using palette overrides.). For our purposes, we will modify some of the -obvious elements of the theme, namely, the cursor, mode lines, current -line highlight, matching parentheses, and active region. +‘BASE-COLORS’ I have been examining all along, while ‘OTHER-NAME’ is the +symbol of another ‘NAME’ that exists in the palette, hence the mapping. +This manual contains lots of examples along those lines (*note DIY +Stylistic variants using palette overrides: DIY Stylistic variants using +palette overrides.). For my purposes, I will modify some of the obvious +elements of the theme, namely, the cursor, mode lines, current line +highlight, matching parentheses, and active region. (modus-themes-generate-palette '((bg-main "#073642") @@ -5030,13 +4893,13 @@ line highlight, matching parentheses, and active region. (cyan "#2AA198")) nil nil - ;; And here are our MAPPINGS where we can specify what values apply + ;; And here are my MAPPINGS where I can specify what values apply ;; to which semantic color. The `modus-themes-list-colors' shows ;; them all. ;; - ;; Note that in our BASE-COLORS above we never wrote what, say, + ;; Note that in my BASE-COLORS above I never wrote what, say, ;; `magenta-warmer' is: it is derived programmatically from the - ;; `magenta' we have there. Absent that, it would be taken from + ;; `magenta' I have there. Absent that, it would be taken from ;; the CORE-PALETTE. '((cursor magenta-warmer) (bg-hl-line bg-blue-nuanced) @@ -5056,10 +4919,10 @@ knew how to do this, ‘modus-themes-generate-palette’ would not be of real value). The point is to start with something that works and then refine it one small step at a time. - We are now ready to try our Solarized themes, using the example of -doing this in our private configuration (*note Complete example of a -package that is derived from Modus: Complete example of a package that -is derived from Modus.). + I am now ready to try my Solarized themes, using the example of doing +this in my private configuration (*note Complete example of a package +that is derived from Modus: Complete example of a package that is +derived from Modus.). • Create two files, one is called ‘modus-solarized-dark-theme.el’ (or however you want to identify it, but always keep ‘-theme.el’ at the @@ -5082,8 +4945,8 @@ is derived from Modus.). ;; Modus+Solarized dark (defvar modus-solarized-dark-palette (modus-themes-generate-palette - ;; We provide the two base colors of Solarized, plus most of its - ;; accents. These form the BASE-COLORS we pass as an argument. + ;; I provide the two base colors of Solarized, plus most of its + ;; accents. These form the BASE-COLORS I pass as an argument. ;; All other color values come from those. The BASE-COLORS here ;; are enough to generate a new palatte that has no traces of, say, ;; the `modus-vivendi' color values. @@ -5096,20 +4959,20 @@ is derived from Modus.). (magenta "#D33682") (cyan "#2AA198")) ;; The COOL-OR-WARM-PREFERENCE is derived internally based on - ;; `bg-main'. We can pass it here if we feel strongly about it. + ;; `bg-main'. I can pass it here if I feel strongly about it. nil - ;; If we need to specify the CORE-PALETTE from where to inherit any - ;; missing colors and/or semantic mappings, we can give it here. + ;; If I need to specify the CORE-PALETTE from where to inherit any + ;; missing colors and/or semantic mappings, I can give it here. ;; Though nil is the appropriate starting point, as the code will ;; handle things internally. nil - ;; And here are our MAPPINGS where we can specify what values apply + ;; And here are my MAPPINGS where I can specify what values apply ;; to which semantic color. The `modus-themes-list-colors' shows ;; them all. ;; - ;; Note that in our BASE-COLORS above we never wrote what, say, + ;; Note that in my BASE-COLORS above I never wrote what, say, ;; `magenta-warmer' is: it is derived programmatically from the - ;; `magenta' we have there. Absent that, it would be taken from + ;; `magenta' I have there. Absent that, it would be taken from ;; the CORE-PALETTE. '((cursor magenta-warmer) (bg-hl-line bg-blue-nuanced) @@ -5134,8 +4997,8 @@ is derived from Modus.). ;; Modus+Solarized light (defvar modus-solarized-light-palette (modus-themes-generate-palette - ;; We provide the two base colors of Solarized, plus most of its - ;; accents. These form the BASE-COLORS we pass as an argument. + ;; I provide the two base colors of Solarized, plus most of its + ;; accents. These form the BASE-COLORS I pass as an argument. ;; All other color values come from those. The BASE-COLORS here ;; are enough to generate a new palatte that has no traces of, say, ;; the `modus-operandi' color values. @@ -5148,20 +5011,20 @@ is derived from Modus.). (magenta "#D33682") (cyan "#2AA198")) ;; The COOL-OR-WARM-PREFERENCE is derived internally based on - ;; `bg-main'. We can pass it here if we feel strongly about it. + ;; `bg-main'. I can pass it here if I feel strongly about it. nil - ;; If we need to specify the CORE-PALETTE from where to inherit any - ;; missing colors and/or semantic mappings, we can give it here. + ;; If I need to specify the CORE-PALETTE from where to inherit any + ;; missing colors and/or semantic mappings, I can give it here. ;; Though nil is the appropriate starting point, as the code will ;; handle things internally. nil - ;; And here are our MAPPINGS where we can specify what values apply + ;; And here are my MAPPINGS where I can specify what values apply ;; to which semantic color. The `modus-themes-list-colors' shows ;; them all. ;; - ;; Note that in our BASE-COLORS above we never wrote what, say, + ;; Note that in my BASE-COLORS above I never wrote what, say, ;; `magenta-warmer' is: it is derived programmatically from the - ;; `magenta' we have there. Absent that, it would be taken from + ;; `magenta' I have there. Absent that, it would be taken from ;; the CORE-PALETTE. '((cursor yellow-warmer) (bg-hl-line bg-red-nuanced) @@ -5187,7 +5050,7 @@ 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 -8.2 Determine what counts as a Modus theme +9.2 Determine what counts as a Modus theme ========================================== [ NOTE: Users of many Modus derivatives do not need to do anything of @@ -5231,7 +5094,7 @@ enabled. In this scenario, "Modus" themes are only those whose family is ‘ef-themes’. All the Modus commands that switch between themes will thus only work with those Ef themes. - For our part, we define the ‘modus-themes-include-derivatives-mode’. + For my part, I define the ‘modus-themes-include-derivatives-mode’. It is how users can opt in to the all-inclusive conception of "Modus". In this scenario, every theme that is declared with the aforementioned ‘modus-themes-theme’ will count as "Modus" and be available to all the @@ -5257,14 +5120,14 @@ on. 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 +9.3 Create convenience commands to load a derivative theme ========================================================== [ NOTE: Users of many Modus derivatives do not need to do anything of what is described herein. Just enable the ‘modus-themes-include-derivatives-mode’. ] - In the previous section, we explored the mechanics of the + In the previous section, I explored the mechanics of the ‘modus-themes-get-themes’ (*note Determine what counts as a Modus theme: Determine what counts as a Modus theme.). Independent of that method, developers can use the macro ‘modus-themes-define-derivative-command’ to @@ -5309,7 +5172,7 @@ 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 +9.4 Arrange to activate your derivative themes ============================================== The ‘modus-themes-theme’ function is responsible for instantiating a @@ -5317,7 +5180,7 @@ theme and registering it for use by the various Modus commands that act on a theme (*note Build on top of the Modus themes: 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 +already loaded. Otherwise my function is never called and the theme is never created. To this end, users need to call the function ‘modus-themes-activate’ @@ -5329,7 +5192,7 @@ form, the activation looks as follows, assuming the theme's file (modus-themes-activate 'modus-solarized-dark) - To load multiple themes at once we can define a function like the + To load multiple themes at once I can define a function like the following: (defun my-modus-derivatives-activate-themes (directory) @@ -5356,8 +5219,8 @@ following: File: modus-themes.info, Node: Face coverage, Next: Notes on individual packages, Prev: Build on top of the Modus themes, Up: Top -9 Face coverage -*************** +10 Face coverage +**************** The Modus themes try to provide as close to full face coverage as possible. This is necessary to ensure a consistently accessible reading @@ -5371,8 +5234,8 @@ experience across all available interfaces. File: modus-themes.info, Node: Supported packages, Next: Indirectly covered packages, Up: Face coverage -9.1 Full support for packages or face groups -============================================ +10.1 Full support for packages or face groups +============================================= This list will always be updated to reflect the current state of the project. The idea is to offer an overview of the known status of all @@ -5658,8 +5521,8 @@ have lots of extensions, so the "full support" may not be 100% true… File: modus-themes.info, Node: Indirectly covered packages, Prev: Supported packages, Up: Face coverage -9.2 Indirectly covered packages -=============================== +10.2 Indirectly covered packages +================================ These do not require any extra styles because they are configured to inherit from some basic faces or their dependencies which are directly @@ -5720,7 +5583,7 @@ supported by the themes. File: modus-themes.info, Node: Notes on individual packages, Next: Frequently Asked Questions, Prev: Face coverage, Up: Top -10 Notes on individual packages +11 Notes on individual packages ******************************* This section covers information that may be of interest to users of @@ -5751,7 +5614,7 @@ individual packages. File: modus-themes.info, Node: Note on calendarel weekday and weekend colors, Next: Note on git-gutter in Doom Emacs, Up: Notes on individual packages -10.1 Note on calendar.el weekday and weekend colors +11.1 Note on calendar.el weekday and weekend colors =================================================== By default, the ‘M-x calendar’ interface differentiates weekdays from @@ -5779,7 +5642,7 @@ anew. File: modus-themes.info, Node: Note on git-gutter in Doom Emacs, Next: Note on php-mode multiline comments, Prev: Note on calendarel weekday and weekend colors, Up: Notes on individual packages -10.2 Note on git-gutter in Doom Emacs +11.2 Note on git-gutter in Doom Emacs ===================================== The ‘git-gutter’ and ‘git-gutter-fr’ packages default to drawing bitmaps @@ -5788,9 +5651,9 @@ lines). In Doom Emacs, these bitmaps are replaced with contiguous lines which may look nicer, but require a change to the foreground of the relevant faces to yield the desired color combinations. - Since this is Doom-specific, we urge users to apply changes in their -local setup. Below is some sample code, based on what we cover at -length elsewhere in this manual: + Since this is Doom-specific, I urge users to apply changes in their +local setup. Below is some sample code, based on what I cover at length +elsewhere in this manual: *note Advanced customization: Advanced customization. @@ -5835,7 +5698,7 @@ the post-load-theme phase. File: modus-themes.info, Node: Note on php-mode multiline comments, Next: Note on underlines in compilation buffers, Prev: Note on git-gutter in Doom Emacs, Up: Notes on individual packages -10.3 Note on php-mode multiline comments +11.3 Note on php-mode multiline comments ======================================== Depending on your build of Emacs and/or the environment it runs in, @@ -5854,7 +5717,7 @@ multiline comments in PHP with the ‘php-mode’ package use the File: modus-themes.info, Node: Note on underlines in compilation buffers, Next: Note on inline Latex in Org buffers, Prev: Note on php-mode multiline comments, Up: Notes on individual packages -10.4 Note on underlines in compilation buffers +11.4 Note on underlines in compilation buffers ============================================== Various buffers that produce compilation results or run tests on code @@ -5877,7 +5740,7 @@ faces. File: modus-themes.info, Node: Note on inline Latex in Org buffers, Next: Note on dimmerel, Prev: Note on underlines in compilation buffers, Up: Notes on individual packages -10.5 Note on inline Latex in Org buffers +11.5 Note on inline Latex in Org buffers ======================================== Org can work with inline latex and related syntax. To actually fontify @@ -5891,12 +5754,12 @@ the desired list of values (per its docstring). For example: File: modus-themes.info, Node: Note on dimmerel, Next: Note on display-fill-column-indicator-mode, Prev: Note on inline Latex in Org buffers, Up: Notes on individual packages -10.6 Note on dimmer.el +11.6 Note on dimmer.el ====================== The ‘dimmer.el’ library by Neil Okamoto can be configured to automatically dim the colors of inactive Emacs windows. To guarantee -consistent results with the Modus themes, we suggest some tweaks to the +consistent results with the Modus themes, I suggest some tweaks to the default styles, such as in this minimal setup: (use-package dimmer @@ -5907,7 +5770,7 @@ default styles, such as in this minimal setup: (dimmer-mode 1)) - Of the above, we strongly recommend the RGB color space because it is + Of the above, I strongly recommend the RGB color space because it is the one that remains faithful to the hueness of the colors used by the themes. Whereas the default CIELAB space has a tendency to distort colors in addition to applying the dim effect, which can be somewhat @@ -5926,7 +5789,7 @@ of this package: it draws too much attention to unfocused windows. File: modus-themes.info, Node: Note on display-fill-column-indicator-mode, Next: Note on highlight-parenthesesel, Prev: Note on dimmerel, Up: Notes on individual packages -10.7 Note on display-fill-column-indicator-mode +11.7 Note on display-fill-column-indicator-mode =============================================== The ‘display-fill-column-indicator-mode’ uses a typographic character to @@ -5934,7 +5797,7 @@ draw its line. This has the downside of creating a dashed line. The dashes are further apart depending on how tall the font's glyph height is and what integer the ‘line-spacing’ is set to. - At the theme level we eliminate this effect by making the character + At the theme level I eliminate this effect by making the character one pixel tall: the line is contiguous. Users who prefer the dashed line are advised to change the ‘fill-column-indicator’ face, as explained elsewhere in this document. For example: @@ -5947,7 +5810,7 @@ explained elsewhere in this document. For example: theme colors in code with modus-themes-with-colors. To make the line thicker, set the height to be equal to the base font -size instead of the one pixel we use. This is done by specifying a rate +size instead of the one pixel I use. This is done by specifying a rate instead of an absolute number, as in ‘:height 1.0’ versus ‘:height 1’. For example: @@ -5958,7 +5821,7 @@ For example: File: modus-themes.info, Node: Note on highlight-parenthesesel, Next: Note on mmm-modeel background colors, Prev: Note on display-fill-column-indicator-mode, Up: Notes on individual packages -10.8 Note on highlight-parentheses.el +11.8 Note on highlight-parentheses.el ===================================== The ‘highlight-parentheses’ package provides contextual coloration of @@ -5966,45 +5829,45 @@ surrounding parentheses, highlighting only those which are around the point. The package expects users to customize the applicable colors on their own by configuring certain variables. - To make the Modus themes work as expected with this, we need to use + To make the Modus themes work as expected with this, I need to use some of the techniques that are discussed at length in the various "Do-It-Yourself" (DIY) sections, which provide insight into the more advanced customization options of the themes. *note Advanced customization: Advanced customization. - In the following example, we are assuming that the user wants to (i) + In the following example, I am assuming that the user wants to (i) reuse color variables provided by the themes, (ii) be able to retain their tweaks while switching between ‘modus-operandi’ and ‘modus-vivendi’, and (iii) have the option to highlight either the foreground of the parentheses or the background as well. - We start by defining our own variable, which will serve as a toggle + I start by defining my own variable, which will serve as a toggle between foreground and background coloration styles: (defvar my-highlight-parentheses-use-background t "Prefer `highlight-parentheses-background-colors'.") - Then we can update our preference with this: + Then I can update my preference with this: ;; Set to nil to disable backgrounds. (setq my-highlight-parentheses-use-background nil) - To reuse colors from the themes, we must wrap our code in the -‘modus-themes-with-colors’ macro. Our implementation must interface -with the variables ‘highlight-parentheses-background-colors’ and/or + To reuse colors from the themes, I must wrap my code in the +‘modus-themes-with-colors’ macro. My implementation must interface with +the variables ‘highlight-parentheses-background-colors’ and/or ‘highlight-parentheses-colors’. - So we can have something like this (the docstring of + So I can have something like this (the docstring of ‘modus-themes-with-colors’ explains where the names of the colors can be found): (modus-themes-with-colors - ;; Our preference for setting either background or foreground + ;; My preference for setting either background or foreground ;; styles, depending on `my-highlight-parentheses-use-background'. (if my-highlight-parentheses-use-background - ;; Here we set color combinations that involve both a background + ;; Here I set color combinations that involve both a background ;; and a foreground value. (setq highlight-parentheses-background-colors (list bg-cyan-intense bg-magenta-intense @@ -6015,7 +5878,7 @@ found): green yellow)) - ;; And here we pass only foreground colors while disabling any + ;; And here I pass only foreground colors while disabling any ;; backgrounds. (setq highlight-parentheses-colors (list green-intense magenta-intense @@ -6026,12 +5889,12 @@ found): ;; Include this if you also want to make the parentheses bold: (set-face-attribute 'highlight-parentheses-highlight nil :inherit 'bold) - ;; Our changes must be evaluated before enabling the relevant mode, so + ;; My changes must be evaluated before enabling the relevant mode, so ;; this comes last. (global-highlight-parentheses-mode 1) - For our changes to persist while switching between the Modus themes, -we need to include them in a function which can then get passed to + For my changes to persist while switching between the Modus themes, I +need to include them in a function which can then get passed to ‘modus-themes-after-load-theme-hook’. This is the complete implementation: @@ -6045,11 +5908,11 @@ implementation: (defun my-modus-themes-highlight-parentheses (&rest _) (modus-themes-with-colors - ;; Our preference for setting either background or foreground + ;; My preference for setting either background or foreground ;; styles, depending on `my-highlight-parentheses-use-background'. (if my-highlight-parentheses-use-background - ;; Here we set color combinations that involve both a background + ;; Here I set color combinations that involve both a background ;; and a foreground value. (setq highlight-parentheses-background-colors (list bg-cyan-intense bg-magenta-intense @@ -6060,7 +5923,7 @@ implementation: green yellow)) - ;; And here we pass only foreground colors while disabling any + ;; And here I pass only foreground colors while disabling any ;; backgrounds. (setq highlight-parentheses-colors (list green-intense magenta-intense @@ -6071,7 +5934,7 @@ implementation: ;; Include this if you also want to make the parentheses bold: (set-face-attribute 'highlight-parentheses-highlight nil :inherit 'bold) - ;; Our changes must be evaluated before enabling the relevant mode, so + ;; My changes must be evaluated before enabling the relevant mode, so ;; this comes last. (global-highlight-parentheses-mode 1)) @@ -6085,7 +5948,7 @@ the post-load-theme phase. File: modus-themes.info, Node: Note on mmm-modeel background colors, Next: Note for prism, Prev: Note on highlight-parenthesesel, Up: Notes on individual packages -10.9 Note on mmm-mode.el background colors +11.9 Note on mmm-mode.el background colors ========================================== The faces used by ‘mmm-mode.el’ are expected to have a colorful @@ -6106,14 +5969,14 @@ of that library, it inevitably produces inaccessible color combinations. color-coding of the underlying background. As the Modus themes are designed with the express purpose of -conforming with the first point, we have to forgo the apparent -color-coding of the background elements. Instead we use subtle colors +conforming with the first point, I have to forgo the apparent +color-coding of the background elements. Instead I use subtle colors that do not undermine the legibility of the affected text while they still offer a sense of added context. Users who might prefer to fall below the minimum 7:1 contrast ratio -in relative luminance (the accessibility target we conform with), can -opt to configure the relevant faces on their own. +in relative luminance (the accessibility target I conform with), can opt +to configure the relevant faces on their own. *note Use theme colors in code with modus-themes-with-colors: Use theme colors in code with modus-themes-with-colors. @@ -6135,7 +5998,7 @@ the very high cost of degraded legibility. File: modus-themes.info, Node: Note for prism, Next: Note on company-mode overlay pop-up, Prev: Note on mmm-modeel background colors, Up: Notes on individual packages -10.10 Note on prism.el +11.10 Note on prism.el ====================== This package by Adam Porter, aka "alphapapa" or "github-alphapapa", @@ -6143,12 +6006,12 @@ implements an alternative to the typical coloration of code. Instead of highlighting the syntactic constructs, it applies color to different levels of depth in the code structure. - As ‘prism.el’ offers a broad range of customizations, we cannot style + As ‘prism.el’ offers a broad range of customizations, I cannot style it directly at the theme level: that would run contrary to the spirit of -the package. Instead, we may offer preset color schemes. Those should +the package. Instead, I may offer preset color schemes. Those should offer a starting point for users to adapt to their needs. - In the following code snippets, we employ the + In the following code snippets, I employ the ‘modus-themes-with-colors’ macro: *note Use theme colors in code with modus-themes-with-colors: Use theme colors in code with modus-themes-with-colors. @@ -6225,7 +6088,7 @@ examples with the 4, 8, 16 colors): File: modus-themes.info, Node: Note on company-mode overlay pop-up, Next: Note on ERC escaped color sequences, Prev: Note for prism, Up: Notes on individual packages -10.11 Note on company-mode overlay pop-up +11.11 Note on company-mode overlay pop-up ========================================= By default, the ‘company-mode’ pop-up that lists completion candidates @@ -6248,7 +6111,7 @@ instead of overlays.(1)(2) File: modus-themes.info, Node: Note on ERC escaped color sequences, Next: Note on powerline or spaceline, Prev: Note on company-mode overlay pop-up, Up: Notes on individual packages -10.12 Note on ERC escaped color sequences +11.12 Note on ERC escaped color sequences ========================================= The built-in IRC client ‘erc’ has the ability to colorize any text using @@ -6263,8 +6126,8 @@ minimum setup is this: erc-interpret-mirc-color t) As this allows users the chance to make arbitrary combinations, it is -impossible to guarantee a consistently high contrast ratio. All we can -we do is provide guidance on the combinations that satisfy the +impossible to guarantee a consistently high contrast ratio. All I can I +do is provide guidance on the combinations that satisfy the accessibility standard of the themes: Modus Operandi @@ -6286,7 +6149,7 @@ Emacs: <https://www.mirc.com/colors.html> File: modus-themes.info, Node: Note on powerline or spaceline, Next: Note on SHR colors, Prev: Note on ERC escaped color sequences, Up: Notes on individual packages -10.13 Note on powerline or spaceline +11.13 Note on powerline or spaceline ==================================== Both Powerline and Spaceline package users will likely need to use the @@ -6296,7 +6159,7 @@ and/or mode line setup. File: modus-themes.info, Node: Note on SHR colors, Next: Note on SHR fonts, Prev: Note on powerline or spaceline, Up: Notes on individual packages -10.14 Note on SHR colors +11.14 Note on SHR colors ======================== Emacs' HTML rendering library (‘shr.el’) may need explicit configuration @@ -6308,7 +6171,7 @@ webpage provides. File: modus-themes.info, Node: Note on SHR fonts, Next: Note on Ement colors and fonts, Prev: Note on SHR colors, Up: Notes on individual packages -10.15 Note on SHR fonts +11.15 Note on SHR fonts ======================= By default, packages that build on top of the Simple HTML Renderer @@ -6330,7 +6193,7 @@ for Org and others. File: modus-themes.info, Node: Note on Ement colors and fonts, Next: Note on pdf-tools link hints, Prev: Note on SHR fonts, Up: Notes on individual packages -10.16 Note on Ement colors and fonts +11.16 Note on Ement colors and fonts ==================================== The ‘ement.el’ library by Adam Porter (also known as "alphapapa") @@ -6342,14 +6205,14 @@ with: The contrast ratio of these colors is governed by another user option: ‘ement-room-prism-minimum-contrast’. By default, it is set to 6 -which is slightly below our nominal target. Try this instead: +which is slightly below my nominal target. Try this instead: (setq ement-room-prism-minimum-contrast 7) With regard to fonts, Ement depends on ‘shr’ (*note Note on SHR fonts: Note on SHR fonts.). - Since we are here, here is an excerpt from Ement's source code: + Since I am here, here is an excerpt from Ement's source code: (defcustom ement-room-prism-minimum-contrast 6 "Attempt to enforce this minimum contrast ratio for user faces. @@ -6359,14 +6222,14 @@ fonts: Note on SHR fonts.). :type 'number) Yes, I do approve of that default. Even a 4.5 (the WCAG AA rating) -would be a good baseline for many themes and/or user configurations. -Our target is the highest of the sort, though we do not demand that -everyone conforms with it. +would be a good baseline for many themes and/or user configurations. My +target is the highest of the sort, though I do not demand that everyone +conforms with it. File: modus-themes.info, Node: Note on pdf-tools link hints, Next: Note on the Notmuch logo, Prev: Note on Ement colors and fonts, Up: Notes on individual packages -10.17 Note on pdf-tools link hints +11.17 Note on pdf-tools link hints ================================== Hints are drawn by ImageMagick (https://imagemagick.org/), not Emacs, @@ -6415,7 +6278,7 @@ your initialization file after you've customized any faces. File: modus-themes.info, Node: Note on the Notmuch logo, Next: Note on goto-address-mode faces, Prev: Note on pdf-tools link hints, Up: Notes on individual packages -10.18 Note on the Notmuch logo +11.18 Note on the Notmuch logo ============================== By default, the "hello" buffer of Notmuch includes a header with the @@ -6428,7 +6291,7 @@ those buttons. Disabling the logo fixes the problem: File: modus-themes.info, Node: Note on goto-address-mode faces, Prev: Note on the Notmuch logo, Up: Notes on individual packages -10.19 Note on goto-address-mode faces +11.19 Note on goto-address-mode faces ===================================== The built-in ‘goto-address-mode’ uses heuristics to identify URLs and @@ -6453,10 +6316,10 @@ but also because they are often enclosed in angled brackets). File: modus-themes.info, Node: Frequently Asked Questions, Next: Contributing, Prev: Notes on individual packages, Up: Top -11 Frequently Asked Questions +12 Frequently Asked Questions ***************************** -In this section we provide answers related to some aspects of the Modus +In this section I provide answers related to some aspects of the Modus themes' design and application. * Menu: @@ -6471,15 +6334,15 @@ themes' design and application. File: modus-themes.info, Node: Is the contrast ratio about adjacent colors?, Next: What does it mean to avoid exaggerations?, Up: Frequently Asked Questions -11.1 Is the contrast ratio about adjacent colors? +12.1 Is the contrast ratio about adjacent colors? ================================================= The minimum contrast ratio in relative luminance that the themes conform with always refers to any given combination of background and foreground -colors. If we have some blue colored text next to a magenta one, both -against a white background, we do not mean to imply that blue:magenta is -7:1 in terms of relative luminance. Rather, we state that blue:white -and magenta:white each are 7:1 or higher. +colors. If I have some blue colored text next to a magenta one, both +against a white background, I do not mean to imply that blue:magenta is +7:1 in terms of relative luminance. Rather, I state that blue:white and +magenta:white each are 7:1 or higher. The point of reference is always the background. Because colors have about the same minimum distance in luminance from their backdrop, they @@ -6487,7 +6350,7 @@ necessarily are fairly close to each other in this measure. A possible blue:magenta combination would naturally be around 1:1 in contrast of the sort here considered. - To differentiate between sequential colors, we rely on hueness by + To differentiate between sequential colors, I rely on hueness by mapping contrasting hues to adjacent constructs, while avoiding exaggerations. A blue next to a magenta can be told apart regardless of their respective contrast ratio against their common background. @@ -6499,7 +6362,7 @@ the primary objective of the Modus themes. File: modus-themes.info, Node: What does it mean to avoid exaggerations?, Next: Why are colors mostly variants of blue magenta cyan?, Prev: Is the contrast ratio about adjacent colors?, Up: Frequently Asked Questions -11.2 What does it mean to avoid exaggerations? +12.2 What does it mean to avoid exaggerations? ============================================== The Modus themes are designed with restraint, so that their default @@ -6532,7 +6395,7 @@ harmonious rhythm. File: modus-themes.info, Node: Why are colors mostly variants of blue magenta cyan?, Next: What is the best setup for legibility?, Prev: What does it mean to avoid exaggerations?, Up: Frequently Asked Questions -11.3 Why are colors mostly variants of blue, magenta, cyan? +12.3 Why are colors mostly variants of blue, magenta, cyan? =========================================================== Due to the innate properties of color, some options are better than @@ -6543,7 +6406,7 @@ avoidance of exaggerations in design. *note What does it mean to avoid exaggerations?: What does it mean to avoid exaggerations?. - What we describe as color is a function of three distinct channels of + What I describe as color is a function of three distinct channels of light: red, green, blue. In hexadecimal RGB notation, a color value is read as three pairs of red, green, and blue light: ‘#RRGGBB’. Of those three, the most luminant is green, while the least luminant is blue. @@ -6552,7 +6415,7 @@ three, the most luminant is green, while the least luminant is blue. can be intermixed to give us six colors: red and green derive yellow, green and blue make cyan, red and blue turn into magenta. - We can test the luminance of each of those against white and black to + I can test the luminance of each of those against white and black to get a sense of how not all colors are equally good for accessibility (white is ‘#ffffff’, which means that all three light channels are fully luminated, while black is ‘#000000’ meaning that no light is present @@ -6569,11 +6432,11 @@ luminated, while black is ‘#000000’ meaning that no light is present *note Measure color contrast: DIY Measure color contrast. - By reading this table we learn that every color that has a high level + By reading this table I learn that every color that has a high level of green light (green, yellow, cyan) is virtually unreadable against a white background and, conversely, can be easily read against black. - We can then infer that red and blue, in different combinations, with + I can then infer that red and blue, in different combinations, with green acting as calibrator for luminance, will give us fairly moderate colors that pass the 7:1 target. Blue with a bit of green produce appropriate variants of cyan. Similarly, blue combined with some red @@ -6597,7 +6460,7 @@ against white: | #995500 | 5.75 | | #990099 | 7.46 | - We notice that equal values of red and blue light in ‘#990099’ + I notice that equal values of red and blue light in ‘#990099’ (magenta shade) do not lead to a considerable change in luminance compared with ‘#990000’ (red variant). Whereas less amount of green light in ‘#995500’ leads to a major drop in luminance relative to white. @@ -6605,15 +6468,15 @@ It follows that using the green channel of light to calibrate the luminance of colors is more effective than trying to do the same with either red or blue (the latter is the least effective in that regard). - When we need to work with several colors, it is always better to have -sufficient manoeuvring space, especially since we cannot pick arbitrary + When I need to work with several colors, it is always better to have +sufficient manoeuvring space, especially since I cannot pick arbitrary colors but only those that satisfy the accessibility objectives of the themes. - As for why we do not mostly use green, yellow, cyan for the dark + As for why I do not mostly use green, yellow, cyan for the dark theme, it is because those colors are far more luminant than their counterparts on the other side of the spectrum, so to ensure that they -all have about the same contrast ratios we would have to alter their +all have about the same contrast ratios I would have to alter their hueness considerably. In short, the effect would not be optimal as it would lead to exaggerations. Plus, it would make ‘modus-vivendi’ look completely different than ‘modus-operandi’, to the effect that the two @@ -6622,7 +6485,7 @@ could not be properly considered part of the same project. File: modus-themes.info, Node: What is the best setup for legibility?, Next: Are these color schemes?, Prev: Why are colors mostly variants of blue magenta cyan?, Up: Frequently Asked Questions -11.4 What is the best setup for legibility? +12.4 What is the best setup for legibility? =========================================== The Modus themes can be conceptually simplified as combinations of color @@ -6630,7 +6493,7 @@ values that account for relative luminance and inner harmony. Those qualities do not guarantee that every end-user will have the same experience, due to differences between people, but also because of variances in hardware capabilities and configurations. For the purposes -of this document, we may only provide suggestions pertaining to the +of this document, I may only provide suggestions pertaining to the latter case. ‘modus-operandi’ is best used outdoors or in a room that either gets @@ -6672,7 +6535,7 @@ need to be considered in full. File: modus-themes.info, Node: Are these color schemes?, Next: Port the Modus themes to other platforms?, Prev: What is the best setup for legibility?, Up: Frequently Asked Questions -11.5 Are these color schemes? +12.5 Are these color schemes? ============================= No, the Modus themes are not color schemes. @@ -6695,22 +6558,22 @@ Emacs uses constructs known as "faces" which allow the user/developer to specify where a given color will be used and whether it should be accompanied by other typographic or stylistic attributes. - By configuring the multitude of faces on offer we thus control both + By configuring the multitude of faces on offer I thus control both which colors are applied and how they appear in their context. When a package wants to render each instance of "foo" with the "bar" face, it is not requesting a specific color, which makes things considerably more -flexible as we can treat "bar" in its own right without necessarily -having to use some color value that we hardcoded somewhere. +flexible as I can treat "bar" in its own right without necessarily +having to use some color value that I hardcoded somewhere. Which brings us to the distinction between consistency and uniformity -where our goal is always the former: we want things to look similar -across all interfaces, but we must never force a visual identity where -that runs contrary to the functionality of the given interface. For -instance, all links are underlined by default yet there are cases such -as when viewing listings of emails in Gnus (and Mu4e, Notmuch) where (i) -it is already understood that one must follow the indicator or headline -to view its contents and (ii) underlining everything would make the -interface virtually unusable. +where my goal is always the former: I want things to look similar across +all interfaces, but I must never force a visual identity where that runs +contrary to the functionality of the given interface. For instance, all +links are underlined by default yet there are cases such as when viewing +listings of emails in Gnus (and Mu4e, Notmuch) where (i) it is already +understood that one must follow the indicator or headline to view its +contents and (ii) underlining everything would make the interface +virtually unusable. Again, one must exercise judgement in order to avoid discrimination, where "discrimination" refers to: @@ -6730,12 +6593,12 @@ error of treating different cases as if they were the same. The Modus themes prioritize "thematic consistency" over abstract harmony or regularity among their applicable colors. In concrete terms, -we do not claim that, say, our yellows are the best complements for our -blues because we generally avoid using complementary colors -side-by-side, so it is wrong to optimize for a decontextualised -blue+yellow combination. Not to imply that our colors do not work well -together because they do, just to clarify that consistency of context is -what themes must strive for, and that requires widening the scope of the +I do not claim that, say, my yellows are the best complements for my +blues because I generally avoid using complementary colors side-by-side, +so it is wrong to optimize for a decontextualised blue+yellow +combination. Not to imply that my colors do not work well together +because they do, just to clarify that consistency of context is what +themes must strive for, and that requires widening the scope of the design beyond the particularities of a color scheme. Long story short: color schemes and themes have different @@ -6744,7 +6607,7 @@ requirements. Please do not conflate the two. File: modus-themes.info, Node: Port the Modus themes to other platforms?, Prev: Are these color schemes?, Up: Frequently Asked Questions -11.6 Port the Modus themes to other platforms? +12.6 Port the Modus themes to other platforms? ============================================== There is no plan to port the themes to other platforms or text editors. @@ -6804,7 +6667,7 @@ them in their efforts. File: modus-themes.info, Node: Contributing, Next: Acknowledgements, Prev: Frequently Asked Questions, Up: Top -12 Contributing +13 Contributing *************** This section documents the canonical sources of the themes and the ways @@ -6819,7 +6682,7 @@ in which you can contribute to their ongoing development. File: modus-themes.info, Node: Sources of the themes, Next: Issues you can help with, Up: Contributing -12.1 Sources of the themes +13.1 Sources of the themes ========================== • Package name (GNU ELPA): ‘modus-themes’ @@ -6828,18 +6691,15 @@ File: modus-themes.info, Node: Sources of the themes, Next: Issues you can hel • Color palette: <https://protesilaos.com/emacs/modus-themes-colors> • Sample pictures: <https://protesilaos.com/emacs/modus-themes-pictures> - • Git repo on SourceHut: - <https://git.sr.ht/~protesilaos/modus-themes> - • Mirrors: - • GitHub: <https://github.com/protesilaos/modus-themes> - • GitLab: <https://gitlab.com/protesilaos/modus-themes> - • Mailing list: <https://lists.sr.ht/~protesilaos/modus-themes> - • Backronym: My Old Display Unexpectedly Sharpened ... themes + • Git repositories: + • GitHub: <https://github.com/protesilaos/modus-themes> + • GitLab: <https://gitlab.com/protesilaos/modus-themes> + • Backronym: My Old Display Unexpectedly Sharpened ... themes. File: modus-themes.info, Node: Issues you can help with, Next: Patches require copyright assignment to the FSF, Prev: Sources of the themes, Up: Contributing -12.2 Issues you can help with +13.2 Issues you can help with ============================= A few tasks you can help with by sending an email to the general @@ -6853,7 +6713,7 @@ modus-themes public mailing list • Suggest refinements to the color palette. • Help expand this document or any other piece of documentation. • Send patches for code refinements (if you need, ask me for help - with Git--we all start out as beginners). + with Git--I all start out as beginners). *note Patches require copyright assignment to the FSF: Patches require copyright assignment to the FSF. @@ -6871,7 +6731,7 @@ interest of the latter. File: modus-themes.info, Node: Patches require copyright assignment to the FSF, Prev: Issues you can help with, Up: Contributing -12.3 Patches require copyright assignment to the FSF +13.3 Patches require copyright assignment to the FSF ==================================================== Code contributions are most welcome. For any major edit (more than 15 @@ -6933,7 +6793,7 @@ you to make contributions to Emacs in general. File: modus-themes.info, Node: Acknowledgements, Next: GNU Free Documentation License, Prev: Contributing, Up: Top -13 Acknowledgements +14 Acknowledgements ******************* The Modus themes are a collective effort. Every bit of work matters. @@ -7520,73 +7380,69 @@ B.1 Function index * Menu: +* load-theme: Enable and load. (line 6) * modus-themes-contrast: DIY Measure color contrast. - (line 6) + (line 6) * modus-themes-define-derivative-command: Create convenience commands to load a derivative theme. - (line 10) + (line 10) * modus-themes-generate-palette: Complete example that also uses modus-themes-generate-palette. - (line 52) + (line 52) * modus-themes-get-all-known-themes: Determine what counts as a Modus theme. - (line 10) + (line 10) * modus-themes-get-color-value: Get a single color from the palette with modus-themes-get-color-value. - (line 6) -* modus-themes-get-themes: Option for which themes to rotate. - (line 17) -* modus-themes-get-themes <1>: Determine what counts as a Modus theme. - (line 16) + (line 6) +* modus-themes-get-themes: Option for which themes to toggle. + (line 13) +* modus-themes-get-themes <1>: Option for which themes to rotate. + (line 17) +* modus-themes-get-themes <2>: Option for which themes to rotate. + (line 21) +* modus-themes-get-themes <3>: Determine what counts as a Modus theme. + (line 16) * modus-themes-include-derivatives-mode: Determine what counts as a Modus theme. - (line 47) -* modus-themes-list-colors: Preview theme colors. - (line 6) -* modus-themes-list-colors-current: Preview theme colors. - (line 11) -* modus-themes-load-random: Enable and load. (line 94) -* modus-themes-load-random <1>: Disable other themes. - (line 15) -* modus-themes-load-random-dark: Enable and load. (line 106) -* modus-themes-load-random-light: Enable and load. (line 108) -* modus-themes-load-theme: Enable and load. (line 80) -* modus-themes-load-theme <1>: Disable other themes. - (line 15) -* modus-themes-preview-colors: Preview theme colors. - (line 19) -* modus-themes-preview-colors-current: Preview theme colors. - (line 19) + (line 47) +* modus-themes-list-colors: Preview theme colors. (line 6) +* modus-themes-list-colors-current: Preview theme colors. (line 11) +* modus-themes-load-random: Enable and load. (line 19) +* modus-themes-load-random <1>: Disable other themes. (line 15) +* modus-themes-load-random-dark: Enable and load. (line 47) +* modus-themes-load-random-light: Enable and load. (line 49) +* modus-themes-load-theme: Enable and load. (line 6) +* modus-themes-load-theme <1>: Disable other themes. (line 15) +* modus-themes-preview-colors: Preview theme colors. (line 19) +* modus-themes-preview-colors-current: Preview theme colors. (line 19) * modus-themes-preview-mode: Commands for the preview palette buffer. - (line 6) + (line 6) * modus-themes-preview-mode-copy-color: Commands for the preview palette buffer. - (line 20) + (line 20) * modus-themes-preview-mode-copy-entry: Commands for the preview palette buffer. - (line 27) + (line 27) * modus-themes-preview-mode-mark: Commands for the preview palette buffer. - (line 34) + (line 34) * modus-themes-preview-mode-mark-all: Commands for the preview palette buffer. - (line 34) + (line 34) * modus-themes-preview-mode-unmark: Commands for the preview palette buffer. - (line 34) + (line 34) * modus-themes-preview-mode-unmark-all: Commands for the preview palette buffer. - (line 34) -* modus-themes-rotate: Enable and load. (line 94) -* modus-themes-rotate <1>: Disable other themes. - (line 15) + (line 34) +* modus-themes-rotate: Enable and load. (line 19) +* modus-themes-rotate <1>: Disable other themes. (line 15) * modus-themes-rotate <2>: Option for which themes to rotate. - (line 6) -* modus-themes-select: Enable and load. (line 94) -* modus-themes-select <1>: Disable other themes. - (line 15) -* modus-themes-select-dark: Enable and load. (line 102) -* modus-themes-select-light: Enable and load. (line 104) + (line 6) +* modus-themes-select: Enable and load. (line 19) +* modus-themes-select <1>: Disable other themes. (line 15) +* modus-themes-select-dark: Enable and load. (line 43) +* modus-themes-select-light: Enable and load. (line 45) * modus-themes-theme: Build on top of the Modus themes. - (line 21) -* modus-themes-toggle: Enable and load. (line 94) -* modus-themes-toggle <1>: Disable other themes. - (line 15) + (line 21) +* modus-themes-toggle: Enable and load. (line 19) +* modus-themes-toggle <1>: Disable other themes. (line 15) * modus-themes-toggle <2>: Option for which themes to toggle. - (line 6) + (line 6) * modus-themes-wcag-formula: DIY Measure color contrast. - (line 6) + (line 6) * modus-themes-with-colors: Use theme colors in code with modus-themes-with-colors. - (line 10) + (line 10) File: modus-themes.info, Node: Variable index, Next: Concept index, Prev: Function index, Up: Indices @@ -7599,6 +7455,8 @@ B.2 Variable index * ~modus-themes-define-derivative-command-known-suffixes~: Create convenience commands to load a derivative theme. (line 24) +* custom-enabled-themes: Difference between loading and enabling. + (line 6) * modus-operandi-deuteranopia-palette-overrides: Palette overrides. (line 30) * modus-operandi-deuteranopia-palette-user: Palette extension. (line 24) @@ -7609,7 +7467,7 @@ B.2 Variable index * modus-operandi-tritanopia-palette-overrides: Palette overrides. (line 34) * modus-operandi-tritanopia-palette-user: Palette extension. (line 26) -* modus-themes-after-load-theme-hook: Enable and load. (line 86) +* modus-themes-after-load-theme-hook: Enable and load. (line 6) * modus-themes-bold-constructs: Bold constructs. (line 6) * modus-themes-common-palette-overrides: Palette overrides. (line 22) * modus-themes-common-palette-user: Palette extension. (line 16) @@ -7627,7 +7485,7 @@ B.2 Variable index * modus-themes-operandi-palette: Complete example that also uses modus-themes-generate-palette. (line 94) * modus-themes-org-blocks: Org mode blocks. (line 6) -* modus-themes-post-load-hook: Enable and load. (line 86) +* modus-themes-post-load-hook: Enable and load. (line 6) * modus-themes-preset-overrides-cooler: DIY Palette override presets. (line 29) * modus-themes-preset-overrides-faint: DIY Palette override presets. @@ -7698,7 +7556,7 @@ B.3 Concept index (line 6) * Innate color qualities of the palette: Why are colors mostly variants of blue magenta cyan?. (line 6) -* load-theme VS enable-theme: Differences between loading and enabling. +* load-theme VS enable-theme: Difference between loading and enabling. (line 6) * Org custom emphasis faces: DIY Custom Org emphasis faces. (line 6) @@ -7730,143 +7588,141 @@ B.3 Concept index Tag Table: Node: Top874 -Node: Overview9180 -Node: How do the themes look like11960 -Node: Learn about the latest changes12341 -Node: Installation12729 -Node: Install manually from source13640 -Node: Install from the archives14478 -Node: Install on GNU/Linux15092 -Node: Debian 11 Bullseye15583 -Node: GNU Guix16006 -Node: Dealing with byte compilation errors16304 -Node: Enable and load17486 -Node: The require-theme for built-in Emacs themes21784 -Node: Sample configuration22701 -Node: Differences between loading and enabling25154 -Node: Customization options27239 -Node: Disable other themes31023 -Node: Bold constructs32419 -Node: Italic constructs33291 -Node: Option for which themes to toggle34119 -Node: Option for which themes to rotate34882 -Node: Mixed fonts35912 -Node: Command prompts36966 -Node: Completion UIs38807 -Node: Org mode blocks41656 -Node: Heading styles42394 -Node: UI typeface46820 -Node: Palette overrides47793 -Node: Palette extension52171 -Node: Preview theme colors54647 -Node: Commands for the preview palette buffer56342 -Node: Use colors from the Modus themes palette58441 -Node: Get a single color from the palette with modus-themes-get-color-value59474 -Node: Use theme colors in code with modus-themes-with-colors61856 -Node: Advanced customization64208 -Node: DIY Palette override presets66022 -Node: DIY Add support for vc-annotate68854 -Node: DIY Add support for engrave-faces70380 -Node: DIY Stylistic variants using palette overrides80410 -Node: DIY Make the mode line borderless82469 -Node: DIY Make the active mode line colorful83844 -Node: DIY Make the tab bar more or less colorful86062 -Node: DIY Make the fringe invisible or another color87999 -Node: DIY Make links use subtle or no underlines89196 -Node: DIY Make prompts more or less colorful90314 -Node: DIY Make completion matches more or less colorful91637 -Node: DIY Make comments yellow and strings green95196 -Node: DIY Make code syntax use the old alt-syntax style96903 -Node: DIY Make use of alternative styles for code syntax100016 -Node: DIY Make matching parenthesis more or less intense103478 -Node: DIY Make box buttons more or less gray104850 -Node: DIY Make TODO and DONE more or less intense105863 -Node: DIY Make headings more or less colorful107364 -Node: DIY Make Org block colors more or less colorful109481 -Node: DIY Make Org agenda more or less colorful113938 -Node: DIY Make inline code in prose use alternative styles117113 -Node: DIY Make mail citations and headers more or less colorful119405 -Node: DIY Make the region preserve text colors plus other styles121805 -Node: DIY Make mouse highlights more or less colorful123361 -Node: DIY Make language underlines less colorful124374 -Node: DIY Make line numbers use alternative styles125526 -Node: DIY Make diffs use only a foreground127169 -Node: DIY Make deuteranopia diffs red and blue instead of yellow and blue130056 -Node: DIY More accurate colors in terminal emulators132528 -Node: DIY Range of color with terminal emulators133836 -Node: DIY Per-theme customization settings136628 -Node: DIY Do not extend the region background138061 -Node: DIY Add padding to the mode line138859 -Node: DIY Remap face with local value141787 -Node: DIY Font configurations for Org and others144328 -Ref: DIY Font configurations for Org and others-Footnote-1147310 -Node: DIY Configure bold and italic faces147497 -Node: DIY Custom Org todo keyword and priority faces152135 -Node: DIY Custom Org emphasis faces155876 -Node: DIY Use colored Org source blocks per language160753 -Node: DIY Measure color contrast165483 -Node: DIY Load theme depending on time of day168200 -Node: DIY Backdrop for pdf-tools169228 -Node: DIY Toggle themes without reloading them172423 -Node: DIY Use more spacious margins or padding in Emacs frames173772 -Node: DIY Custom hl-todo colors178009 -Node: DIY Add support for solaire-mode179826 -Node: DIY Add support for meow-mode182940 -Node: DIY Add support for combobulate184750 -Node: DIY Use a hook at the post-load-theme phase188373 -Node: DIY A theme-agnostic hook for theme loading190720 -Node: Build on top of the Modus themes193351 -Node: Complete example of a Modus derivative theme199616 -Node: Complete example of a package that is derived from Modus200776 -Node: Complete example of a private theme derived from Modus203924 -Node: Complete example of a custom theme with its own palette205701 -Node: Complete example that also uses modus-themes-generate-palette210464 -Node: Determine what counts as a Modus theme227455 -Node: Create convenience commands to load a derivative theme230898 -Node: Arrange to activate your derivative themes233238 -Node: Face coverage235327 -Node: Supported packages235789 -Node: Indirectly covered packages241831 -Node: Notes on individual packages243187 -Node: Note on calendarel weekday and weekend colors244289 -Node: Note on git-gutter in Doom Emacs245439 -Node: Note on php-mode multiline comments247963 -Node: Note on underlines in compilation buffers248725 -Node: Note on inline Latex in Org buffers249599 -Node: Note on dimmerel250210 -Node: Note on display-fill-column-indicator-mode251697 -Node: Note on highlight-parenthesesel253150 -Node: Note on mmm-modeel background colors259250 -Node: Note for prism261604 -Node: Note on company-mode overlay pop-up264818 -Ref: Note on company-mode overlay pop-up-Footnote-1265548 -Ref: Note on company-mode overlay pop-up-Footnote-2265615 -Node: Note on ERC escaped color sequences265670 -Ref: Note on ERC escaped color sequences-Footnote-1267100 -Node: Note on powerline or spaceline267210 -Node: Note on SHR colors267626 -Node: Note on SHR fonts268047 -Node: Note on Ement colors and fonts268736 -Node: Note on pdf-tools link hints270260 -Node: Note on the Notmuch logo272718 -Node: Note on goto-address-mode faces273252 -Node: Frequently Asked Questions274372 -Node: Is the contrast ratio about adjacent colors?275003 -Node: What does it mean to avoid exaggerations?276512 -Node: Why are colors mostly variants of blue magenta cyan?278362 -Node: What is the best setup for legibility?282783 -Node: Are these color schemes?285425 -Node: Port the Modus themes to other platforms?289079 -Node: Contributing291969 -Node: Sources of the themes292368 -Node: Issues you can help with293264 -Node: Patches require copyright assignment to the FSF294703 -Node: Acknowledgements296917 -Node: GNU Free Documentation License301746 -Node: Indices326909 -Node: Function index327088 -Node: Variable index332246 -Node: Concept index336963 +Node: Overview9162 +Node: How do the themes look like11987 +Node: Learn about the latest changes12368 +Node: Installation12755 +Node: Install manually from source13388 +Node: Install from source with package-vc-install14411 +Node: Install from GNU ELPA15175 +Node: Dealing with byte compilation errors15793 +Node: Sample configuration16940 +Node: The require-theme for built-in Emacs themes18694 +Node: Enable and load20206 +Node: Difference between loading and enabling22283 +Node: Customization options23075 +Node: Disable other themes26856 +Node: Bold constructs28270 +Node: Italic constructs29142 +Node: Option for which themes to toggle29970 +Node: Option for which themes to rotate30524 +Node: Mixed fonts31554 +Node: Command prompts32608 +Node: Completion UIs34449 +Node: Org mode blocks37298 +Node: Heading styles38035 +Node: UI typeface42460 +Node: Palette overrides43433 +Node: Palette extension47810 +Node: Preview theme colors50285 +Node: Commands for the preview palette buffer51980 +Node: Use colors from the Modus themes palette54079 +Node: Get a single color from the palette with modus-themes-get-color-value55112 +Node: Use theme colors in code with modus-themes-with-colors57493 +Node: Advanced customization59843 +Node: DIY Palette override presets61657 +Node: DIY Add support for vc-annotate64485 +Node: DIY Add support for engrave-faces66011 +Node: DIY Stylistic variants using palette overrides76038 +Node: DIY Make the mode line borderless78096 +Node: DIY Make the active mode line colorful79469 +Node: DIY Make the tab bar more or less colorful81685 +Node: DIY Make the fringe invisible or another color83620 +Node: DIY Make links use subtle or no underlines84815 +Node: DIY Make prompts more or less colorful85931 +Node: DIY Make completion matches more or less colorful87253 +Node: DIY Make comments yellow and strings green90809 +Node: DIY Make code syntax use the old alt-syntax style92513 +Node: DIY Make use of alternative styles for code syntax95622 +Node: DIY Make matching parenthesis more or less intense99083 +Node: DIY Make box buttons more or less gray100452 +Node: DIY Make TODO and DONE more or less intense101464 +Node: DIY Make headings more or less colorful102961 +Node: DIY Make Org block colors more or less colorful105075 +Node: DIY Make Org agenda more or less colorful109529 +Node: DIY Make inline code in prose use alternative styles112701 +Node: DIY Make mail citations and headers more or less colorful114989 +Node: DIY Make the region preserve text colors plus other styles117353 +Node: DIY Make mouse highlights more or less colorful118907 +Node: DIY Make language underlines less colorful119918 +Node: DIY Make line numbers use alternative styles121068 +Node: DIY Make diffs use only a foreground122709 +Node: DIY Make deuteranopia diffs red and blue instead of yellow and blue125590 +Node: DIY More accurate colors in terminal emulators128060 +Node: DIY Range of color with terminal emulators129368 +Node: DIY Per-theme customization settings132160 +Node: DIY Do not extend the region background133593 +Node: DIY Add padding to the mode line134390 +Node: DIY Remap face with local value137315 +Node: DIY Font configurations for Org and others139847 +Ref: DIY Font configurations for Org and others-Footnote-1142829 +Node: DIY Configure bold and italic faces143016 +Node: DIY Custom Org todo keyword and priority faces147650 +Node: DIY Custom Org emphasis faces151390 +Node: DIY Use colored Org source blocks per language156261 +Node: DIY Measure color contrast160990 +Node: DIY Load theme depending on time of day163707 +Node: DIY Backdrop for pdf-tools164734 +Node: DIY Toggle themes without reloading them167924 +Node: DIY Use more spacious margins or padding in Emacs frames169271 +Node: DIY Custom hl-todo colors173503 +Node: DIY Add support for solaire-mode175318 +Node: DIY Add support for meow-mode178425 +Node: DIY Add support for combobulate180235 +Node: DIY Use a hook at the post-load-theme phase183858 +Node: DIY A theme-agnostic hook for theme loading186205 +Node: Build on top of the Modus themes188832 +Node: Complete example of a Modus derivative theme195096 +Node: Complete example of a package that is derived from Modus196254 +Node: Complete example of a private theme derived from Modus199401 +Node: Complete example of a custom theme with its own palette201176 +Node: Complete example that also uses modus-themes-generate-palette205933 +Node: Determine what counts as a Modus theme222876 +Node: Create convenience commands to load a derivative theme226317 +Node: Arrange to activate your derivative themes228656 +Node: Face coverage230743 +Node: Supported packages231207 +Node: Indirectly covered packages237251 +Node: Notes on individual packages238609 +Node: Note on calendarel weekday and weekend colors239711 +Node: Note on git-gutter in Doom Emacs240861 +Node: Note on php-mode multiline comments243383 +Node: Note on underlines in compilation buffers244145 +Node: Note on inline Latex in Org buffers245019 +Node: Note on dimmerel245630 +Node: Note on display-fill-column-indicator-mode247115 +Node: Note on highlight-parenthesesel248566 +Node: Note on mmm-modeel background colors254645 +Node: Note for prism256996 +Node: Note on company-mode overlay pop-up260207 +Ref: Note on company-mode overlay pop-up-Footnote-1260937 +Ref: Note on company-mode overlay pop-up-Footnote-2261004 +Node: Note on ERC escaped color sequences261059 +Ref: Note on ERC escaped color sequences-Footnote-1262487 +Node: Note on powerline or spaceline262597 +Node: Note on SHR colors263013 +Node: Note on SHR fonts263434 +Node: Note on Ement colors and fonts264123 +Node: Note on pdf-tools link hints265643 +Node: Note on the Notmuch logo268101 +Node: Note on goto-address-mode faces268635 +Node: Frequently Asked Questions269755 +Node: Is the contrast ratio about adjacent colors?270385 +Node: What does it mean to avoid exaggerations?271890 +Node: Why are colors mostly variants of blue magenta cyan?273740 +Node: What is the best setup for legibility?278152 +Node: Are these color schemes?280793 +Node: Port the Modus themes to other platforms?284436 +Node: Contributing287326 +Node: Sources of the themes287725 +Node: Issues you can help with288466 +Node: Patches require copyright assignment to the FSF289904 +Node: Acknowledgements292118 +Node: GNU Free Documentation License296947 +Node: Indices322110 +Node: Function index322289 +Node: Variable index327251 +Node: Concept index332123 End Tag Table diff --git a/doc/modus-themes.org b/doc/modus-themes.org index 04e0723..1fc9f11 100644 --- a/doc/modus-themes.org +++ b/doc/modus-themes.org @@ -21,9 +21,9 @@ #+texinfo: @insertcopying -This manual, written by Protesilaos, describes the -customization options for the Modus themes, and provides every other -piece of information pertinent to them. +This manual, written by Protesilaos, describes the customization +options for the Modus themes, and provides every other piece of +information pertinent to them. The documentation furnished herein corresponds to stable version {{{stable-version}}}, released on {{{release-date}}}. Any reference @@ -69,39 +69,39 @@ modify this GNU manual.” :CUSTOM_ID: h:f0f3dbcb-602d-40cf-b918-8f929c441baf :END: -The Modus themes are designed for accessible readability. They -conform with the highest standard for color contrast between -combinations of background and foreground values. For small sized -text, this corresponds to the WCAG AAA standard, which specifies a -minimum rate of distance in relative luminance of 7:1. +The Modus themes are designed for accessible readability. They conform +with the highest standard for color contrast between combinations of +background and foreground values. For small sized text, this +corresponds to the WCAG AAA standard, which specifies a minimum rate +of distance in relative luminance of 7:1. The Modus themes consist of eight themes, divided into four subgroups. - Main themes :: ~modus-operandi~ is the project's main light theme, - while ~modus-vivendi~ is its dark counterpart. These two themes are - part of the project since its inception. They are designed to cover + while ~modus-vivendi~ is its dark counterpart. These two themes are + part of the project since its inception. They are designed to cover a broad range of needs and are, in the opinion of the author, the reference for what a highly legible "default" theme should look like. - Tinted themes :: ~modus-operandi-tinted~ and ~modus-vivendi-tinted~ - are variants of the two main themes. They slightly tone down the - intensity of the background and provide a bit more color variety. - ~modus-operandi-tinted~ has a set of base tones that are shades of - light ochre (earthly colors), while ~modus-vivendi-tinted~ gives a - night sky impression. + are variants of the two main themes. They tone down the intensity of + the background and rely on a marginally altered palette for + stylistic harmony. ~modus-operandi-tinted~ has a set of base tones + that are shades of light ochre (earthly colors), while + ~modus-vivendi-tinted~ gives a night sky impression. - Deuteranopia themes :: ~modus-operandi-deuteranopia~ and its companion ~modus-vivendi-deuteranopia~ are optimized for users with - red-green color deficiency. This means that they do not use red and + red-green color deficiency. This means that they do not use red and green hues for color-coding purposes, such as for diff removed and - added lines. Instead, they implement colors that are discernible by - users with deueteranopia or deuteranomaly (mostly yellow and blue - hues). + added lines. Instead, they implement colors that are discernible by + users with deueteranopia or deuteranomaly (those colors are mostly + shades of yellow and blue). - Tritanopia themes :: ~modus-operandi-tritanopia~ and its counterpart ~modus-vivendi-tritanopia~ are optimized for users with blue-yellow - color deficiency. The idea is the same as with the deuteranopia + color deficiency. The idea is the same as with the deuteranopia variants: color coding relies only on hues that are accessible to people with tritanopia or tritanomaly, namely, shades of red and cyan. @@ -111,10 +111,10 @@ themes strive to achieve as close to full face coverage as possible, while still targeting a curated list of well-maintained packages ([[#h:a9c8f29d-7f72-4b54-b74b-ddefe15d6a19][Face coverage]]). -The overarching objective of this project is to always offer -accessible color combinations. There shall never be a compromise on -this principle. If there arises an inescapable trade-off between -usability and stylistic considerations, we will always opt for the +The overarching objective of this project is to consistently offer +accessible color combinations. There shall never be a compromise on +this principle. If there arises an inescapable trade-off between +usability and stylistic considerations, I will always opt for the former. Starting with version 0.12.0 and onwards, the themes are built into GNU @@ -126,7 +126,7 @@ Emacs. :END: #+cindex: Screenshots -Check the web page with [[https://protesilaos.com/emacs/modus-themes-pictures/][the screen shots]]. Note that the themes are +Check the web page with [[https://protesilaos.com/emacs/modus-themes-pictures/][the screen shots]]. Note that the themes are highly customizable ([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization options]]). ** Learn about the latest changes @@ -135,8 +135,8 @@ highly customizable ([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization op :END: #+cindex: Changelog -Please refer to the [[https://protesilaos.com/emacs/modus-themes-changelog][web page with the change log]]. It is comprehensive -and covers everything that goes into every tagged release of the themes. +Please refer to the [[https://protesilaos.com/emacs/modus-themes-changelog][web page with the change log]]. It is comprehensive +and covers everything that goes into each tagged release of the themes. * Installation :PROPERTIES: @@ -144,25 +144,21 @@ and covers everything that goes into every tagged release of the themes. :END: The Modus themes are distributed with Emacs starting with version -28.1. On Emacs 27, they can be installed using Emacs' package manager -or manually from their code repository. There also exist packages for -distributions of GNU/Linux. +28.1. They are also available as a standalone package. -Emacs 28 ships with ~modus-themes~ version =1.6.0=. Emacs 29 includes -version =3.0.0=. Emacs 30 provides a newer, refactored version that -thoroughly refashions how the themes are implemented and customized. -Such major versions are not backward-compatible due to the limited -resources at the maintainer's disposal to support multiple versions of -Emacs and of the themes across the years. +Emacs 28 ships with ~modus-themes~ version =1.6.0=. Emacs 29 includes +version =3.0.0=. Emacs 30 provides version =4.4.0=, while Emacs 31 has +version =5.2.0= (soon to be updated to {{{development-version}}}). ** Install manually from source :PROPERTIES: :CUSTOM_ID: h:da3414b7-1426-46b8-8e76-47b845b76fd0 :END: -In the following example, we are assuming that your Emacs files are +In the following example, I am assuming that your Emacs files are stored in {{{file(~/.emacs.d)}}} and that you want to place the Modus -themes in {{{file(~/.emacs.d/modus-themes)}}}. +themes in {{{file(~/.emacs.d/modus-themes)}}}. If you are using Emacs +29, you do not need to do this manually ([[#h:0e667835-ade2-4f8c-8aa4-0983dbbbe45b][Install from source with ~package-vc-install~]]). 1. Get the source and store it in the desired path by running the following in the command line shell: @@ -178,66 +174,43 @@ themes in {{{file(~/.emacs.d/modus-themes)}}}. The themes are now ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]. -** Install from the archives +** Install from source with ~package-vc-install~ :PROPERTIES: -:CUSTOM_ID: h:c4b10085-149f-43e2-bd4d-347f33aee054 -:END: - -The ~modus-themes~ package is available from the GNU ELPA archive, which -is configured by default. - -Prior to querying any package archive, make sure to update the index, -with {{{kbd(M-x package-refresh-contents)}}}. Then all you need to do -is type {{{kbd(M-x package-install)}}} and specify the ~modus-themes~. - -Once installed, the themes are ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]. - -** Install on GNU/Linux -:PROPERTIES: -:CUSTOM_ID: h:da640eb1-95dd-4e86-bb4e-1027b27885f0 -:END: - -The themes are also available from the archives of some distributions of -GNU/Linux. These should correspond to a tagged release rather than -building directly from the latest Git commit. It all depends on the -distro's packaging policies. - -*** Debian 11 Bullseye -:PROPERTIES: -:CUSTOM_ID: h:7e570360-9ee6-4bc5-8c04-9dc11418a3e4 +:CUSTOM_ID: h:0e667835-ade2-4f8c-8aa4-0983dbbbe45b :END: -The themes are part of Debian 11 Bullseye. Get them with: +Starting with Emacs version 29, you can install the ~modus-themes~ +directly from source with the function ~package-vc-install~: -#+begin_src sh -sudo apt install elpa-modus-themes +#+begin_src emacs-lisp +;; Install from source. Do not do it if the package is already installed. +;; +;; To upgrade packages installed with `package-vc-install', use the +;; commands `package-vc-upgrade' or `package-vc-upgrade-all'. +(unless (package-installed-p 'modus-themes) + (package-vc-install "https://github.com/protesilaos/modus-themes.git")) #+end_src -They are now ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]. - -NOTE that Debian's package is severely out-of-date as of this writing -2022-07-24 09:57 +0300. - -*** GNU Guix +** Install from GNU ELPA :PROPERTIES: -:CUSTOM_ID: h:a4ca52cd-869f-46a5-9e16-4d9665f5b88e +:CUSTOM_ID: h:c4b10085-149f-43e2-bd4d-347f33aee054 :END: -Users of Guix can get the themes with this command: +The ~modus-themes~ package is available from the official GNU ELPA +archive. Prior to querying any package archive, make sure to update +the index, with {{{kbd(M-x package-refresh-contents)}}}. Then all you +need to do is type {{{kbd(M-x package-install)}}} and specify the +~modus-themes~ at the prompt. -#+begin_src sh -guix package -i emacs-modus-themes -#+end_src - -They are now ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]. +Once installed, the themes are ready for use: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]. ** Dealing with byte compilation errors :PROPERTIES: :CUSTOM_ID: h:e6268471-e847-4c9d-998f-49a83257b7f1 :END: -From time to time, we receive bug reports pertaining to errors with -byte compilation. These seldom have to do with faulty code in the +From time to time, I receive bug reports pertaining to errors with +byte compilation. These seldom have to do with faulty code in the themes: it might be a shortcoming of {{{file(package.el)}}}, some regression in the current development target of Emacs, a misconfiguration in an otherwise exotic setup, and the like. @@ -251,140 +224,61 @@ The common solution with a stable version of Emacs is to: For those building Emacs directly from source, the solution may involve reverting to an earlier commit in emacs.git. -At any rate, if you encounter such an issue please report it: we will -either fix the bug on our end if it is truly ours, or help forward it to -the relevant upstream maintainer. Whatever you do, please understand -that a build failure does not mean we are necessarily doing something -wrong. +At any rate, if you encounter such an issue please report it: I will +either fix the bug or help forward it to the relevant upstream +maintainer. Whatever you do, please understand that a build failure +does not mean I am necessarily doing something wrong. [[#h:6536c8d5-3f98-43ab-a787-b94120e735e8][Issues you can help with]]. -* Enable and load +* Sample configuration :PROPERTIES: -:CUSTOM_ID: h:3f3c3728-1b34-437d-9d0c-b110f5b161a9 +:CUSTOM_ID: h:e979734c-a9e1-4373-9365-0f2cd36107b8 :END: -#+cindex: Essential configuration - -NOTE that Emacs can load multiple themes, which typically produces -undesirable results and undoes the work of the designer. Use the -~disable-theme~ command if you are trying other themes beside the -Modus collection ([[#h:adb0c49a-f1f9-4690-868b-013a080eed68][Option for disabling other themes while loading Modus]]). - -Users of the built-in themes cannot ~require~ the package as usual -because there is no package to speak of. Instead, things are simpler -as built-in themes are considered safe. All one needs is to load the -theme of their preference by adding either form to their init file: - -#+begin_src emacs-lisp -(load-theme 'modus-operandi) ; Light theme -(load-theme 'modus-vivendi) ; Dark theme -#+end_src - -Remember that there are multiple Modus themes ([[#h:f0f3dbcb-602d-40cf-b918-8f929c441baf][Overview]]). Adapt the -above snippet accordingly. +#+cindex: use-package configuration +#+cindex: sample configuration -Users of packaged variants of the themes must add a few more lines to -ensure that everything works as intended. First, one has to require the -main library before loading one of the themes: +It is common for Emacs users to rely on ~use-package~ for declaring +package configurations in their setup ([[#h:b66b128d-54a4-4265-b59f-4d1ea2feb073][The ~require-theme~ for built-in Emacs themes]]): #+begin_src emacs-lisp -(require 'modus-themes) -#+end_src +(use-package modus-themes + :ensure t + :config + ;; Your customizations here. All customizations must be evaluated + ;; BEFORE loading the theme. Reload the theme for new customizations + ;; to take effect. + (setq modus-themes-italic-constructs t + modus-themes-bold-constructs nil) -One can activate a theme with something like the following expression, -replacing ~modus-operandi~ with their preferred Modus theme: + (modus-themes-load-theme 'modus-operandi) -#+begin_src emacs-lisp -(load-theme 'modus-operandi :no-confirm) + (define-key global-map (kbd "<f5>") #'modus-themes-toggle)) #+end_src -Changes to the available customization options must always be evaluated -before loading a theme ([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization Options]]). Reload a theme for -new changes to take effect. - -This is how a basic setup could look like ([[#h:b66b128d-54a4-4265-b59f-4d1ea2feb073][The require-theme for built-in Emacs themes]]): +The same without ~use-package~: #+begin_src emacs-lisp -;;; For the built-in themes which cannot use `require'. -(require-theme 'modus-themes) - -;; Add all your customizations prior to loading the themes. -(setq modus-themes-italic-constructs t - modus-themes-bold-constructs nil) - -;; Load the theme of your choice. -(load-theme 'modus-operandi) - -;; Optionally define a key to switch between Modus themes. Also check -;; the user option `modus-themes-to-toggle'. -(define-key global-map (kbd "<f5>") #'modus-themes-toggle) - - - -;;; For packaged versions which must use `require'. - (require 'modus-themes) -;; Add all your customizations prior to loading the themes +;; Your customizations here. All customizations must be evaluated +;; BEFORE loading the theme. Reload the theme for new customizations +;; to take effect. (setq modus-themes-italic-constructs t modus-themes-bold-constructs nil) -;; Load the theme of your choice. -(load-theme 'modus-operandi :no-confirm) +(modus-themes-load-theme 'modus-operandi) (define-key global-map (kbd "<f5>") #'modus-themes-toggle) #+end_src -[[#h:e979734c-a9e1-4373-9365-0f2cd36107b8][Sample configuration with and without use-package]]. - -To disable other themes before loading a Modus theme, use something -like this: - -#+begin_src emacs-lisp -(mapc #'disable-theme custom-enabled-themes) -(load-theme 'modus-operandi :no-confirm) -#+end_src - -#+findex: modus-themes-load-theme -Instead of using the basic ~load-theme~ function, users can rely on -the ~modus-themes-load-theme~. It accepts a single argument, which is -a symbol representing the Modus theme of choice, such as: - -#+begin_src emacs-lisp -(modus-themes-load-theme 'modus-operandi) -#+end_src - -#+vindex: modus-themes-after-load-theme-hook -#+vindex: modus-themes-post-load-hook -The ~modus-themes-load-theme~ takes care to disable other themes, if -the user opts in ([[#h:adb0c49a-f1f9-4690-868b-013a080eed68][Option for disabling other themes while loading Modus]]). -After loading the theme of choice, this function calls the -hook ~modus-themes-after-load-theme-hook~ (alias ~modus-themes-post-load-hook~). -Users can add their own functions to this hook to make further -customizations ([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]). - -#+findex: modus-themes-toggle -#+findex: modus-themes-select -#+findex: modus-themes-rotate -#+findex: modus-themes-load-random -The commands ~modus-themes-toggle~, ~modus-themes-rotate~, -~modus-themes-load-random~, and ~modus-themes-select~ use -~modus-themes-load-theme~ internally ([[#h:4fbfed66-5a89-447a-a07d-a03f6819c5bd][Option for which themes to toggle]]). -The aforementioned hold true for them as well. - -Convenience commands for loading only dark or light themes are: - -#+findex: modus-themes-select-dark -- ~modus-themes-select-dark~ - -#+findex: modus-themes-select-light -- ~modus-themes-select-light~ - -#+findex: modus-themes-load-random-dark -- ~modus-themes-load-random-dark~ +[[#h:e68560b3-7fb0-42bc-a151-e015948f8a35][Difference between loading and enabling]]. -#+findex: modus-themes-load-random-light -- ~modus-themes-load-random-light~ +Note: make sure not to customize the variable ~custom-theme-load-path~ +or ~custom-theme-directory~ after the themes' package declaration. +That will lead to failures in loading the files. If either or both of +those variables need to be changed, their values should be defined +before the package declaration of the themes. ** The ~require-theme~ for built-in Emacs themes :PROPERTIES: @@ -392,153 +286,132 @@ Convenience commands for loading only dark or light themes are: :END: The version of the Modus themes that is included in Emacs CANNOT use -the standard ~require~. This is because the built-in themes are not -included in the ~load-path~ (not my decision). The ~require-theme~ -function must be used in this case as a replacement. For example: +the standard ~require~ that ~use-package~ calls internally. This is +because the built-in themes are not included in the ~load-path~ (not +my decision). The ~require-theme~ function must be used instead. For +example: #+begin_src emacs-lisp (require-theme 'modus-themes) -;; All customizations here +;; Your customizations here. All customizations must be evaluated +;; BEFORE loading the theme. Reload the theme for new customizations +;; to take effect. (setq modus-themes-bold-constructs t modus-themes-italic-constructs t) -;; Load the theme of choice (built-in themes are always "safe" so they -;; do not need the `no-require' argument of `load-theme'). -(load-theme 'modus-operandi) +(modus-themes-load-theme 'modus-operandi) (define-key global-map (kbd "<f5>") #'modus-themes-toggle) #+end_src -** Sample configuration -:PROPERTIES: -:CUSTOM_ID: h:e979734c-a9e1-4373-9365-0f2cd36107b8 -:END: -#+cindex: use-package configuration -#+cindex: sample configuration - -What follows is a variant of what we demonstrate in the previous -section ([[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]). - -It is common for Emacs users to rely on ~use-package~ for declaring -package configurations in their setup. We use this as an example: +Same principle but with ~use-package~: #+begin_src emacs-lisp -;;; For the built-in themes which cannot use `require'. (use-package emacs :init - (require-theme 'modus-themes) ; `require-theme' is ONLY for the built-in Modus themes + ;; `require-theme' is ONLY for the built-in Modus themes + (require-theme 'modus-themes) :config - ;; Your customizations here. All customizations must evaluated - ;; BEFORE loading the theme. + ;; Your customizations here. All customizations must be evaluated + ;; BEFORE loading the theme. Reload the theme for new customizations + ;; to take effect. (setq modus-themes-italic-constructs t modus-themes-bold-constructs nil) - ;; Load the theme of your choice. (modus-themes-load-theme 'modus-operandi) (define-key global-map (kbd "<f5>") #'modus-themes-toggle)) +#+end_src +* Enable and load +:PROPERTIES: +:CUSTOM_ID: h:3f3c3728-1b34-437d-9d0c-b110f5b161a9 +:END: +#+cindex: Essential configuration +#+findex: load-theme +#+findex: modus-themes-load-theme +#+vindex: modus-themes-after-load-theme-hook +#+vindex: modus-themes-post-load-hook +Emacs provides the generic ~load-theme~ function to load the given +theme. Modus themes work with it as expected. Though I also define the +function ~modus-themes-load-theme~ which (i) calls the +~modus-themes-after-load-theme-hook~ (alias ~modus-themes-post-load-hook~) +and (ii) disables all other color themes if the relevant user option +is enabled ([[#h:adb0c49a-f1f9-4690-868b-013a080eed68][Option to disable other color themes when loading a Modus theme]]). -;;; For packaged versions which must use `require'. -(use-package modus-themes - :ensure t - :config - ;; Your customizations here. All customizations must evaluated - ;; BEFORE loading the theme. - (setq modus-themes-italic-constructs t - modus-themes-bold-constructs nil) +The ~modus-themes-after-load-theme-hook~ is specific to the Modus +themes. As such, users can rely on it to work as expected with the +functions and macros that Modus defines ([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]). - ;; Load the theme of your choice. - (modus-themes-load-theme 'modus-operandi) +#+findex: modus-themes-toggle +#+findex: modus-themes-select +#+findex: modus-themes-rotate +#+findex: modus-themes-load-random +The commands ~modus-themes-toggle~, ~modus-themes-rotate~, +~modus-themes-load-random~, and ~modus-themes-select~ use +~modus-themes-load-theme~ internally: - (define-key global-map (kbd "<f5>") #'modus-themes-toggle)) -#+end_src +- ~modus-themes-toggle~ :: Switches between two predefined Modus + themes ([[#h:4fbfed66-5a89-447a-a07d-a03f6819c5bd][Option for which themes to toggle]]). -The same without ~use-package~: +- ~modus-themes-rotate~ :: Cycles through a list of Modus themes in + rotation from left to right ([[#h:a10c0202-3683-4fad-9897-433c25e255f6][Option for which themes to rotate]]). -#+begin_src emacs-lisp -(require 'modus-themes) ; OR for the built-in themes: (require-theme 'modus-themes) +- ~modus-themes-select~ :: Selects a Modus theme using the minibuffer. + When called with a prefix argument ({{{kbd(C-u)}}} by default), it + first prompts for a light or dark subset and then loads a theme + accordingly. -;; Your customizations here. All customizations must evaluated -;; BEFORE loading the theme. -(setq modus-themes-italic-constructs t - modus-themes-bold-constructs nil) +- ~modus-themes-load-random~ :: Loads a Modus theme at random. When + called with a prefix argument, it behaves like the aforementioned + ~modus-themes-select~. -;; Load the theme of your choice: -(modus-themes-load-theme 'modus-operandi :no-confirm) +Convenience commands for loading only dark or light themes are: -(define-key global-map (kbd "<f5>") #'modus-themes-toggle) -#+end_src +#+findex: modus-themes-select-dark +- ~modus-themes-select-dark~ -[[#h:e68560b3-7fb0-42bc-a151-e015948f8a35][Differences between loading and enabling]]. +#+findex: modus-themes-select-light +- ~modus-themes-select-light~ -Note: make sure not to customize the variable ~custom-theme-load-path~ -or ~custom-theme-directory~ after the themes' package declaration. That -will lead to failures in loading the files. If either or both of those -variables need to be changed, their values should be defined before the -package declaration of the themes. +#+findex: modus-themes-load-random-dark +- ~modus-themes-load-random-dark~ -** Differences between loading and enabling +#+findex: modus-themes-load-random-light +- ~modus-themes-load-random-light~ + +** Difference between loading and enabling :PROPERTIES: :CUSTOM_ID: h:e68560b3-7fb0-42bc-a151-e015948f8a35 :END: #+cindex: load-theme VS enable-theme -The reason we recommend ~load-theme~ instead of the other option of -~enable-theme~ is that the former does a kind of "reset" on the face -specs. It quite literally loads (or reloads) the theme. Whereas the -~enable-theme~ function simply puts an already loaded theme to the top -of the list of enabled items, reusing whatever state was last loaded. - -As such, ~load-theme~ reads all customizations that may happen during -any given Emacs session: even after the initial setup of a theme. -Examples are calls to ~custom-set-faces~, as well as new values assigned -to the options the Modus themes provide ([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization Options]]). - -Our tests show that ~enable-theme~ does not read such variables anew, so -it might appear to the unsuspecting user that the themes are somehow -broken whenever they try to assign a new value to a customization option -or some face. - -This "reset" that ~load-theme~ brings about does, however, come at the -cost of being somewhat slower than ~enable-theme~. Users who have a -stable setup and who seldom update their variables during a given Emacs -session, are better off using something like this: - -#+begin_src emacs-lisp -(require 'modus-themes) - -;; Activate your desired themes here -(load-theme 'modus-operandi t t) -(load-theme 'modus-vivendi t t) - -;; Enable the preferred one -(enable-theme 'modus-operandi) -#+end_src +#+vindex: custom-enabled-themes +Emacs differentiates between loading and enabling a theme. The former +refers to the process of loading and evaluating the theme. While the +latter is about moving the given theme to the front of the +~custom-enabled-themes~. Concretely, loading a theme always aaccounts +for the user options and updates the presentation accordingly +([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization Options]]). Whereas enabling a theme will not perform any +further computations. [[#h:b40aca50-a3b2-4c43-be58-2c26fcd14237][Toggle themes without reloading them]]. [[#h:e979734c-a9e1-4373-9365-0f2cd36107b8][Sample configuration]]. -With the above granted, other sections of the manual discuss how to -configure custom faces, where ~load-theme~ is expected, though -~enable-theme~ could still apply in stable setups: - -[[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Use theme colors in code with modus-themes-with-colors]]. - * Customization options :PROPERTIES: :CUSTOM_ID: h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f :END: The Modus themes are highly configurable, though they should work well -without any further tweaks. We provide a variety of user options. +without any further tweaks. I provide a variety of user options. The following code block provides an overview. In addition to those variables, the themes support a comprehensive system of overrides: it can be used to make thoroughgoing changes to the looks of the themes -([[#h:34c7a691-19bb-4037-8d2f-67a07edab150][Option for palette overrides]]). We document everything at length in +([[#h:34c7a691-19bb-4037-8d2f-67a07edab150][Option for palette overrides]]). I document everything at length in the pages of this manual and also provide ready-to-use code samples. Remember that all customization options must be evaluated before loading @@ -584,11 +457,11 @@ reloaded for changes to take effect. (agenda-structure . (variable-pitch light 1.8)) (t . (1.1)))) -;; Remember that more (MUCH MORE) can be done with overrides, which we +;; Remember that more (MUCH MORE) can be done with overrides, which I ;; document extensively in this manual. #+end_src -** Option to disable other themes when loading a Modus theme +** Option to disable other color themes when loading a Modus theme :PROPERTIES: :ALT_TITLE: Disable other themes :DESCRIPTION: Determine whether loading a Modus themes disables all others @@ -596,7 +469,7 @@ reloaded for changes to take effect. :END: #+vindex: modus-themes-disable-other-themes -Brief: Disable all other themes when loading a Modus theme. +Brief: Disable all other color themes when loading a Modus theme. Symbol: ~modus-themes-disable-other-themes~ (=boolean= type) @@ -700,16 +573,9 @@ Symbol: ~modus-themes-to-toggle~ (=list= type) Default value: ='(modus-operandi modus-vivendi)= -Possible values: - -- ~modus-operandi~ -- ~modus-operandi-tinted~ -- ~modus-operandi-deuteranopia~ -- ~modus-operandi-tritanopia~ -- ~modus-vivendi~ -- ~modus-vivendi-tinted~ -- ~modus-vivendi-deuteranopia~ -- ~modus-vivendi-tritanopia~ +#+findex: modus-themes-get-themes +Possible values include all themes returned by the function +~modus-themes-get-themes~. ** Option for which themes to rotate :PROPERTIES: @@ -733,6 +599,7 @@ Possible values: - Any of the themes returned by the function ~modus-themes-get-themes~ ([[#h:86eb375b-9be4-43ce-879a-0686a524a63b][Build on top of the Modus themes]]). +#+findex: modus-themes-get-themes When the value is a list of themes, ~modus-themes-rotate~ will go through them from left to right. With an optional prefix argument ({{{kbd(C-u)}}} by default), it will move in reverse. If the value is @@ -917,7 +784,7 @@ Users can apply palette overrides to set a style that fits their preference (purple, blue, yellow, green, etc.). It is more flexible and more powerful ([[#h:f44cc6e3-b0f1-4a5e-8a90-9e48fa557b50][DIY Make Org block colors more or less colorful]]) -For the option to change the background of Org source blocks, we +For the option to change the background of Org source blocks, I provide the relevant setup ([[#h:8c842804-43b7-4287-b4e9-8c07d04d1f89][DIY Use colored Org source blocks per language]]). ** Option for the headings' overall style @@ -938,7 +805,7 @@ through 8) or ~t~, which pertains to the fallback style. The named keys =agenda-date= and =agenda-structure= apply to the Org agenda. Level 0 is a special heading: it is used for what counts as a document -title or equivalent, such as the =#+title= construct we find in Org +title or equivalent, such as the =#+title= construct I find in Org files. Levels 1-8 are regular headings. The =LIST-OF-VALUES= covers symbols that refer to properties, as @@ -1078,7 +945,7 @@ is done by assigning the ~variable-pitch~ face to the relevant items. :END: This section describes palette overrides in detail. For a simpler -alternative, use the presets we provide ([[#h:b0bc811c-227e-42ec-bf67-15e1f41eb7bc][Palette override presets]]). +alternative, use the presets I provide ([[#h:b0bc811c-227e-42ec-bf67-15e1f41eb7bc][Palette override presets]]). Each Modus theme specifies a color palette that declares named color values and semantic color mappings: @@ -1219,7 +1086,7 @@ definitions that are shared among the themes or on a per-theme basis. #+vindex: modus-themes-common-palette-user The common values are stored in the user option ~modus-themes-common-palette-user~. -As for per-theme variables, we have the following user options: +As for per-theme variables, I have the following user options: #+vindex: modus-operandi-palette-user - ~modus-operandi-palette-user~ @@ -1415,7 +1282,7 @@ An example with ~modus-operandi~ to show how this function behaves with/without overrides and when recursive mappings are introduced. #+begin_src emacs-lisp -;; Here we show the recursion of palette mappings. In general, it is +;; Here I show the recursion of palette mappings. In general, it is ;; better for the user to specify named colors to avoid possible ;; confusion with their configuration, though those still work as ;; expected. @@ -1441,7 +1308,7 @@ with/without overrides and when recursive mappings are introduced. #+cindex: Use colors from the palette anywhere [ Note that for common cases the following is not not needed. Just rely on - the comprehensive overrides we provide ([[#h:34c7a691-19bb-4037-8d2f-67a07edab150][Option for palette overrides]]). ] + the comprehensive overrides I provide ([[#h:34c7a691-19bb-4037-8d2f-67a07edab150][Option for palette overrides]]). ] #+findex: modus-themes-with-colors Advanced users may want to apply many colors from the palette of the @@ -1473,7 +1340,7 @@ same with ~modus-vivendi~ as the active theme: The ~modus-themes-with-colors~ has access to the whole palette of the active theme, meaning that it can instantiate both (i) named colors like =blue-warmer= and (ii) semantic color mappings like =warning=. -We provide commands to inspect those ([[#h:f4d4b71b-2ca5-4c3d-b0b4-9bfd7aa7fb4d][Preview theme colors]]). +I provide commands to inspect those ([[#h:f4d4b71b-2ca5-4c3d-b0b4-9bfd7aa7fb4d][Preview theme colors]]). Others sections in this manual show how to use the aforementioned macro ([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]). In practice, the use of a hook will @@ -1500,7 +1367,7 @@ they are labeled as "do-it-yourself" or "DIY". :END: This section shows how to refashion the themes by opting in to the -stylistic presets we provide. Those presets override the default +stylistic presets I provide. Those presets override the default color mappings to amplify, tone down, or refashion the overall coloration of the themes. @@ -1516,7 +1383,7 @@ With ~modus-themes-preset-overrides-faint~ the grays are toned down, gray backgrounds are removed from some contexts, and almost all accent colors are desaturated. It makes the themes less attention-grabbing. -On the opposite end of the stylistic spectrum, we have this +On the opposite end of the stylistic spectrum, I have this #+begin_src emacs-lisp ;; Always remember to reload the theme for changes to take effect! @@ -1541,7 +1408,7 @@ For some stylistic variation try the "cooler" and "warmer" presets: #+end_src Note that the user is not limited to those presets. The system of -overrides we provide makes it possible to tweak the value of each +overrides I provide makes it possible to tweak the value of each individual named color and to change how values are assigned to semantic color mappings ([[#h:34c7a691-19bb-4037-8d2f-67a07edab150][Option for palette overrides]]). Subsequent sections provide examples ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). @@ -1562,7 +1429,7 @@ the general idea (extra space for didactic purposes): (underline-paren-match fg-main) ;; And expand the preset here. Note that the ,@ works because - ;; we use the backtick for this list, instead of a straight + ;; I use the backtick for this list, instead of a straight ;; quote. ,@modus-themes-preset-overrides-intense)) #+end_src @@ -1615,9 +1482,9 @@ The ~engraved-faces~ package is used as part of an Org export process to produce decent colors in the output. Its default style though requires changes to use the colors of the active Modus theme. -In the code below we show how to map everything that ~engrave-faces~ +In the code below I show how to map everything that ~engrave-faces~ defines to the corresponding entry in the palette of the active Modus -theme. We then use a hook to ensure that the value is updated after we +theme. I then use a hook to ensure that the value is updated after I switch to another theme in the collection ([[#h:d87673fe-2ce1-4c80-a4b8-be36ca9f2d24][DIY Use a hook at the post-load-theme phase]]). #+begin_src emacs-lisp @@ -1710,7 +1577,7 @@ This section contains practical examples of overriding the palette of the themes ([[#h:34c7a691-19bb-4037-8d2f-67a07edab150][Option for palette overrides]]). Users can copy the code to their init file, evaluate it, and then re-load the theme for changes to take effect. To apply overrides at startup simply define them -before the call that loads the theme. Remember that we also provide +before the call that loads the theme. Remember that I also provide presets that are easier to apply ([[#h:b0bc811c-227e-42ec-bf67-15e1f41eb7bc][Palette override presets]]). *** DIY Make the mode line borderless @@ -1718,9 +1585,9 @@ presets that are easier to apply ([[#h:b0bc811c-227e-42ec-bf67-15e1f41eb7bc][Pal :CUSTOM_ID: h:80ddba52-e188-411f-8cc0-480ebd75befe :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). To -hide the border around the active and inactive mode lines, we need to +hide the border around the active and inactive mode lines, I need to set their color to that of the underlying background. [[#h:e8d781be-eefc-4a81-ac4e-5ed156190df7][Make the active mode line colorful]]. @@ -1749,9 +1616,9 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:e8d781be-eefc-4a81-ac4e-5ed156190df7 :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). -Here we show some snippets that apply different stylistic variants. +Here I show some snippets that apply different stylistic variants. Of course, it is possible to use theme-specific overrides to, say, have a blue mode line for ~modus-operandi~ and a red one for ~modus-vivendi~. @@ -1799,9 +1666,9 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:096658d7-a0bd-4a99-b6dc-9b20a20cda37 :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). -Here we show how to affect the colors of the built-in ~tab-bar-mode~ +Here I show how to affect the colors of the built-in ~tab-bar-mode~ and ~tab-line-mode~. For consistent theme-wide results, consider changing the mode line, @@ -1844,9 +1711,9 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:c312dcac-36b6-4a1f-b1f5-ab1c9abe27b0 :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). -Here we show how to make the fringe invisible or how to assign to it a +Here I show how to make the fringe invisible or how to assign to it a different color. The "fringe" is a small area to the right and left side of the Emacs window which shows indicators such as for truncation or continuation lines. @@ -1872,9 +1739,9 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:6c1d1dea-5cbf-4d92-b7bb-570a7a23ffe9 :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). In -this example, we showcase the special use of the ~unspecified~ symbol +this example, I showcase the special use of the ~unspecified~ symbol that underline mappings can read correctly. #+begin_src emacs-lisp @@ -1900,7 +1767,7 @@ Reload the theme for changes to take effect. This section contains practical examples of overriding the palette of the themes ([[#h:34c7a691-19bb-4037-8d2f-67a07edab150][Option for palette overrides]]). In the following code -block we show how to add or remove color from prompts. +block I show how to add or remove color from prompts. [[#h:db5a9a7c-2928-4a28-b0f0-6f2b9bd52ba1][Option for command prompt styles]]. @@ -1930,8 +1797,8 @@ Reload the theme for changes to take effect. :END: This section contains practical examples of overriding the palette of -the themes ([[#h:34c7a691-19bb-4037-8d2f-67a07edab150][Option for palette overrides]]). Here we demonstrate how -to activate background coloration for completion matches. We show +the themes ([[#h:34c7a691-19bb-4037-8d2f-67a07edab150][Option for palette overrides]]). Here I demonstrate how +to activate background coloration for completion matches. I show three different degrees of intensity. [[#h:f1c20c02-7b34-4c35-9c65-99170efb2882][Option for completion framework aesthetics]]. @@ -1939,7 +1806,7 @@ three different degrees of intensity. #+begin_src emacs-lisp ;; Add a nuanced background color to completion matches, while keeping ;; their foreground intact (foregrounds do not need to be specified in -;; this case, but we do it for didactic purposes). +;; this case, but I do it for didactic purposes). (setq modus-themes-common-palette-overrides '((fg-completion-match-0 blue) (fg-completion-match-1 magenta-warmer) @@ -2010,11 +1877,11 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:26f53daa-0065-48dc-88ab-6a718d16cd95 :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). In -previous versions of the themes, we provided an option for yellow-ish +previous versions of the themes, I provided an option for yellow-ish comments and green-ish strings. For some users, those were still not -good enough, as the exact values were hardcoded. Here we show how to +good enough, as the exact values were hardcoded. Here I show how to reproduce the effect, but also how to tweak it to one's liking. [[#h:c8767172-bf11-4c96-81dc-e736c464fc9c][Make code syntax use the old alt-syntax style]]. @@ -2047,12 +1914,12 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:c8767172-bf11-4c96-81dc-e736c464fc9c :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). In -this section we show how to reproduce what previous versions of the +this section I show how to reproduce what previous versions of the Modus themes provided as a stylistic alternative for code syntax. The -upside of using overrides for this purpose is that we can tweak the -style to our liking, but first let's start with its recreation: +upside of using overrides for this purpose is that I can tweak the +style to my liking, but first let's start with its recreation: #+begin_src emacs-lisp ;; The old "alt-syntax" (before version 4.0.0 of the Modus themes) @@ -2125,7 +1992,7 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:943063da-7b27-4ba4-9afe-f8fe77652fd1 :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). The idea here is to change how named colors are mapped to code syntax. Each of the following snippets give the ~modus-themes~ a different @@ -2209,10 +2076,10 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:259cf8f5-48ec-4b13-8a69-5d6387094468 :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). In -this code block we show how to change the background of matching -delimiters when ~show-paren-mode~ is enabled. We also demonstrate how +this code block I show how to change the background of matching +delimiters when ~show-paren-mode~ is enabled. I also demonstrate how to enable underlines for those highlights. #+begin_src emacs-lisp @@ -2239,7 +2106,7 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:4f6b6ca3-f5bb-4830-8312-baa232305360 :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). By default, the boxed buttons that appear in {{{kbd(M-x customize)}}} and related are distinct shades of gray. The following set of overrides @@ -2261,9 +2128,9 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:b57bb50b-a863-4ea8-bb38-6de2275fa868 :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). -Here we show how to affect just the =TODO= and =DONE= keywords that we +Here I show how to affect just the =TODO= and =DONE= keywords that I encounter in Org buffers. The idea is to make those pop out more or to subdue them. @@ -2295,10 +2162,10 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:11297984-85ea-4678-abe9-a73aeab4676a :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). -Here we show how to alter the looks of headings, such as in Org mode. -Using overrides here offers far more flexibility than what we could +Here I show how to alter the looks of headings, such as in Org mode. +Using overrides here offers far more flexibility than what I could achieve with previous versions of the themes: the user can mix and match styles at will. @@ -2345,9 +2212,9 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:f44cc6e3-b0f1-4a5e-8a90-9e48fa557b50 :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). Here -we show how to change the presentation of Org blocks (and other such +I show how to change the presentation of Org blocks (and other such blocks like Markdown fenced code sections, though the exact presentation depends on each major mode). @@ -2393,7 +2260,7 @@ color. #+end_src The previous examples differentiate the delimiter lines from the -block's contents. Though we can mimic the default aesthetic of a +block's contents. Though I can mimic the default aesthetic of a uniform background, while changing the applicable colors. Here are some nice combinations: @@ -2443,13 +2310,13 @@ until version 4.3.0. :CUSTOM_ID: h:a5af0452-a50f-481d-bf60-d8143f98105f :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). -Here we provide three distinct code blocks. The first adds +Here I provide three distinct code blocks. The first adds alternative and more varied colors to the Org agenda (and related). The second uses faint coloration. The third makes the agenda use various shades of blue. Mix and match at will, while also combining -these styles with what we show in the other chapters with practical +these styles with what I show in the other chapters with practical stylistic variants. #+begin_src emacs-lisp @@ -2520,11 +2387,11 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:bb5b396f-5532-4d52-ab13-149ca24854f1 :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). In -the following code block we show how to affect constructs such as -Org's verbatim, code, and macro entries. We also provide mappings for -tables, property drawers, tags, and code block delimiters, though we +the following code block I show how to affect constructs such as +Org's verbatim, code, and macro entries. I also provide mappings for +tables, property drawers, tags, and code block delimiters, though I do not show every possible permutation. - [[#h:b57bb50b-a863-4ea8-bb38-6de2275fa868][Make TODO and DONE more or less intense]]. @@ -2572,15 +2439,15 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:7da7a4ad-5d3a-4f11-9796-5a1abed0f0c4 :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). In -this section we show how to change the coloration of email message -headers and citations. Before we show the code, this is the anatomy +this section I show how to change the coloration of email message +headers and citations. Before I show the code, this is the anatomy of a message: #+begin_example message From: Protesilaos <info@protesilaos.com> -To: Modus-Themes Development <~protesilaos/modus-themes@lists.sr.ht> +To: Some Person <test@domain.sample> Subject: Test subject --- Headers above this line; message and citations below --- This is some sample text @@ -2589,7 +2456,7 @@ This is some sample text > Newer quote #+end_example -We thus have the following: +I thus have the following: #+begin_src emacs-lisp ;; Reduce the intensity of mail citations and headers @@ -2634,9 +2501,9 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:c8605d37-66e1-42aa-986e-d7514c3af6fe :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). -Here we show how to make the region respect the underlying text colors +Here I show how to make the region respect the underlying text colors or how to make the background more/less intense while combining it with an appropriate foreground value. @@ -2667,9 +2534,9 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:b5cab69d-d7cb-451c-8ff9-1f545ceb6caf :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). In -the following code block we show how to affect the semantic color +the following code block I show how to affect the semantic color mapping that covers mouse hover effects and related highlights: #+begin_src emacs-lisp @@ -2689,9 +2556,9 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:03dbd5af-6bae-475e-85a2-cec189f69598 :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). -Here we show how to affect the color of the underlines that are used +Here I show how to affect the color of the underlines that are used by code linters and prose spell checkers. #+begin_src emacs-lisp @@ -2715,9 +2582,9 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:b6466f51-cb58-4007-9ebe-53a27af655c7 :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). In -this section we show how to affect the ~display-line-numbers-mode~. +this section I show how to affect the ~display-line-numbers-mode~. #+begin_src emacs-lisp ;; Make line numbers less intense @@ -2750,13 +2617,13 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:b3761482-bcbf-4990-a41e-4866fb9dad15 :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). In -this section we show how to change diff buffers (e.g. in ~magit~) to -only use color-coded text without any added background. What we +this section I show how to change diff buffers (e.g. in ~magit~) to +only use color-coded text without any added background. What I basically do is to disable the applicable backgrounds and then intensify the foregrounds. Since the deuteranopia-optimized themes do -not use the red-green color coding, we make an extra set of +not use the red-green color coding, I make an extra set of adjustments for them by overriding their palettes directly instead of just using the "common" overrides. @@ -2785,8 +2652,8 @@ just using the "common" overrides. (bg-diff-context unspecified))) ;; Because deuteranopia cannot use the typical red-yellow-green -;; combination, we need to arrange for a yellow-purple-blue sequence. -;; Notice that the above covers the "common" overrides, so we do not +;; combination, I need to arrange for a yellow-purple-blue sequence. +;; Notice that the above covers the "common" overrides, so I do not ;; need to reproduce the whole list of them. (setq modus-operandi-deuteranopia-palette-overrides '((fg-added blue) @@ -2816,9 +2683,9 @@ Reload the theme for changes to take effect. :CUSTOM_ID: h:16389ea1-4cb6-4b18-9409-384324113541 :END: -This is one of our practical examples to override the semantic colors +This is one of my practical examples to override the semantic colors of the Modus themes ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][Stylistic variants using palette overrides]]). In -this section we show how to implement a red+blue color coding for +this section I show how to implement a red+blue color coding for diffs in the themes ~modus-operandi-deuteranopia~ and ~modus-vivendi-deuteranopia~. As those themes are optimized for users with red-green color deficiency, they do not use the typical red+green @@ -3008,7 +2875,7 @@ Reload the theme for changes to take effect. By default, the background of the ~region~ face extends from the end of the line to the edge of the window. To limit it to the end of -the line, we need to override the face's =:extend= attribute. Adding +the line, I need to override the face's =:extend= attribute. Adding this to the Emacs configuration file will suffice: #+begin_src emacs-lisp @@ -3028,7 +2895,7 @@ this to the Emacs configuration file will suffice: Protesilaos) for more than just the mode line. ] Emacs faces do not have a concept of "padding" for the space between -the text and its box boundaries. We can approximate the effect by +the text and its box boundaries. I can approximate the effect by adding a =:box= attribute, making its border several pixels thick, and using the mode line's background color for it. This way the thick border will not stand out and will appear as a continuation of the @@ -3050,7 +2917,7 @@ mode line. [[#h:d87673fe-2ce1-4c80-a4b8-be36ca9f2d24][Using a hook at the post-load-theme phase]]. The above has the effect of removing the border around the mode lines. -In older versions of the themes, we provided the option for a padded +In older versions of the themes, I provided the option for a padded mode line which could also have borders around it. Those were not real border, however, but an underline and an overline. Adjusting the above: @@ -3073,7 +2940,7 @@ above: (add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) #+end_src -The reason we no longer provide this option is because it depends on a +The reason I no longer provide this option is because it depends on a non-~nil~ value for ~x-underline-at-descent-line~. That variable affects ALL underlines, including those of links. The effect is intrusive and looks awkward in prose. @@ -3090,16 +2957,16 @@ Reload the theme for changes to take effect. :END: #+cindex: Remapping faces -There are cases where we need to change the buffer-local attributes of a -face. This might be because we have our own minor mode that reuses a +There are cases where I need to change the buffer-local attributes of a +face. This might be because I have my own minor mode that reuses a face for a particular purpose, such as a line selection tool that -activates ~hl-line-mode~, but we wish to keep it distinct from other +activates ~hl-line-mode~, but I wish to keep it distinct from other buffers. This is where ~face-remap-add-relative~ can be applied and may be combined with ~modus-themes-with-colors~ to deliver consistent results. [[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Use theme colors in code with modus-themes-with-colors]]. -In this example we will write a simple interactive function that adjusts +In this example I will write a simple interactive function that adjusts the background color of the ~region~ face. This is the sample code: #+begin_src emacs-lisp @@ -3128,7 +2995,7 @@ When ~my-rainbow-region~ is called interactively, it prompts for a color to use. The list of candidates is drawn from the car of each association in ~my-rainbow-region-colors~ (so "red", "green", etc.). -To extend this principle, we may write wrapper functions that pass a +To extend this principle, I may write wrapper functions that pass a color directly. Those can be useful in tandem with hooks. Consider this example: @@ -3139,11 +3006,11 @@ this example: (add-hook 'diff-mode-hook #'my-rainbow-region-magenta) #+end_src -Whenever we enter a ~diff-mode~ buffer, we now get a magenta-colored +Whenever I enter a ~diff-mode~ buffer, I now get a magenta-colored region. Perhaps you may wish to generalize those findings in to a set of -functions that also accept an arbitrary face. We shall leave the +functions that also accept an arbitrary face. I shall leave the experimentation up to you. Reload the theme for changes to take effect. @@ -3256,7 +3123,7 @@ instructions for all typeface tweaks. [[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. -In this example, we set the default font family to Fira Code, while we +In this example, I set the default font family to Fira Code, while I choose to render italics in the Hack typeface (obviously you need to pick fonts that work well together): @@ -3265,7 +3132,7 @@ pick fonts that work well together): (set-face-attribute 'italic nil :family "Hack") #+end_src -And here we play with different weights, using Source Code Pro: +And here I play with different weights, using Source Code Pro: #+begin_src emacs-lisp (set-face-attribute 'default nil :family "Source Code Pro" :height 110 :weight 'light) @@ -3296,7 +3163,7 @@ operations (~custom-set-faces~ follows the format used in the source code of the themes, which can make it easier to redefine faces in bulk). #+begin_src emacs-lisp -;; our generic function +;; my generic function (defun my-modes-themes-bold-italic-faces (&rest _) (set-face-attribute 'default nil :family "Source Code Pro" :height 110) (set-face-attribute 'bold nil :weight 'semibold)) @@ -3331,7 +3198,7 @@ priority cookies to better match their workflow. User options are As those are meant to be custom faces, it is futile to have the themes guess what each user wants to use, which keywords to target, and so on. -Instead, we can provide guidelines on how to customize things to one's +Instead, I can provide guidelines on how to customize things to one's liking with the intent of retaining the overall aesthetic of the themes. Please bear in mind that the end result of those is not controlled by @@ -3480,8 +3347,8 @@ green and yellow hues, respectively: "My underline emphasis for Org.") #+end_src -In the case of a strike-through effect, we have no generic face to -inherit from, so we can write it as follows to also change the +In the case of a strike-through effect, I have no generic face to +inherit from, so I can write it as follows to also change the foreground to a more subtle gray: #+begin_src emacs-lisp @@ -3494,7 +3361,7 @@ foreground to a more subtle gray: "My strike-through emphasis for Org.") #+end_src -Or we can just change the color of the line that strikes through the +Or I can just change the color of the line that strikes through the text to, for example, a shade of red: #+begin_src emacs-lisp @@ -3524,7 +3391,7 @@ entry in the palette. [[#h:f4d4b71b-2ca5-4c3d-b0b4-9bfd7aa7fb4d][Visualize the active Modus theme's palette]]. -Once we have defined the faces we need, we must update the +Once I have defined the faces I need, I must update the ~org-emphasis-alist~. Given that ~org-verbatim~ and ~org-code~ are already styled by the themes, it probably is best not to edit them: @@ -3551,7 +3418,7 @@ invoke {{{kbd(M-x org-mode-restart)}}}. In versions of the Modus themes before =4.4.0= there was an option to change the coloration of Org source blocks so that certain languages would have a distinctly colored background. This was not flexible -enough, because (i) we cannot cover all languages effectively and (ii) +enough, because (i) I cannot cover all languages effectively and (ii) the user had no choice over the =language --> color= mapping. As such, the old user option is no more. Users can use the following @@ -3709,7 +3576,7 @@ theme's color palette. :CUSTOM_ID: h:1d1ef4b4-8600-4a09-993c-6de3af0ddd26 :END: -While we do provide ~modus-themes-toggle~ to manually switch between the +While I do provide ~modus-themes-toggle~ to manually switch between the themes, users may also set up their system to perform such a task automatically at sunrise and sunset. @@ -3744,13 +3611,13 @@ the Modus Operandi theme. To introduce a distinction between the buffer's backdrop and the PDF page's background, the former must be rendered as some shade of gray. Ideally, ~pdf-tools~ would provide a face that the themes could support directly, though this does not seem to be -the case for the time being. We must thus employ the face remapping +the case for the time being. I must thus employ the face remapping technique that is documented elsewhere in this document to change the buffer-local value of the ~default~ face. [[#h:7a93cb6f-4eca-4d56-a85c-9dcd813d6b0f][Remap face with local value]]. -To remap the buffer's backdrop, we start with a function like this one: +To remap the buffer's backdrop, I start with a function like this one: #+begin_src emacs-lisp (defun my-pdf-tools-backdrop (&rest _) @@ -3770,9 +3637,9 @@ remapping function does not get evaluated anew whenever the theme changes, such as upon invoking {{{kbd(M-x modus-themes-toggle)}}} ([[#h:4fbfed66-5a89-447a-a07d-a03f6819c5bd][Option for which themes to toggle]]). -To have our face remapping adapt gracefully while switching between the -Modus themes, we need to also account for the current theme and control -the activation of ~pdf-view-midnight-minor-mode~. To which end we arrive +To have my face remapping adapt gracefully while switching between the +Modus themes, I need to also account for the current theme and control +the activation of ~pdf-view-midnight-minor-mode~. To which end I arrive at something like the following, which builds on the above example: #+begin_src emacs-lisp @@ -3833,7 +3700,7 @@ manual." (_ (error "No Modus theme is loaded; evaluate `modus-themes-load-themes' first")))) #+end_src -[[#h:e68560b3-7fb0-42bc-a151-e015948f8a35][Differences between loading and enabling]]. +[[#h:e68560b3-7fb0-42bc-a151-e015948f8a35][Difference between loading and enabling]]. Recall that ~modus-themes-toggle~ uses ~load-theme~. @@ -3870,7 +3737,7 @@ refers to the first frame that appears on Emacs startup. The 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: +In detail, first I use the same values for the two frame alist variables: #+begin_src emacs-lisp ;; This must go in the early-init.el so that it applies to the initial @@ -3881,10 +3748,10 @@ In detail, first we use the same values for the two frame alist variables: #+end_src What the ~dolist~ does is to call ~add-to-list~ for the two variables -we specify there. This economizes on typing. +I 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 +Then I define a function that makes the relevant faces invisible. +The reason I do this with a function is so I 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). @@ -3935,7 +3802,7 @@ defining their own theme-agnostic hook ([[#h:86f6906b-f090-46cc-9816-1fe8aeb3877 The ~hl-todo~ package provides the user option ~hl-todo-keyword-faces~: it specifies a pair of keyword and corresponding color value. The Modus themes configure that option in -the interest of legibility. While this works for our purposes, users +the interest of legibility. While this works for my purposes, users may still prefer to apply their custom values, in which case the following approach is necessary: @@ -3967,7 +3834,7 @@ Or include a ~let~ form, if needed: [[#h:d87673fe-2ce1-4c80-a4b8-be36ca9f2d24][Using a hook at the post-load-theme phase]]. -Normally, we do not touch user options, though this is an exception: +Normally, I do not touch user options, though this is an exception: otherwise the defaults are not always legible. Reload the theme for changes to take effect. @@ -3990,27 +3857,27 @@ However, the assumption that users opt in to this feature does not always hold true. There are cases where it is enabled by defaultsuch as in the popular Doom Emacs configuration. Thus, the unsuspecting user who loads ~modus-operandi~ or ~modus-vivendi~ without the requisite -customizations is getting a sub-par experience; an experience that we +customizations is getting a sub-par experience; an experience that I did not intend and cannot genuinely fix. -Because the Modus themes are meant to work everywhere, we cannot make an -exception for Doom Emacs and/or Solaire users. Furthermore, we shall +Because the Modus themes are meant to work everywhere, I cannot make an +exception for Doom Emacs and/or Solaire users. Furthermore, I shall not introduce hacks, such as by adding a check in all relevant faces to be adjusted based on Solaire or whatever other package. Hacks of this sort are unsustainable and penalize the entire userbase. Besides, the -themes are built into Emacs and we must keep their standard high. +themes are built into Emacs and I must keep their standard high. The fundamental constraint with Solaire is that Emacs does not have a real distinction between "content" and "UI" buffers. For themes to work with Solaire, they need to be designed around that package. Such is an -arrangement that compromises on our accessibility standards and/or -hinders our efforts to provide the best possible experience while using +arrangement that compromises on my accessibility standards and/or +hinders my efforts to provide the best possible experience while using the Modus themes. As such, ~solaire-mode~ is not---and will not be---supported by the Modus themes (or any other of my themes, for that matter). Users who want it must style the faces manually. Below is some sample code, based -on what we cover at length elsewhere in this manual: +on what I cover at length elsewhere in this manual: [[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]. @@ -4168,14 +4035,14 @@ without ~enable-theme-functions~). ([[#h:d87673fe-2ce1-4c80-a4b8-be36ca9f2d24][Using a hook at the post-load-theme phase]]). ] The themes are designed with the intent to be useful to Emacs users of -varying skill levels, from beginners to experts. This means that we try +varying skill levels, from beginners to experts. This means that I try to make things easier by not expecting anyone reading this document to be proficient in Emacs Lisp or programming in general. Such a case is with the use of ~modus-themes-after-load-theme-hook~, which runs after the ~modus-themes-load-theme~ function (used by the -command ~modus-themes-toggle~). We recommend using that hook for -advanced customizations, because (1) we know for sure that it is +command ~modus-themes-toggle~). I recommend using that hook for +advanced customizations, because (1) I know for sure that it is available once the themes are loaded, and (2) anyone consulting this manual, especially the sections on enabling and loading the themes, will be in a good position to benefit from that hook. @@ -4209,7 +4076,7 @@ it will likely not be able to benefit from macro calls that read the active theme, such as ~modus-themes-with-colors~. Not all Emacs themes have the same capabilities. -In this document, we cover ~modus-themes-after-load-theme-hook~ though +In this document, I 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). @@ -4293,7 +4160,7 @@ passing all the mandatory arguments, but not the optional ones: 'ef-summer-palette-overrides) #+end_src -Here we notice how ~ef-summer~ has ~modus-operandi-palette~ as its +Here I notice how ~ef-summer~ has ~modus-operandi-palette~ as its =CORE-PALETTE=. This means that if the ~ef-summer-palette~ lacks some entry, the theme will still work and it will inherit the style of ~modus-operandi~ for that specific element. @@ -4344,9 +4211,9 @@ corresponds to some named color in the palette of the active theme. [ For more context: [[#h:86eb375b-9be4-43ce-879a-0686a524a63b][Build on top of the Modus themes]]. ] -In this section, we show how to define a new Modus derivative theme. +In this section, I show how to define a new Modus derivative theme. In its simplest form, a theme is a file called =NAME-theme.el= in a -directory that is part of the ~custom-theme-load-path~. We show how to +directory that is part of the ~custom-theme-load-path~. I show how to do this for a package and for a private configuration: - [[#h:f2757848-ea41-4cd7-a04d-7e650555a59b][Complete example of a package that is derived from Modus]] @@ -4375,7 +4242,7 @@ individual theme files. For example, the family of themes that includes =prot-light-theme.el= and =prot-dark-theme.el= has a shared library which is -=prot-themes.el= and therein we find at least the following: +=prot-themes.el= and therein I find at least the following: #+begin_src emacs-lisp ;; Package headers here for prot-themes.el... @@ -4461,8 +4328,8 @@ file: #+end_src The function ~locate-user-emacs-file~ takes care to return a path -relative to where the user's init file is. If, say, we have -=~/.emacs.d/init.el= then we get =~/.emacs.d/my-custom-themes/=. +relative to where the user's init file is. If, say, I have +=~/.emacs.d/init.el= then I get =~/.emacs.d/my-custom-themes/=. Create the directory in that path. Then for each derivative Modus theme, write a new file of the form =NAME-theme.el=. If, for instance, @@ -4500,7 +4367,7 @@ The core and user palettes are among the arguments passed to the ~modus-themes-theme~ functions, as explained elsewhere in this manual ([[#h:86eb375b-9be4-43ce-879a-0686a524a63b][Build on top of the Modus themes]]). -In the following example, we are defining the ~prot-light~ theme in +In the following example, I am defining the ~prot-light~ theme in the =prot-light-theme.el= file. This theme declares itself as belonging to the =prot-themes= family. It is based on the ~modus-operandi-palette~ but then defines its own palette, the @@ -4530,7 +4397,7 @@ There is no limit to how comprehensive the user palette is. Depending on the requirements, this theme can make itself further customizable by the end user via theme-specific palette overrides. In -this case, we have the addition of a user option, which we could call +this case, I have the addition of a user option, which I could call anything though it makes sense to name it consistently like ~prot-light-palette-overrides~. #+begin_src emacs-lisp @@ -4555,7 +4422,7 @@ anything though it makes sense to name it consistently like ~prot-light-palette- 'prot-light-palette-overrides) #+end_src -In the above example, we have our ~prot-light~ theme which is like +In the above example, I have my ~prot-light~ theme which is like ~modus-operandi~ except three colors and which can now be customized further by the user via the ~prot-light-palette-overrides~ ([[#h:34c7a691-19bb-4037-8d2f-67a07edab150][Option for palette overrides]]). @@ -4615,8 +4482,8 @@ palette that can be passed to ~modus-themes-theme~ without necessarily depending on any of the core Modus palettes. I will walk you through the steps of working with something like the following code block. -[ We use color values from Solarized as an example for the rest of - this entry, naming them according to our conventions. ] +[ I use color values from Solarized as an example for the rest of + this entry, naming them according to my conventions. ] #+begin_src emacs-lisp (defvar modus-solarized-dark-palette @@ -4680,7 +4547,7 @@ The =BASE-COLORS= can be as short as follows: The only two mandatory entries in =BASE-COLORS= are =bg-main= and =fg-main= as shown above. In this scenario, the derived palette will get the job done, but will be very close to what Modus defines. The -more we add to the =BASE-COLORS=, the more well defined the character +more I add to the =BASE-COLORS=, the more well defined the character of the new palette will be. For example: #+begin_src emacs-lisp @@ -4698,9 +4565,9 @@ of the new palette will be. For example: This is already going to be a tolerable port of Solarized. If the =BASE-COLORS= provides =bg-main=, =fg-main=, and the six hues of -=red=, =green=, =yellow=, =blue=, =magenta=, =cyan=, we will get a new +=red=, =green=, =yellow=, =blue=, =magenta=, =cyan=, I will get a new palette that has no trace of the color values implemented by core -Modus. Though we can go further and greatly improve the results. +Modus. Though I can go further and greatly improve the results. #+vindex: modus-themes-operandi-palette #+vindex: modus-themes-vivendi-palette @@ -4711,7 +4578,7 @@ then the ~modus-themes-operandi-palette~ is used, otherwise it is ~modus-themes-vivendi-palette~. If all six of the aforementioned hues are present, the ~modus-themes-generate-palette~ will not calculate any more color values. It will use those to derive the relevant -permutations (e.g. blue backgrounds from the =blue= we give it). +permutations (e.g. blue backgrounds from the =blue= I give it). What also plays a role in the interal calculations is whether =bg-main= is a =cool= or =warm= color, meaning whether it is closer to @@ -4745,7 +4612,7 @@ cooler foreground values. Thus: (blue "#268BD2") (magenta "#D33682") (cyan "#2AA198")) - 'warm) ; but we want to use it with `warm' foregrounds + 'warm) ; but I want to use it with `warm' foregrounds ;; And here is the inverse of the above, now with the light version of ;; Solarized. @@ -4758,10 +4625,10 @@ cooler foreground values. Thus: (blue "#268BD2") (magenta "#D33682") (cyan "#2AA198")) - 'cool) ; but we want to use it with `cool' foregrounds + 'cool) ; but I want to use it with `cool' foregrounds #+end_src -This is now getting better, but we can go further. At this point users +This is now getting better, but I can go further. At this point users should be able to do the common work of taking a color scheme that was originally designed for terminal emulators and quickly turning it into a fully fledged Modus palette. All they need is to follow the naming @@ -4769,7 +4636,7 @@ convention for =bg-main=, =fg-main=, and then ={red,green,yellow,blue,magenta,cyan}{,-warmer,-cooler}=. Preview a palette to get the complete list ([[#h:f4d4b71b-2ca5-4c3d-b0b4-9bfd7aa7fb4d][Preview theme colors]]). And, again, remember that not all colors need to be defined in =BASE-COLORS= (e.g. -we could leave out ~magenta-cooler~ if we do not care about it). +I could leave out ~magenta-cooler~ if I do not care about it). The next optional parameter of ~modus-themes-generate-palette~ is the =CORE-PALETTE= it should use. This is to make explicit the decision @@ -4803,7 +4670,7 @@ but, again, users probably should leave this to ~nil~: (magenta "#D33682") (cyan "#2AA198")) nil ; COOL-OR-WARM-PREFERENCE is derived internally based on `bg-main' - 'modus-themes-vivendi-tritanopia-palette) ; we specifically want this as our CORE-PALETTE + 'modus-themes-vivendi-tritanopia-palette) ; I specifically want this as my CORE-PALETTE #+end_src With core Modus palettes, the =CORE-PALETTE= should not make much of a @@ -4815,11 +4682,11 @@ different semantic mappings. Finally, ~modus-themes-generate-palette~ has an optional =MAPPINGS= parameter. This is a list of semantic mappings where each entry is of the form =(NAME OTHER-NAME)= ([[#h:34c7a691-19bb-4037-8d2f-67a07edab150][Option for palette overrides]]). The -=NAME= has the same meaning as for the =BASE-COLORS= we have been +=NAME= has the same meaning as for the =BASE-COLORS= I have been examining all along, while =OTHER-NAME= is the symbol of another =NAME= that exists in the palette, hence the mapping. This manual contains lots of examples along those lines ([[#h:df1199d8-eaba-47db-805d-6b568a577bf3][DIY Stylistic variants using palette overrides]]). -For our purposes, we will modify some of the obvious elements of the +For my purposes, I will modify some of the obvious elements of the theme, namely, the cursor, mode lines, current line highlight, matching parentheses, and active region. @@ -4835,13 +4702,13 @@ matching parentheses, and active region. (cyan "#2AA198")) nil nil - ;; And here are our MAPPINGS where we can specify what values apply + ;; And here are my MAPPINGS where I can specify what values apply ;; to which semantic color. The `modus-themes-list-colors' shows ;; them all. ;; - ;; Note that in our BASE-COLORS above we never wrote what, say, + ;; Note that in my BASE-COLORS above I never wrote what, say, ;; `magenta-warmer' is: it is derived programmatically from the - ;; `magenta' we have there. Absent that, it would be taken from + ;; `magenta' I have there. Absent that, it would be taken from ;; the CORE-PALETTE. '((cursor magenta-warmer) (bg-hl-line bg-blue-nuanced) @@ -4862,8 +4729,8 @@ you already knew how to do this, ~modus-themes-generate-palette~ would not be of real value). The point is to start with something that works and then refine it one small step at a time. -We are now ready to try our Solarized themes, using the example of -doing this in our private configuration ([[#h:f2757848-ea41-4cd7-a04d-7e650555a59b][Complete example of a package that is derived from Modus]]). +I am now ready to try my Solarized themes, using the example of +doing this in my private configuration ([[#h:f2757848-ea41-4cd7-a04d-7e650555a59b][Complete example of a package that is derived from Modus]]). - Create two files, one is called =modus-solarized-dark-theme.el= (or however you want to identify it, but always keep =-theme.el= at the @@ -4886,8 +4753,8 @@ doing this in our private configuration ([[#h:f2757848-ea41-4cd7-a04d-7e650555a5 ;; Modus+Solarized dark (defvar modus-solarized-dark-palette (modus-themes-generate-palette - ;; We provide the two base colors of Solarized, plus most of its - ;; accents. These form the BASE-COLORS we pass as an argument. + ;; I provide the two base colors of Solarized, plus most of its + ;; accents. These form the BASE-COLORS I pass as an argument. ;; All other color values come from those. The BASE-COLORS here ;; are enough to generate a new palatte that has no traces of, say, ;; the `modus-vivendi' color values. @@ -4900,20 +4767,20 @@ doing this in our private configuration ([[#h:f2757848-ea41-4cd7-a04d-7e650555a5 (magenta "#D33682") (cyan "#2AA198")) ;; The COOL-OR-WARM-PREFERENCE is derived internally based on - ;; `bg-main'. We can pass it here if we feel strongly about it. + ;; `bg-main'. I can pass it here if I feel strongly about it. nil - ;; If we need to specify the CORE-PALETTE from where to inherit any - ;; missing colors and/or semantic mappings, we can give it here. + ;; If I need to specify the CORE-PALETTE from where to inherit any + ;; missing colors and/or semantic mappings, I can give it here. ;; Though nil is the appropriate starting point, as the code will ;; handle things internally. nil - ;; And here are our MAPPINGS where we can specify what values apply + ;; And here are my MAPPINGS where I can specify what values apply ;; to which semantic color. The `modus-themes-list-colors' shows ;; them all. ;; - ;; Note that in our BASE-COLORS above we never wrote what, say, + ;; Note that in my BASE-COLORS above I never wrote what, say, ;; `magenta-warmer' is: it is derived programmatically from the - ;; `magenta' we have there. Absent that, it would be taken from + ;; `magenta' I have there. Absent that, it would be taken from ;; the CORE-PALETTE. '((cursor magenta-warmer) (bg-hl-line bg-blue-nuanced) @@ -4940,8 +4807,8 @@ And the light variant: ;; Modus+Solarized light (defvar modus-solarized-light-palette (modus-themes-generate-palette - ;; We provide the two base colors of Solarized, plus most of its - ;; accents. These form the BASE-COLORS we pass as an argument. + ;; I provide the two base colors of Solarized, plus most of its + ;; accents. These form the BASE-COLORS I pass as an argument. ;; All other color values come from those. The BASE-COLORS here ;; are enough to generate a new palatte that has no traces of, say, ;; the `modus-operandi' color values. @@ -4954,20 +4821,20 @@ And the light variant: (magenta "#D33682") (cyan "#2AA198")) ;; The COOL-OR-WARM-PREFERENCE is derived internally based on - ;; `bg-main'. We can pass it here if we feel strongly about it. + ;; `bg-main'. I can pass it here if I feel strongly about it. nil - ;; If we need to specify the CORE-PALETTE from where to inherit any - ;; missing colors and/or semantic mappings, we can give it here. + ;; If I need to specify the CORE-PALETTE from where to inherit any + ;; missing colors and/or semantic mappings, I can give it here. ;; Though nil is the appropriate starting point, as the code will ;; handle things internally. nil - ;; And here are our MAPPINGS where we can specify what values apply + ;; And here are my MAPPINGS where I can specify what values apply ;; to which semantic color. The `modus-themes-list-colors' shows ;; them all. ;; - ;; Note that in our BASE-COLORS above we never wrote what, say, + ;; Note that in my BASE-COLORS above I never wrote what, say, ;; `magenta-warmer' is: it is derived programmatically from the - ;; `magenta' we have there. Absent that, it would be taken from + ;; `magenta' I have there. Absent that, it would be taken from ;; the CORE-PALETTE. '((cursor yellow-warmer) (bg-hl-line bg-red-nuanced) @@ -5041,7 +4908,7 @@ is =ef-themes=. All the Modus commands that switch between themes will thus only work with those Ef themes. #+findex: modus-themes-include-derivatives-mode -For our part, we define the ~modus-themes-include-derivatives-mode~. +For my part, I define the ~modus-themes-include-derivatives-mode~. It is how users can opt in to the all-inclusive conception of "Modus". In this scenario, every theme that is declared with the aforementioned ~modus-themes-theme~ will count as "Modus" and be available to all the @@ -5075,7 +4942,7 @@ accordingly." what is described herein. Just enable the ~modus-themes-include-derivatives-mode~. ] #+findex: modus-themes-define-derivative-command -In the previous section, we explored the mechanics of the +In the previous section, I explored the mechanics of the ~modus-themes-get-themes~ ([[#h:412e3017-81fe-4a95-97a6-225de1867757][Determine what counts as a Modus theme]]). Independent of that method, developers can use the macro ~modus-themes-define-derivative-command~ to define small wrappers for @@ -5127,7 +4994,7 @@ 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 +only work if the given theme file is already loaded. Otherwise my function is never called and the theme is never created. To this end, users need to call the function ~modus-themes-activate~ @@ -5141,7 +5008,7 @@ form, the activation looks as follows, assuming the theme's file (modus-themes-activate 'modus-solarized-dark) #+end_src -To load multiple themes at once we can define a function like the +To load multiple themes at once I can define a function like the following: #+begin_src emacs-lisp @@ -5577,8 +5444,8 @@ contiguous lines which may look nicer, but require a change to the foreground of the relevant faces to yield the desired color combinations. -Since this is Doom-specific, we urge users to apply changes in their -local setup. Below is some sample code, based on what we cover at +Since this is Doom-specific, I urge users to apply changes in their +local setup. Below is some sample code, based on what I cover at length elsewhere in this manual: [[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]. @@ -5690,7 +5557,7 @@ Remember to use {{{kbd(M-x org-mode-restart)}}} for changes to take effect. The {{{file(dimmer.el)}}} library by Neil Okamoto can be configured to automatically dim the colors of inactive Emacs windows. To guarantee -consistent results with the Modus themes, we suggest some tweaks to the +consistent results with the Modus themes, I suggest some tweaks to the default styles, such as in this minimal setup: #+begin_src emacs-lisp @@ -5703,7 +5570,7 @@ default styles, such as in this minimal setup: (dimmer-mode 1)) #+end_src -Of the above, we strongly recommend the RGB color space because it is +Of the above, I strongly recommend the RGB color space because it is the one that remains faithful to the hueness of the colors used by the themes. Whereas the default CIELAB space has a tendency to distort colors in addition to applying the dim effect, which can be somewhat @@ -5729,7 +5596,7 @@ draw its line. This has the downside of creating a dashed line. The dashes are further apart depending on how tall the font's glyph height is and what integer the ~line-spacing~ is set to. -At the theme level we eliminate this effect by making the character one +At the theme level I eliminate this effect by making the character one pixel tall: the line is contiguous. Users who prefer the dashed line are advised to change the ~fill-column-indicator~ face, as explained elsewhere in this document. For example: @@ -5743,7 +5610,7 @@ elsewhere in this document. For example: [[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Use theme colors in code with modus-themes-with-colors]]. To make the line thicker, set the height to be equal to the base font -size instead of the one pixel we use. This is done by specifying a rate +size instead of the one pixel I use. This is done by specifying a rate instead of an absolute number, as in =:height 1.0= versus =:height 1=. For example: @@ -5763,20 +5630,20 @@ surrounding parentheses, highlighting only those which are around the point. The package expects users to customize the applicable colors on their own by configuring certain variables. -To make the Modus themes work as expected with this, we need to use some +To make the Modus themes work as expected with this, I need to use some of the techniques that are discussed at length in the various "Do-It-Yourself" (DIY) sections, which provide insight into the more advanced customization options of the themes. [[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]. -In the following example, we are assuming that the user wants to (i) +In the following example, I am assuming that the user wants to (i) reuse color variables provided by the themes, (ii) be able to retain their tweaks while switching between ~modus-operandi~ and ~modus-vivendi~, and (iii) have the option to highlight either the foreground of the parentheses or the background as well. -We start by defining our own variable, which will serve as a toggle +I start by defining my own variable, which will serve as a toggle between foreground and background coloration styles: #+begin_src emacs-lisp @@ -5784,29 +5651,29 @@ between foreground and background coloration styles: "Prefer `highlight-parentheses-background-colors'.") #+end_src -Then we can update our preference with this: +Then I can update my preference with this: #+begin_src emacs-lisp ;; Set to nil to disable backgrounds. (setq my-highlight-parentheses-use-background nil) #+end_src -To reuse colors from the themes, we must wrap our code in the -~modus-themes-with-colors~ macro. Our implementation must interface with +To reuse colors from the themes, I must wrap my code in the +~modus-themes-with-colors~ macro. My implementation must interface with the variables ~highlight-parentheses-background-colors~ and/or ~highlight-parentheses-colors~. -So we can have something like this (the docstring of +So I can have something like this (the docstring of ~modus-themes-with-colors~ explains where the names of the colors can be found): #+begin_src emacs-lisp (modus-themes-with-colors - ;; Our preference for setting either background or foreground + ;; My preference for setting either background or foreground ;; styles, depending on `my-highlight-parentheses-use-background'. (if my-highlight-parentheses-use-background - ;; Here we set color combinations that involve both a background + ;; Here I set color combinations that involve both a background ;; and a foreground value. (setq highlight-parentheses-background-colors (list bg-cyan-intense bg-magenta-intense @@ -5817,7 +5684,7 @@ found): green yellow)) - ;; And here we pass only foreground colors while disabling any + ;; And here I pass only foreground colors while disabling any ;; backgrounds. (setq highlight-parentheses-colors (list green-intense magenta-intense @@ -5828,12 +5695,12 @@ found): ;; Include this if you also want to make the parentheses bold: (set-face-attribute 'highlight-parentheses-highlight nil :inherit 'bold) -;; Our changes must be evaluated before enabling the relevant mode, so +;; My changes must be evaluated before enabling the relevant mode, so ;; this comes last. (global-highlight-parentheses-mode 1) #+end_src -For our changes to persist while switching between the Modus themes, we +For my changes to persist while switching between the Modus themes, I need to include them in a function which can then get passed to ~modus-themes-after-load-theme-hook~. This is the complete implementation: @@ -5849,11 +5716,11 @@ implementation: (defun my-modus-themes-highlight-parentheses (&rest _) (modus-themes-with-colors - ;; Our preference for setting either background or foreground + ;; My preference for setting either background or foreground ;; styles, depending on `my-highlight-parentheses-use-background'. (if my-highlight-parentheses-use-background - ;; Here we set color combinations that involve both a background + ;; Here I set color combinations that involve both a background ;; and a foreground value. (setq highlight-parentheses-background-colors (list bg-cyan-intense bg-magenta-intense @@ -5864,7 +5731,7 @@ implementation: green yellow)) - ;; And here we pass only foreground colors while disabling any + ;; And here I pass only foreground colors while disabling any ;; backgrounds. (setq highlight-parentheses-colors (list green-intense magenta-intense @@ -5875,7 +5742,7 @@ implementation: ;; Include this if you also want to make the parentheses bold: (set-face-attribute 'highlight-parentheses-highlight nil :inherit 'bold) - ;; Our changes must be evaluated before enabling the relevant mode, so + ;; My changes must be evaluated before enabling the relevant mode, so ;; this comes last. (global-highlight-parentheses-mode 1)) @@ -5909,13 +5776,13 @@ There are two competing goals at play: color-coding of the underlying background. As the Modus themes are designed with the express purpose of conforming -with the first point, we have to forgo the apparent color-coding of the -background elements. Instead we use subtle colors that do not undermine +with the first point, I have to forgo the apparent color-coding of the +background elements. Instead I use subtle colors that do not undermine the legibility of the affected text while they still offer a sense of added context. Users who might prefer to fall below the minimum 7:1 contrast ratio in -relative luminance (the accessibility target we conform with), can opt +relative luminance (the accessibility target I conform with), can opt to configure the relevant faces on their own. [[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Use theme colors in code with modus-themes-with-colors]]. @@ -5947,13 +5814,13 @@ implements an alternative to the typical coloration of code. Instead of highlighting the syntactic constructs, it applies color to different levels of depth in the code structure. -As {{{file(prism.el)}}} offers a broad range of customizations, we +As {{{file(prism.el)}}} offers a broad range of customizations, I cannot style it directly at the theme level: that would run contrary -to the spirit of the package. Instead, we may offer preset color +to the spirit of the package. Instead, I may offer preset color schemes. Those should offer a starting point for users to adapt to their needs. -In the following code snippets, we employ the ~modus-themes-with-colors~ +In the following code snippets, I employ the ~modus-themes-with-colors~ macro: [[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Use theme colors in code with modus-themes-with-colors]]. These are the minimum recommended settings with 16 colors: @@ -6071,8 +5938,8 @@ separated by a comma. Like this =^C1,6=. The minimum setup is this: #+end_src As this allows users the chance to make arbitrary combinations, it is -impossible to guarantee a consistently high contrast ratio. All we can -we do is provide guidance on the combinations that satisfy the +impossible to guarantee a consistently high contrast ratio. All I can +I do is provide guidance on the combinations that satisfy the accessibility standard of the themes: + Modus Operandi :: Use foreground color 1 for all backgrounds from @@ -6141,7 +6008,7 @@ can be disabled with: The contrast ratio of these colors is governed by another user option: ~ement-room-prism-minimum-contrast~. By default, it is set to 6 which is -slightly below our nominal target. Try this instead: +slightly below my nominal target. Try this instead: #+begin_src emacs-lisp (setq ement-room-prism-minimum-contrast 7) @@ -6149,7 +6016,7 @@ slightly below our nominal target. Try this instead: With regard to fonts, Ement depends on ~shr~ ([[#h:e6c5451f-6763-4be7-8fdb-b4706a422a4c][Note on SHR fonts]]). -Since we are here, here is an excerpt from Ement's source code: +Since I am here, here is an excerpt from Ement's source code: #+begin_src emacs-lisp (defcustom ement-room-prism-minimum-contrast 6 @@ -6162,7 +6029,7 @@ This should be a reasonable number from, e.g. 0-7 or so." Yes, I do approve of that default. Even a 4.5 (the WCAG AA rating) would be a good baseline for many themes and/or user configurations. -Our target is the highest of the sort, though we do not demand that +My target is the highest of the sort, though I do not demand that everyone conforms with it. ** Note on pdf-tools link hints @@ -6261,7 +6128,7 @@ because they are often enclosed in angled brackets). :END: #+cindex: Frequently Asked Questions -In this section we provide answers related to some aspects of the Modus +In this section I provide answers related to some aspects of the Modus themes' design and application. ** Is the contrast ratio about adjacent colors? @@ -6272,9 +6139,9 @@ themes' design and application. The minimum contrast ratio in relative luminance that the themes conform with always refers to any given combination of background and foreground -colors. If we have some blue colored text next to a magenta one, both -against a white background, we do not mean to imply that blue:magenta is -7:1 in terms of relative luminance. Rather, we state that blue:white +colors. If I have some blue colored text next to a magenta one, both +against a white background, I do not mean to imply that blue:magenta is +7:1 in terms of relative luminance. Rather, I state that blue:white and magenta:white each are 7:1 or higher. The point of reference is always the background. Because colors have @@ -6283,7 +6150,7 @@ necessarily are fairly close to each other in this measure. A possible blue:magenta combination would naturally be around 1:1 in contrast of the sort here considered. -To differentiate between sequential colors, we rely on hueness by +To differentiate between sequential colors, I rely on hueness by mapping contrasting hues to adjacent constructs, while avoiding exaggerations. A blue next to a magenta can be told apart regardless of their respective contrast ratio against their common background. @@ -6338,7 +6205,7 @@ of exaggerations in design. [[#h:44284e1f-fab8-4c4f-92f0-544728a7c91e][What does it mean to avoid exaggerations?]] -What we describe as color is a function of three distinct channels of +What I describe as color is a function of three distinct channels of light: red, green, blue. In hexadecimal RGB notation, a color value is read as three pairs of red, green, and blue light: =#RRGGBB=. Of those three, the most luminant is green, while the least luminant is blue. @@ -6347,7 +6214,7 @@ The three basic colors represent each of the channels of light. They can be intermixed to give us six colors: red and green derive yellow, green and blue make cyan, red and blue turn into magenta. -We can test the luminance of each of those against white and black to +I can test the luminance of each of those against white and black to get a sense of how not all colors are equally good for accessibility (white is =#ffffff=, which means that all three light channels are fully luminated, while black is =#000000= meaning that no light is present @@ -6366,11 +6233,11 @@ luminated, while black is =#000000= meaning that no light is present [[#h:02e25930-e71a-493d-828a-8907fc80f874][Measure color contrast]]. -By reading this table we learn that every color that has a high level of +By reading this table I learn that every color that has a high level of green light (green, yellow, cyan) is virtually unreadable against a white background and, conversely, can be easily read against black. -We can then infer that red and blue, in different combinations, with +I can then infer that red and blue, in different combinations, with green acting as calibrator for luminance, will give us fairly moderate colors that pass the 7:1 target. Blue with a bit of green produce appropriate variants of cyan. Similarly, blue combined with some red @@ -6394,7 +6261,7 @@ the relative luminance of shades of red, yellow, magenta against white: | #990099 | 7.46 | #+end_example -We notice that equal values of red and blue light in =#990099= (magenta +I notice that equal values of red and blue light in =#990099= (magenta shade) do not lead to a considerable change in luminance compared with =#990000= (red variant). Whereas less amount of green light in =#995500= leads to a major drop in luminance relative to white. It follows that @@ -6402,15 +6269,15 @@ using the green channel of light to calibrate the luminance of colors is more effective than trying to do the same with either red or blue (the latter is the least effective in that regard). -When we need to work with several colors, it is always better to have -sufficient manoeuvring space, especially since we cannot pick arbitrary +When I need to work with several colors, it is always better to have +sufficient manoeuvring space, especially since I cannot pick arbitrary colors but only those that satisfy the accessibility objectives of the themes. -As for why we do not mostly use green, yellow, cyan for the dark theme, +As for why I do not mostly use green, yellow, cyan for the dark theme, it is because those colors are far more luminant than their counterparts on the other side of the spectrum, so to ensure that they all have about -the same contrast ratios we would have to alter their hueness +the same contrast ratios I would have to alter their hueness considerably. In short, the effect would not be optimal as it would lead to exaggerations. Plus, it would make ~modus-vivendi~ look completely different than ~modus-operandi~, to the effect that the two @@ -6427,7 +6294,7 @@ values that account for relative luminance and inner harmony. Those qualities do not guarantee that every end-user will have the same experience, due to differences between people, but also because of variances in hardware capabilities and configurations. For the purposes -of this document, we may only provide suggestions pertaining to the +of this document, I may only provide suggestions pertaining to the latter case. ~modus-operandi~ is best used outdoors or in a room that either gets @@ -6492,16 +6359,16 @@ Emacs uses constructs known as "faces" which allow the user/developer to specify where a given color will be used and whether it should be accompanied by other typographic or stylistic attributes. -By configuring the multitude of faces on offer we thus control both +By configuring the multitude of faces on offer I thus control both which colors are applied and how they appear in their context. When a package wants to render each instance of "foo" with the "bar" face, it is not requesting a specific color, which makes things considerably more -flexible as we can treat "bar" in its own right without necessarily -having to use some color value that we hardcoded somewhere. +flexible as I can treat "bar" in its own right without necessarily +having to use some color value that I hardcoded somewhere. Which brings us to the distinction between consistency and uniformity -where our goal is always the former: we want things to look similar -across all interfaces, but we must never force a visual identity where +where my goal is always the former: I want things to look similar +across all interfaces, but I must never force a visual identity where that runs contrary to the functionality of the given interface. For instance, all links are underlined by default yet there are cases such as when viewing listings of emails in Gnus (and Mu4e, Notmuch) where (i) @@ -6526,11 +6393,11 @@ not-so-obvious error of treating different cases as if they were the same. The Modus themes prioritize "thematic consistency" over abstract harmony -or regularity among their applicable colors. In concrete terms, we do -not claim that, say, our yellows are the best complements for our blues -because we generally avoid using complementary colors side-by-side, so +or regularity among their applicable colors. In concrete terms, I do +not claim that, say, my yellows are the best complements for my blues +because I generally avoid using complementary colors side-by-side, so it is wrong to optimize for a decontextualised blue+yellow combination. -Not to imply that our colors do not work well together because they do, +Not to imply that my colors do not work well together because they do, just to clarify that consistency of context is what themes must strive for, and that requires widening the scope of the design beyond the particularities of a color scheme. @@ -6617,12 +6484,10 @@ in which you can contribute to their ongoing development. + Change log: <https://protesilaos.com/emacs/modus-themes-changelog> + Color palette: <https://protesilaos.com/emacs/modus-themes-colors> + Sample pictures: <https://protesilaos.com/emacs/modus-themes-pictures> -+ Git repo on SourceHut: <https://git.sr.ht/~protesilaos/modus-themes> - - Mirrors: - + GitHub: <https://github.com/protesilaos/modus-themes> - + GitLab: <https://gitlab.com/protesilaos/modus-themes> -+ Mailing list: <https://lists.sr.ht/~protesilaos/modus-themes> -+ Backronym: My Old Display Unexpectedly Sharpened ... themes ++ Git repositories: + + GitHub: <https://github.com/protesilaos/modus-themes> + + GitLab: <https://gitlab.com/protesilaos/modus-themes> ++ Backronym: My Old Display Unexpectedly Sharpened ... themes. ** Issues you can help with :PROPERTIES: @@ -6640,7 +6505,7 @@ A few tasks you can help with by sending an email to the general + Suggest refinements to the color palette. + Help expand this document or any other piece of documentation. + Send patches for code refinements (if you need, ask me for help with - Git---we all start out as beginners). + Git---I all start out as beginners). [[#h:111773e2-f26f-4b68-8c4f-9794ca6b9633][Patches require copyright assignment to the FSF]]. |