diff --git a/.gitignore b/.gitignore index 4e14440..47917cb 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ *-autoloads.el *-pkg.el doc/fdl-1.3.txt +doc/modus-themes.texi diff --git a/doc/modus-themes.texi b/doc/modus-themes.texi deleted file mode 100644 index 7e92e13..0000000 --- a/doc/modus-themes.texi +++ /dev/null @@ -1,3424 +0,0 @@ -\input texinfo @c -*- texinfo -*- -@c %**start of header -@setfilename modus-themes.info -@settitle Modus themes for GNU Emacs -@documentencoding UTF-8 -@documentlanguage en -@set MAINTAINERSITE @uref{https://protesilaos.com,maintainer webpage} -@set MAINTAINER Protesilaos Stavrou -@set MAINTAINEREMAIL @email{info@protesilaos.com} -@set MAINTAINERCONTACT @uref{mailto:info@protesilaos.com,contact the maintainer} -@c %**end of header - -@copying -Copyright (C) 2020-2021 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this -document under the terms of the GNU Free Documentation License, -Version 1.3 or any later version published by the Free Software -Foundation; with no Invariant Sections, with no Front-Cover Texts, -and with no Back-Cover Texts. - -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Modus Themes: (modus-themes). Highly accessible themes (WCAG AAA). -@end direntry - -@finalout -@titlepage -@title Modus themes for GNU Emacs -@author Protesilaos Stavrou (@email{info@@protesilaos.com}) -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@ifnottex -@node Top -@top Modus themes for GNU Emacs - -@insertcopying - -This manual, written by Protesilaos Stavrou, describes the customization -options for the @code{modus-operandi} and @code{modus-vivendi} themes, and provides -every other piece of information pertinent to them. - -The documentation furnished herein corresponds to stable version -1.2.3, released on 2021-03-05. Any reference to a newer -feature which does not yet form part of the latest tagged commit, is -explicitly marked as such. - -Current development target is 1.3.0-dev. This manual was -built on 2021-03-05 19:43 +0200. - -@end ifnottex - -@menu -* Overview:: -* Installation:: -* Enable and load:: -* Customization Options:: -* Advanced customization (do-it-yourself):: -* Face coverage:: -* Notes for individual packages:: -* Contributing:: -* Acknowledgements:: -* Meta:: -* GNU Free Documentation License:: -* Indices:: - -@detailmenu ---- The Detailed Node Listing --- - -Overview - -* How do the themes look like:: -* Learn about the latest changes:: - -Installation - -* Install manually from source:: -* Install from the archives:: -* Install on GNU/Linux:: - -Install on GNU/Linux - -* Debian 11 Bullseye:: -* GNU Guix:: - -Enable and load - -* Sample configuration for use-package:: -* Differences between loading and enabling:: - -Customization Options - -* Bold constructs:: Toggle bold constructs in code -* Slanted constructs:: Toggle slanted constructs (italics) in code -* Syntax styles:: Choose the overall aesthetic of code syntax -* No mixed fonts:: Toggle mixing of font families -* Link styles:: Choose among several styles, with or without underline -* Command prompts:: Choose among plain, subtle, or intense prompts -* Mode line:: Choose among several styles, with or without borders -* Completion UIs:: Choose among standard, moderate, or opinionated looks -* Fringes:: Choose among invisible, subtle, or intense fringe styles -* Language checkers:: Control the style of language checkers/linters -* Line highlighting:: Toggle intense style for current line highlighting -* Line numbers:: Toggle subtle style for line numbers -* Matching parentheses:: Choose between various styles for matching delimiters/parentheses -* Active region:: Choose between various styles for the active region -* Diffs:: Choose among intense, desaturated, or text-only diffs -* Org mode blocks:: Choose among plain, grayscale, or rainbow styles -* Org agenda habits:: Choose among standard, simplified, or traffic light styles -* Heading styles:: Choose among several styles, also per heading level -* Scaled headings:: Toggle scaling of headings -* UI typeface:: Toggle the use of variable-pitch across the User Interface -* Headings' typeface:: Toggle the use of variable-pitch in headings - -Scaled headings - -* Scaled heading sizes:: Specify rate of increase for scaled headings - -Advanced customization (do-it-yourself) - -* Per-theme customization settings (DIY):: -* Case-by-case face specs using the themes' palette (DIY):: -* Face specs at scale using the themes' palette (DIY):: -* Override colors (DIY):: -* Font configurations for Org and others (DIY):: -* Custom Org user faces (DIY):: -* Measure color contrast (DIY):: -* Load theme depending on time of day:: -* A theme-agnostic hook for theme loading (DIY):: - -Face coverage - -* Supported packages:: Full list of covered face groups -* Indirectly covered packages:: - -Notes for individual packages - -* Note for display-fill-column-indicator-mode:: -* Note for mmm-mode.el background colors: Note for mmm-modeel background colors. -* Note for prism:: -* Note on company-mode overlay pop-up:: -* Note for ERC escaped color sequences:: -* Note for powerline or spaceline:: -* Note on SHR colors:: -* Note for Helm grep:: -* Note on vc-annotate-background-mode:: -* Note on pdf-tools link hints:: - -Contributing - -* Sources of the themes:: -* Issues you can help with:: -* Patches require copyright assignment to the FSF:: - -Indices - -* Function index:: -* Variable index:: -* Concept index:: - -@end detailmenu -@end menu - -@node Overview -@chapter Overview - -The Modus themes are designed for accessible readability. They conform -with the highest standard for color contrast between any given -combination of background and foreground values. This corresponds to -the WCAG AAA standard, which specifies a minimum rate of distance in -relative luminance of 7:1. - -Modus Operandi (@code{modus-operandi}) is a light theme, while Modus Vivendi -(@code{modus-vivendi}) is dark. Each theme's color palette is designed to meet -the needs of the numerous interfaces that are possible in the Emacs -computing environment. - -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 readability -and stylistic considerations, we will always opt for the former. - -To ensure that users have a consistently accessible experience, the -themes strive to achieve as close to full face coverage as possible -(@ref{Face coverage}). - -Starting with version 0.12.0 and onwards, the themes are built into GNU -Emacs. - -@menu -* How do the themes look like:: -* Learn about the latest changes:: -@end menu - -@node How do the themes look like -@section How do the themes look like - -@cindex Screenshots - -Check the web page with @uref{https://protesilaos.com/modus-themes-pictures/, the screen shots}. There are lots of scenarios -on display that draw attention to details and important aspects in the -design of the themes. They also showcase the numerous customization -options. - -@ref{Customization Options, , Customization options}. - -@node Learn about the latest changes -@section Learn about the latest changes - -@cindex Changelog - -Please refer to the @uref{https://protesilaos.com/modus-themes-changelog, web page with the change log}. It is comprehensive -and covers everything that goes into every tagged release of the themes. - -@node Installation -@chapter Installation - -The Modus themes are distributed with Emacs starting with version 28.1. -On older versions of Emacs, they can be installed using Emacs' package -manager or manually from their code repository. There also exist -packages for distributions of GNU/Linux. - -@menu -* Install manually from source:: -* Install from the archives:: -* Install on GNU/Linux:: -@end menu - -@node Install manually from source -@section Install manually from source - -In the following example, we are assuming that your Emacs files are -stored in @samp{~/.emacs.d} and that you want to place the Modus themes in -@samp{~/.emacs.d/modus-themes}. - -@enumerate -@item -Get the source and store it in the desired path by running the -following in the command line shell: -@end enumerate - -@example -$ git clone https://gitlab.com/protesilaos/modus-themes.git ~/.emacs.d/modus-themes -@end example - - -@enumerate -@item -Add that path to your known Elisp libraries' list, by placing this -snippet of Emacs Lisp in your init file (e.g. @file{init.el}): -@end enumerate - -@lisp -(add-to-list 'load-path "~/.emacs.d/modus-themes") -@end lisp - -The themes are now ready to be used: @ref{Enable and load}. - -@node Install from the archives -@section Install from the archives - -The @samp{modus-themes} package is available from the GNU ELPA archive, which -is configured by default. - -Prior to querying any package archive, make sure to have updated 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 @code{modus-themes}. - -Note that older versions of the themes used to be distributed as -standalone packages. This practice has been discontinued starting with -version 1.0.0 of this project. - -Once installed, the themes are ready to be used: @ref{Enable and load}. - -@node Install on GNU/Linux -@section 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:: -@end menu - -@node Debian 11 Bullseye -@subsection Debian 11 Bullseye - -The themes are part of Debian 11 Bullseye. Get them with: - -@example -sudo apt install elpa-modus-themes -@end example - -They are now ready to be used: @ref{Enable and load}. - -@node GNU Guix -@subsection GNU Guix - -Users of Guix can get the themes with this command: - -@example -guix package -i emacs-modus-themes -@end example - -They are now ready to be used: @ref{Enable and load}. - -@node Enable and load -@chapter Enable and load - -@findex modus-themes-load-themes -@findex modus-themes-toggle -@findex modus-themes-load-operandi -@findex modus-themes-load-vivendi -@cindex Essential configuration -@vindex modus-themes-after-load-theme-hook - -Users of the built-in themes can load and automatically enable the theme -of their preference by adding either form to their init file: - -@lisp -(load-theme 'modus-operandi) ; Light theme -(load-theme 'modus-vivendi) ; Dark theme -@end lisp - -This is all one needs. - -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 either theme: - -@lisp -(require 'modus-themes) -@end lisp - -Then it is recommended to load the individual theme files with the -helper function @code{modus-themes-load-themes}: - -@lisp -;; Load the theme files before enabling a theme (else you get an error). -(modus-themes-load-themes) -@end lisp - -Once the libraries that define the themes are enabled, one can activate -a theme with either of the following expressions: - -@lisp -(modus-themes-load-operandi) ; Light theme -;; OR -(modus-themes-load-vivendi) ; Dark theme -@end lisp - -Changes to the available customization options must always be evaluated -before loading a theme (@ref{Customization Options}). This is how a basic -setup could look like: - -@lisp -(require 'modus-themes) - -;; Your customisations here. For example: -(setq modus-themes-bold-constructs t - modus-themes-mode-line '3d) - -;; Load the theme files before enabling a theme (else you get an error). -(modus-themes-load-themes) - -;; Enable the theme of your preference: -(modus-themes-load-operandi) - -;; Optionally add a key binding for the toggle between the themes: -(define-key global-map (kbd "") #'modus-themes-toggle) -@end lisp - -@ref{Sample configuration for use-package}. - -With those granted, bear in mind a couple of technical points on -@code{modus-themes-load-operandi} and @code{modus-themes-load-vivendi}, as well as -@code{modus-themes-toggle} which relies on them: - -@enumerate -@item -Those functions call @code{load-theme}. Some users prefer to opt for -@code{enable-theme} instead (@ref{Differences between loading and enabling}). - -@item -The functions will run the @code{modus-themes-after-load-theme-hook} as -their final step. This can be employed for bespoke configurations -(@ref{Advanced customization (do-it-yourself)}). Experienced users may not -wish to rely on such a hook and the functions that run it: they may -prefer a custom solution (@ref{A theme-agnostic hook for theme loading (DIY), , A theme-agnostic hook for theme loading}). -@end enumerate - -@menu -* Sample configuration for use-package:: -* Differences between loading and enabling:: -@end menu - -@node Sample configuration for use-package -@section Sample configuration for use-package - -@cindex use-package configuration - -It is common for Emacs users to rely on @code{use-package} for declaring -package configurations in their setup. We use this as an example: - -@lisp -(use-package modus-themes - :ensure ; omit this to use the built-in themes - :init - ;; Add all your customizations prior to loading the themes - (setq modus-themes-slanted-constructs t - modus-themes-bold-constructs nil) - - ;; Load the theme files before enabling a theme (else you get an error). - (modus-themes-load-themes) - :config - ;; Load the theme of your choice: - (modus-themes-load-operandi) ;; OR (modus-themes-load-vivendi) - :bind ("" . modus-themes-toggle)) -@end lisp - -@ref{Differences between loading and enabling}. - -Note: make sure not to customize the variable @code{custom-theme-load-path} -or @code{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. - -@node Differences between loading and enabling -@section Differences between loading and enabling - -@cindex load-theme VS enable-theme - -The reason we recommend @code{load-theme} instead of the other option of -@code{enable-theme} is that the former does a kind of ``reset'' on the face -specs. It quite literally loads (or re-loads) the theme. Whereas the -latter simply puts an already loaded theme at the top of the list of -enabled items, re-using whatever state was last loaded. - -As such, @code{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 @code{custom-set-faces}, as well as new values assigned -to the options the Modus themes provide (@ref{Customization Options}). - -Our tests show that @code{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 @code{load-theme} conducts does, however, come at the cost -of being somewhat slower than @code{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: - -@lisp -(require 'modus-themes) -(load-theme 'modus-operandi t t) -(load-theme 'modus-vivendi t t) - -(enable-theme 'modus-operandi) ;; OR (enable-theme 'modus-vivendi) -@end lisp - -@ref{Sample configuration for use-package}. - -With the above granted, other sections of the manual discuss how to -configure custom faces, where @code{load-theme} is expected, though -@code{enable-theme} could still apply in stable setups: - -@ref{Case-by-case face specs using the themes' palette (DIY), , Case-by-case face specs using the themes' palette}. - -@ref{Face specs at scale using the themes' palette (DIY), , Face specs at scale using the themes' palette}. - -@node Customization Options -@chapter Customization Options - -The Modus themes are highly configurable, though they should work well -without any further tweaks. By default, all customization options are -set to nil. - -Remember that all customization options must be evaluated before loading -a theme (@ref{Enable and load}). - -@menu -* Bold constructs:: Toggle bold constructs in code -* Slanted constructs:: Toggle slanted constructs (italics) in code -* Syntax styles:: Choose the overall aesthetic of code syntax -* No mixed fonts:: Toggle mixing of font families -* Link styles:: Choose among several styles, with or without underline -* Command prompts:: Choose among plain, subtle, or intense prompts -* Mode line:: Choose among several styles, with or without borders -* Completion UIs:: Choose among standard, moderate, or opinionated looks -* Fringes:: Choose among invisible, subtle, or intense fringe styles -* Language checkers:: Control the style of language checkers/linters -* Line highlighting:: Toggle intense style for current line highlighting -* Line numbers:: Toggle subtle style for line numbers -* Matching parentheses:: Choose between various styles for matching delimiters/parentheses -* Active region:: Choose between various styles for the active region -* Diffs:: Choose among intense, desaturated, or text-only diffs -* Org mode blocks:: Choose among plain, grayscale, or rainbow styles -* Org agenda habits:: Choose among standard, simplified, or traffic light styles -* Heading styles:: Choose among several styles, also per heading level -* Scaled headings:: Toggle scaling of headings -* UI typeface:: Toggle the use of variable-pitch across the User Interface -* Headings' typeface:: Toggle the use of variable-pitch in headings -@end menu - -@node Bold constructs -@section Option for more bold constructs - -@vindex modus-themes-bold-constructs - -Symbol: @code{modus-themes-bold-constructs} - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{t} -@end enumerate - -The default is to use a bold typographic weight only when it is -required. - -With a non-nil value (@samp{t}) display several syntactic constructs in bold -weight. This concerns keywords and other important aspects of code -syntax. It also affects certain mode line indicators and command-line -prompts. - -@node Slanted constructs -@section Option for more slanted constructs - -@vindex modus-themes-slanted-constructs - -Symbol: @code{modus-themes-slanted-constructs} - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{t} -@end enumerate - -The default is to not use slanted text (italics) unless it is absolutely -necessary. - -With a non-nil value (@samp{t}) choose to render more faces in slanted text. -This typically affects documentation strings and code comments. - -@node Syntax styles -@section Option for syntax highlighting - -@vindex modus-themes-syntax - -Symbol: @code{modus-themes-syntax} - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@code{faint} -@item -@code{yellow-comments} -@item -@code{green-strings} -@item -@code{yellow-comments-green-strings} -@item -@code{alt-syntax} -@item -@code{alt-syntax-yellow-comments} -@item -@code{faint-yellow-comments} -@end enumerate - -The default style (nil) for code syntax highlighting is a balanced -combination of colors on the cyan-blue-magenta side of the spectrum. -There is little to no use of greens, yellows, or reds, except when it is -necessary. - -Option @code{faint} is like the default in terms of the choice of palette but -applies desaturated color values. - -Option @code{yellow-comments} adds a yellow tint to comments. The rest of the -syntax is the same as the default. - -Option @code{green-strings} replaces the blue/cyan/cold color variants in -strings with greener alternatives. The rest of the syntax remains the -same. - -Option @code{yellow-comments-green-strings} combines yellow comments with green -strings and the rest of the default syntax highlighting style. - -Option @code{alt-syntax} expands the active spectrum by applying color -combinations with more contrasting hues between them. Expect to find -red and green variants in addition to cyan, blue, magenta. - -Option @code{alt-syntax-yellow-comments} combines @code{alt-syntax} with -@code{yellow-comments}. - -Option @code{faint-yellow-comments} combines the @code{faint} style with -@code{yellow-comments}. - -@node No mixed fonts -@section Option for no font mixing - -@vindex modus-themes-no-mixed-fonts - -Symbol: @code{modus-themes-no-mixed-fonts} - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{t} -@end enumerate - -By default, the themes configure some spacing-sensitive faces like Org -tables and code blocks to always inherit from the @code{fixed-pitch} face. -This is to ensure that those constructs remain monospaced even when -users opt for a mode that remaps typeface families, such as the built-in -@kbd{M-x variable-pitch-mode}. Otherwise the layout would appear -broken, due to how spacing is done. To disable this behaviour, set the -option to @samp{t}. - -Users may prefer to use another package for handling mixed typeface -configurations, rather than letting the theme do it, perhaps because a -purpose-specific package has extra functionality. Two possible options -are @code{org-variable-pitch} and @code{mixed-pitch}. - -@ref{Font configurations for Org and others (DIY), , Font configurations for Org (and others)}. - -@node Link styles -@section Option for links - -@vindex modus-themes-links - -Symbol: @code{modus-themes-links} - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@code{faint} -@item -@code{neutral-underline} -@item -@code{faint-neutral-underline} -@item -@code{no-underline} -@item -@code{underline-only} -@item -@code{neutral-underline-only} -@end enumerate - -The default style (nil) for links is to apply an underline and a -saturated color to the affected text. The color of the two is the same, -which makes the link fairly prominent. - -Option @code{faint} follows the same approach as the default, but uses less -intense colors. - -Option @code{neutral-underline} changes the underline's color to a subtle gray, -while retaining the default text color. - -Option @code{faint-neutral-underline} combines a desaturated text color with a -subtle gray underline. - -Option @code{no-underline} removes link underlines altogether, while retaining -their original fairly vivid color. - -Option @code{underline-only} applies a prominent underline while making the -affected text colorless (it uses the same foreground as the theme's -default). - -Option @code{neutral-underline-only} makes the text colorless while using a -subtle gray underline below it. - -NOTE: The placement of the underline, i.e. its proximity to the affected -text, is controlled by the built-in @code{x-underline-at-descent-line}, -@code{x-use-underline-position-properties}, @code{underline-minimum-offset}. Please -refer to their documentation strings. - -@node Command prompts -@section Option for command prompt styles - -@vindex modus-themes-prompts - -Symbol: @code{modus-themes-prompts} - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@code{subtle-accented} (@code{subtle} exists for backward compatibility) -@item -@code{intense-accented} (@code{intense} exists for backward compatibility) -@item -@code{subtle-gray} -@item -@code{intense-gray} -@end enumerate - -The default does not use any background for minibuffer and command line -prompts. It relies exclusively on an accented foreground color. - -Options @code{subtle-accented} and @code{intense-accented} will change both the -background and the foreground values to use accented color combinations -that follow the hue of the default styles' foreground (e.g. the default -minibuffer prompt is cyan text, so these combinations will involved a -cyan background and an appropriate cyan foreground). The difference -between the two is that the latter has a more pronounced/noticeable -effect than the former. - -Options @code{subtle-gray}, @code{intense-gray} are like their accented counterparts, -except they use grayscale values. - -@node Mode line -@section Option for mode line presentation - -@vindex modus-themes-mode-line - -Symbol: @code{modus-themes-mode-line} - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@code{3d} -@item -@code{moody} -@item -@code{borderless} -@item -@code{borderless-3d} -@item -@code{borderless-moody} -@end enumerate - -The default produces a two-dimensional effect both for the active and -inactive modelines. The differences between the two are limited to -distinct shades of grayscale values, with the active being more intense -than the inactive. - -Option @code{3d} will make the active modeline look like a three-dimensional -rectangle. Inactive modelines remain 2D, though they are slightly toned -down relative to the default. This aesthetic is virtually the same as -what you get when you run Emacs without any customizations (@samp{emacs -Q} on -the command line). - -While @code{moody} removes all box effects from the modelines and applies -underline and overline properties instead. It also tones down a bit the -inactive modelines. This is meant to optimize things for use with the -@uref{https://github.com/tarsius/moody, moody package} (hereinafter referred to as ``Moody''), though it can work -fine even without it. - -The @code{borderless} option uses the same colors as the default (nil value), -but removes the border effect. This is done by making the box property -use the same color as the background, effectively blending the two and -creating some padding. - -The @code{borderless-3d} and @code{borderless-moody} approximate the @code{3d} and @code{moody} -options respectively, while removing the borders. However, to ensure -that the inactive modelines remain visible, they apply a slightly more -prominent background to them than what their counterparts do (same -inactive background as with the default). - -Note that Moody does not expose any faces that the themes could style -directly. Instead it re-purposes existing ones to render its tabs and -ribbons. As such, there may be cases where the contrast ratio falls -below the 7:1 target that the themes conform with (WCAG AAA). To hedge -against this, we configure a fallback foreground for the @code{moody} option, -which will come into effect when the background of the modeline changes -to something less accessible, such as Moody ribbons (read the doc string -of @code{set-face-attribute}, specifically @code{:distant-foreground}). This fallback -is activated when Emacs determines that the background and foreground of -the given construct are too close to each other in terms of color -distance. In effect, users would need to experiment with the variable -@code{face-near-same-color-threshold} to trigger the effect. We find that a -value of @samp{45000} will suffice, contrary to the default @samp{30000}. Do not set -the value too high, because that would have the adverse effect of always -overriding the default color (which has been carefully designed to be -highly accessible). - -Furthermore, because Moody expects an underline and overline instead of -a box style, it is advised you include this in your setup: - -@lisp -(setq x-underline-at-descent-line t) -@end lisp - -@node Completion UIs -@section Option for completion framework aesthetics - -@vindex modus-themes-completions - -Symbol: @code{modus-themes-completions} - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@code{moderate} -@item -@code{opinionated} -@end enumerate - -This is a special option that has different effects depending on the -completion UI@. The interfaces can be grouped in two categories, based -on their default aesthetics: (i) those that only or mostly use -foreground colors for their interaction model, and (ii) those that -combine background and foreground values for some of their metaphors. -The former category encompasses Icomplete, Ido, Selectrum as well as -pattern matching styles like Orderless and Flx. The latter covers Helm, -Ivy, and similar. - -A value of @samp{nil} will respect the metaphors of each completion framework. - -Option @code{moderate} applies a combination of background and foreground that -is fairly subtle. For Icomplete and friends this constitutes a -departure from their default aesthetics, however the difference is -small. While Helm, Ivy et al appear slightly different than their -original looks, as they are toned down a bit. - -Option @code{opinionated} uses color combinations that refashion the completion -UI@. For the Icomplete camp this means that intense background and -foreground combinations are used: in effect their looks emulate those of -Helm, Ivy and co. in their original style. Whereas the other group of -packages will revert to an even more nuanced aesthetic with some -additional changes to the choice of hues. - -To appreciate the scope of this customization option, you should spend -some time with every one of the @samp{nil} (default), @code{moderate}, and @code{opinionated} -possibilities. - -@node Fringes -@section Option for fringe visibility - -@vindex modus-themes-fringes - -Symbol: @code{modus-themes-fringes} - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@code{subtle} -@item -@code{intense} -@end enumerate - -The default is to use the same color as that of the main background, -meaning that the fringes are not obvious though they still occupy the -space given to them by @code{fringe-mode}. - -Options @code{subtle} and @code{intense} apply a gray background, making the fringes -visible. The difference between the two is one of degree, as their -names imply. - -@node Language checkers -@section Option for language checkers - -@vindex modus-themes-lang-checkers - -Symbol: @code{modus-themes-lang-checkers} - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@code{subtle-foreground} -@item -@code{intense-foreground} -@item -@code{straight-underline} -@item -@code{subtle-foreground-straight-underline} -@item -@code{intense-foreground-straight-underline} -@item -@code{colored-background} -@end enumerate - -Nil (the default) applies a color-coded underline to the affected text, -while it leaves the original foreground in tact. If the display spec -where Emacs runs in has support for it (e.g. Emacs GUI), the underline's -style is that of a wave, otherwise it is a straight line. - -Options @code{subtle-foreground} and @code{intense-foreground} follow the same -color-coding pattern and wavy underline of the default, while extending -it with a corresponding foreground value for the affected text. The -difference between the two options is one of degree, as their names -suggest. - -Option @code{straight-underline} is like the default but always applies a -straight line under the affected text. Same principle for -@code{subtle-foreground-straight-underline} and its counterpart -@code{intense-foreground-straight-underline}. - -Option @code{colored-background} uses a straight underline, a tinted -background, and a suitable foreground. All are color-coded. This is -the most intense combination of face properties. - -The present variable affects packages and/or face groups such as those -of @samp{flyspell}, @samp{flymake}, @samp{flycheck}, @code{artbollocks-mode}, and @code{writegood-mode}. - -NOTE: The placement of the straight underline, though not the wave -style, is controlled by the built-in @code{x-underline-at-descent-line}, -@code{x-use-underline-position-properties}, @code{underline-minimum-offset}. Please -refer to their documentation strings. - -@node Line highlighting -@section Option for line highlighting (hl-line-mode) - -@vindex modus-themes-intense-hl-line - -Symbol: @code{modus-themes-intense-hl-line} - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{t} -@end enumerate - -The default is to use a subtle gray background for @code{hl-line-mode} and its -global equivalent. - -With a non-nil value (@samp{t}) use a more prominent background color instead. - -This affects several packages that enable @code{hl-line-mode}, such as @samp{elfeed} -and @samp{mu4e}. - -@node Line numbers -@section Option for line numbers (display-line-numbers-mode) - -@vindex modus-themes-subtle-line-numbers - -Symbol: @code{modus-themes-subtle-line-numbers} - -Possible value: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{t} -@end enumerate - -The default style for @code{display-line-numbers-mode} and its global variant -is to apply a subtle gray background to the line numbers. The current -line has a more pronounced background and foreground combination to -bring more attention to itself. - -Similarly, the faces for @code{display-line-numbers-major-tick} and its -counterpart @code{display-line-numbers-minor-tick} use appropriate styles that -involve a bespoke background and foreground combination. - -With a non-nil value (@samp{t}), line numbers have no background of their own. -Instead they retain the primary background of the theme, blending with -the rest of the buffer. Foreground values for all relevant faces are -updated to accommodate this aesthetic. - -@node Matching parentheses -@section Option for parenthesis matching (show-paren-mode) - -@vindex modus-themes-paren-match - -Symbol: @code{modus-themes-paren-match} - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@code{subtle-bold} -@item -@code{intense} -@item -@code{intense-bold} -@end enumerate - -Nil means to use a subtle tinted background color for the matching -delimiters. - -Option @code{intense} applies a saturated background color. - -Option @code{subtle-bold} is the same as the default, but also makes use of -bold typographic weight (inherits the @code{bold} face). - -Option @code{intense-bold} is the same as @code{intense}, while it also uses a bold -weight. - -This customization variable affects tools such as the built-in -@code{show-paren-mode} and the @samp{smartparens} package. - -@node Active region -@section Option for active region - -@vindex modus-themes-region - -Symbol: @code{modus-themes-region} - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@code{no-extend} -@item -@code{bg-only} -@item -@code{bg-only-no-extend} -@end enumerate - -Nil means to only use a prominent gray background with a neutral -foreground. The foreground overrides all syntax highlighting. The -region extends to the edge of the window. - -Option @code{no-extend} preserves the default aesthetic but prevents the region -from extending to the edge of the window. - -Option @code{bg-only} applies a faint tinted background that is distinct from -all others used in the theme, while it does not override any existing -colors. It extends to the edge of the window. - -Option @code{bg-only-no-extend} is a combination of the @code{bg-only} and @code{no-extend} -options. - -@node Diffs -@section Option for diff buffer looks - -@vindex modus-themes-diffs - -Symbol: @code{modus-themes-diffs} - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@code{desaturated} -@item -@code{fg-only} -@item -@code{bg-only} -@item -@code{deuteranopia} -@end enumerate - -By default the themes apply rich coloration to the output of diffs, such -as those of @code{diff-mode}, @code{ediff}, @code{smerge-mode}, and Magit. These are -color combinations of an accented background and foreground so that, for -example, added lines have a pronounced green background with an -appropriate shade of green for the affected text. Word-wise or -``refined'' changes follow this pattern but use different shades of those -colors to remain distinct. - -Option @code{desaturated} tones down all relevant color values. It still -combines an accented background with an appropriate foreground, yet its -overall impression is fairly subtle. Refined changes are a bit more -intense to fulfil their intended function, though still less saturated -than default. - -Option @code{fg-only} will remove most accented backgrounds and instead rely -on color-coded text to denote changes. For instance, added lines use a -green foreground, while their background is the same as the rest of the -buffer. Word-wise highlights still use a background value which is, -nonetheless, more subtle than its default equivalent. - -Option @code{bg-only} applies color-coded backgrounds but does not override -any syntax highlighting that may be present. This makes it suitable for -use with a non-nil value for @code{diff-font-lock-syntax} (which is the -default for @code{diff-mode} buffers in Emacs 27 or higher). - -Option @code{deuteranopia} optimizes for red-green color deficiency. It -replaces all instances of green with blue variants. This is to ensure -that indicators for ``removed'' and ``added'' states are not mistaken for -each other. - -Concerning Magit, an extra set of tweaks are introduced for the effect -of highlighting the current diff hunk, so as to remain aligned with the -overall experience of that mode. Expect changes that are consistent -with the overall intent of the aforementioned. Note, however, that the -@code{bg-only} option will not deliver the intended results in Magit diffs -because no syntax highlighting is used there (last checked with Magit -version 20201116.1057, though upstream has a plan to eventually support -such a feature---this entry shall be updated accordingly). - -@node Org mode blocks -@section Option for org-mode block styles - -@vindex modus-themes-org-blocks - -Symbol: @code{modus-themes-org-blocks} - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@code{grayscale} -@item -@code{rainbow} -@end enumerate - -The default is to use the same background as the rest of the buffer for -the contents of the block. - -Option @code{grayscale} applies a subtle neutral gray background to the block's -contents. It will also extend to the edge of the window the background -of the ``begin'' and ``end'' block delimiter lines (only relevant for Emacs -versions >= 27 where the 'extend' keyword is part of the face -specifications). - -Option @code{rainbow} uses an accented background for the contents of the -block. The exact color will depend on the programming language and is -controlled by the @code{org-src-block-faces} variable. This is most suitable -for users who work on literate programming documents that mix and match -several languages. - -Note that the ``rainbow'' blocks may require you to also reload the -major-mode so that the colors are applied consistently throughout: use -@kbd{M-x org-mode} or @kbd{M-x org-mode-restart} to refresh the buffer. -Or start typing in each code block (inefficient at scale, but it still -works). - -@node Org agenda habits -@section Option for org-habit graph styles - -@vindex modus-themes-org-habit - -Symbol: @code{modus-themes-org-habit} - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@code{simplified} -@item -@code{traffic-light} -@end enumerate - -The default is meant to conform with the original aesthetic of -@samp{org-habit}. It employs all four color codes that correspond to the -org-habit states---clear, ready, alert, and overdue---while -distinguishing between their present and future variants. This results -in a total of eight colors in use: red, yellow, green, blue, in tinted -and shaded versions. They cover the full set of information provided by -the @samp{org-habit} consistency graph. - -Option @code{simplified} is like the default except that it removes the -dichotomy between current and future variants by applying uniform -color-coded values. It applies a total of four colors: red, yellow, -green, blue. They produce a simplified consistency graph that is more -legible (or less ``busy'') than the default. The intent is to shift focus -towards the distinction between the four states of a habit task, rather -than each state's present/future outlook. - -Option @code{traffic-light} further reduces the available colors to red, -yellow, and green. As in @code{simplified}, present and future variants appear -uniformly, but differently from it, the 'clear' state is rendered in a -green hue, instead of the original blue. This is meant to capture the -use-case where a habit task being ``too early'' is less important than it -being ``too late''. The difference between ready and clear states is -attenuated by painting both of them using shades of green. This option -thus highlights the alert and overdue states. - -@node Heading styles -@section Option for the headings' overall style - -@vindex modus-themes-headings - -This is defined as an alist and, therefore, uses a different approach -than other customization options documented in this manual. - -Symbol: @code{modus-themes-headings} - -Possible values, which can be specified for each heading level (examples -further below): - -@itemize -@item -nil (default fallback option---covers all heading levels) -@item -@samp{t} (default style for a single heading, when the fallback differs) -@item -@code{no-bold} -@item -@code{line} -@item -@code{line-no-bold} -@item -@code{rainbow} -@item -@code{rainbow-line} -@item -@code{rainbow-line-no-bold} -@item -@code{highlight} -@item -@code{highlight-no-bold} -@item -@code{rainbow-highlight} -@item -@code{rainbow-highlight-no-bold} -@item -@code{section} -@item -@code{section-no-bold} -@item -@code{rainbow-section} -@item -@code{rainbow-section-no-bold} -@item -@code{no-color} -@item -@code{no-color-no-bold} -@end itemize - -To control faces per level from 1-8, use something like this: - -@lisp -(setq modus-themes-headings - '((1 . section) - (2 . section-no-bold) - (3 . rainbow-line) - (t . rainbow-line-no-bold))) -@end lisp - -The above uses the @code{section} value for heading levels 1, @code{section-no-bold} -for headings 2, @code{rainbow-line} for 3. All other levels fall back to -@code{rainbow-line-no-bold}. - -To set a uniform value for all heading levels, use this pattern: - -@lisp -;; A given style for every heading -(setq modus-themes-headings - '((t . section))) - -;; Default aesthetic for every heading -(setq modus-themes-headings - '()) -@end lisp - -The default style for headings uses a fairly desaturated foreground -value in combination with bold typographic weight. To specify this -style for a given level N, assuming you wish to have another fallback -option, just specify the value @samp{t} like this: - -@lisp -(setq modus-themes-headings - '((1 . t) - (2 . line) - (t . rainbow-line-no-bold))) -@end lisp - -A description of all other possible styles beyond the default: - -@itemize -@item -@code{no-bold} retains the default text color while removing the bold -typographic weight. - -@item -@code{line} is the same as the default plus an overline across the -heading's length. - -@item -@code{line-no-bold} is the same as @code{line} without bold weight. - -@item -@code{rainbow} uses a more colorful foreground in combination with bold -typographic weight. - -@item -@code{rainbow-line} is the same as @code{rainbow} plus an overline. - -@item -@code{rainbow-line-no-bold} is the same as @code{rainbow-line} without the bold -weight. - -@item -@code{highlight} retains the default style of a fairly desaturated -foreground combined with a bold weight and adds to it a subtle -accented background. - -@item -@code{highlight-no-bold} is the same as @code{highlight} without a bold weight. - -@item -@code{rainbow-highlight} is the same as @code{highlight} but with a more -colorful foreground. - -@item -@code{rainbow-highlight-no-bold} is the same as @code{rainbow-highlight} without -a bold weight. - -@item -@code{section} retains the default looks and adds to them both an overline -and a slightly accented background. It is, in effect, a combination -of the @code{line} and @code{highlight} values. - -@item -@code{section-no-bold} is the same as @code{section} without a bold weight. - -@item -@code{rainbow-section} is the same as @code{section} but with a more colorful -foreground. - -@item -@code{rainbow-section-no-bold} is the same as @code{rainbow-section} without a -bold weight. - -@item -@code{no-color} does not apply any color to the heading, meaning that it -uses the foreground of the @code{default} face. It still renders the text -with a bold typographic weight. - -@item -@code{no-color-no-bold} is like @code{no-color} but without the bold weight. -@end itemize - -@node Scaled headings -@section Option for scaled headings - -@vindex modus-themes-scale-headings - -Symbol: @code{modus-themes-scale-headings} - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{t} -@end enumerate - -The default is to use the same size for headings and paragraph text. - -With a non-nil value (@samp{t}) make headings larger in height relative to the -main text. This is noticeable in modes like Org, Markdown, and Info. - -@menu -* Scaled heading sizes:: Specify rate of increase for scaled headings -@end menu - -@node Scaled heading sizes -@subsection Control the scale of headings - -In addition to the toggle for enabling scaled headings, users can also -specify a number of their own. - -@itemize -@item -If it is a floating point, say, @samp{1.5}, it is interpreted as a multiple -of the base font size. This is the recommended method, because it -will always adapt to changes in the base font size, such as while -using the @code{text-scale-adjust} command. - -@item -If it is an integer, it is read as an absolute font height that is -1/10 of the typographic point size. Thus a value of @samp{18pt} must be -expressed as @samp{180}. Setting an absolute value is discouraged, as it -will break the layout in cases where the base font size must change, -such as with the @code{text-scale-adjust} command (@ref{Font configurations for Org and others (DIY), , Font configurations}). -While we discourage using absolute values, we still provide for this -option for users who do not need to perform text-scaling operations or -who are content with whatever discrepancies in height. -@end itemize - -Below are the variables in their default values, using the floating -point paradigm. The numbers are very conservative, but one is free to -change them to their liking, such as @samp{1.2}, @samp{1.4}, @samp{1.6}, @samp{1.8}, @samp{2.0}---or use a -resource for finding a consistent scale: - -@lisp -(setq modus-themes-scale-1 1.05 - modus-themes-scale-2 1.1 - modus-themes-scale-3 1.15 - modus-themes-scale-4 1.2 - modus-themes-scale-5 1.3) -@end lisp - -As for the application of that scale, the variables that range from -@code{modus-themes-scale-1} up to @code{modus-themes-scale-4} apply to regular -headings within the context of the given major mode. The former is the -smallest, while the latter is the largest. ``Regular headings'' are those -that have a standard syntax for their scale, such as Org mode's eight -levels of asterisks or Markdown's six columns. - -Whereas @code{modus-themes-scale-5} is applied to special headings that do not -conform with the aforementioned syntax, yet which are expected to be -larger than the largest value on that implied scale. Put concretely, -Org's @samp{#+title} meta datum is not part of the eight levels of headings in -an Org file, yet is supposed to signify the primary header. Similarly, -the Org Agenda's structure headings are not part of a recognisable scale -and so they also get @code{modus-themes-scale-5}. - -Users who wish to maintain scaled headings for the normal syntax while -preventing special headings from standing out, can assign a value of @samp{1.0} -to @code{modus-themes-scale-5} to make it the same as body text (or whatever -value would render it indistinguishable from the desired point of -reference). - -Note that in earlier versions of Org, scaling would only increase the -size of the heading, but not of keywords that were added to it, like -``TODO''. The issue has been fixed upstream: -@uref{https://protesilaos.com/codelog/2020-09-24-org-headings-adapt/}. - -@node UI typeface -@section Option for variable-pitch font in UI elements - -@vindex modus-themes-variable-pitch-ui - -Symbol: @code{modus-themes-variable-pitch-ui} - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{t} -@end enumerate - -This option concerns User Interface elements that are under the direct -control of Emacs. In particular: the mode line, header line, tab bar, -and tab line. - -The default is to use the same font as the rest of Emacs, which usually -is a monospaced family. - -With a non-nil value (@samp{t}) apply a proportionately spaced typeface. This -is done by assigning the @code{variable-pitch} face to the relevant items. - -@ref{Font configurations for Org and others (DIY), , Font configurations for Org and others}. - -@node Headings' typeface -@section Option for variable-pitch font in headings - -@vindex modus-themes-variable-pitch-headings - -Symbol: @code{modus-themes-variable-pitch-headings} - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{t} -@end enumerate - -The default is to use the main font family, which typically is -monospaced. - -With a non-nil value (@samp{t}) apply a proportionately spaced typeface, else -``variable-pitch'', to headings (such as in Org mode). - -@ref{Font configurations for Org and others (DIY), , Font configurations for Org and others}. - -@node Advanced customization (do-it-yourself) -@chapter Advanced customization (do-it-yourself) - -Unlike the predefined customization options which follow a clear pattern -of allowing the user to quickly specify their preference, the themes -also provide a more flexible, albeit difficult, mechanism to control -things with precision (@ref{Customization Options}). - -This section is of interest only to users who are prepared to maintain -their own local tweaks and who are willing to deal with any possible -incompatibilities between versioned releases of the themes. As such, -they are labelled as ``do-it-yourself'' or ``DIY''. - -@menu -* Per-theme customization settings (DIY):: -* Case-by-case face specs using the themes' palette (DIY):: -* Face specs at scale using the themes' palette (DIY):: -* Override colors (DIY):: -* Font configurations for Org and others (DIY):: -* Custom Org user faces (DIY):: -* Measure color contrast (DIY):: -* Load theme depending on time of day:: -* A theme-agnostic hook for theme loading (DIY):: -@end menu - -@node Per-theme customization settings (DIY) -@section Per-theme customization settings (DIY) - -If you prefer to maintain different customization options between the -two themes, it is best you write your own functions that first set those -options and then load the relevant theme. The following code does -exactly that by simply differentiating the two themes on the choice of -bold constructs in code syntax (enabled for one, disabled for the -other). - -@lisp -(defun my-demo-modus-operandi () - (interactive) - (setq modus-themes-bold-constructs t) ; ENABLE bold - (modus-themes-load-operandi)) - -(defun my-demo-modus-vivendi () - (interactive) - (setq modus-themes-bold-constructs nil) ; DISABLE bold - (modus-themes-load-vivendi)) - -(defun my-demo-modus-themes-toggle () - (if (eq (car custom-enabled-themes) 'modus-operandi) - (my-demo-modus-vivendi) - (my-demo-modus-operandi))) -@end lisp - -Then assign @code{my-demo-modus-themes-toggle} to a key instead of the -equivalent the themes provide. - -For a more elaborate design, it is better to inspect the source code of -@code{modus-themes-toggle} and relevant functions. - -@node Case-by-case face specs using the themes' palette (DIY) -@section Case-by-case face specs using the themes' palette (DIY) - -@findex modus-themes-color -@findex modus-themes-color-alts -@cindex Extracting individual colors - -This section is about tweaking individual faces. If you plan to do -things at scale, consult the next section: @ref{Face specs at scale using the themes' palette (DIY), , Set multiple faces}. - -We already covered in previous sections how to toggle between the themes -and how to configure options prior to loading. We also explained that -some of the functions made available to users will fire up a hook that -can be used to pass tweaks in the post-theme-load phase. - -Now assume you wish to change a single face, say, the @code{cursor}. And you -would like to get the standard ``blue'' color value of the active Modus -theme, whether it is Modus Operandi or Modus Vivendi. To do that, you -can use the @code{modus-themes-color} function. It accepts a symbol that is -associated with a color in @code{modus-themes-operandi-colors} and -@code{modus-themes-vivendi-colors}. Like this: - -@lisp -(modus-themes-color 'blue) -@end lisp - -The function always extracts the color value of the active Modus theme. - -@lisp -(progn - (load-theme 'modus-operandi t) - (modus-themes-color 'blue)) ; "#0031a9" for `modus-operandi' - -(progn - (load-theme 'modus-vivendi t) - (modus-themes-color 'blue)) ; "#2fafff" for `modus-vivendi' -@end lisp - -Do @kbd{C-h v} on the aforementioned variables to check all the available -symbols that can be passed to this function. - -With that granted, let us expand the example to actually change the -@code{cursor} face's background property. We employ the built-in function of -@code{set-face-attribute}: - -@lisp -(set-face-attribute 'cursor nil :background (modus-themes-color 'blue)) -@end lisp - -If you evaluate this form, your cursor will become blue. But if you -change themes, such as with @code{modus-themes-toggle}, your edits will be -lost, because the newly loaded theme will override the @samp{:background} -attribute you had assigned to that face. - -For such changes to persist, we need to make them after loading the -theme. So we rely on @code{modus-themes-after-load-theme-hook}, which gets -called from @code{modus-themes-load-operandi}, @code{modus-themes-load-vivendi}, as -well as the command @code{modus-themes-toggle}. Here is a sample function that -tweaks two faces and then gets added to the hook: - -@lisp -(defun my-modus-themes-custom-faces () - (set-face-attribute 'cursor nil :background (modus-themes-color 'blue)) - (set-face-attribute 'font-lock-type-face nil :foreground (modus-themes-color 'magenta-alt))) - -(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) -@end lisp - -@ref{A theme-agnostic hook for theme loading (DIY), , A theme-agnostic hook for theme loading}. - -Using this principle, it is possible to override the styles of faces -without having to find color values for each case. - -Another application is to control the precise weight for bold -constructs. This is particularly useful if your typeface has several -variants such as ``heavy'', ``extrabold'', ``semibold''. All you have to do -is edit the @code{bold} face. For example: - -@lisp -(set-face-attribute 'bold nil :weight 'semibold) -@end lisp - -Remember to use the custom function and hook combo we demonstrated -above. Because the themes do not hard-wire a specific weight, this -simple form is enough to change the weight of all bold constructs -throughout the interface. - -Finally, there are cases where you want to tweak colors though wish to -apply different ones to each theme, say, a blue hue for Modus Operandi -and a shade of red for Modus Vivendi. To this end, we provide -@code{modus-themes-color-alts} as a convenience function to save you from the -trouble of writing separate wrappers for each theme. It still returns a -single value by querying either of @code{modus-themes-operandi-colors} and -@code{modus-themes-vivendi-colors}, only here you pass the two keys you want, -first for @code{modus-operandi} then @code{modus-vivendi}. - -Take the previous example with the @code{cursor} face: - -@lisp -;; Blue for `modus-operandi' and red for `modus-vivendi' -(set-face-attribute 'cursor nil :background (modus-themes-color-alts 'blue 'red)) -@end lisp - -@node Face specs at scale using the themes' palette (DIY) -@section Face specs at scale using the themes' palette (DIY) - -@findex modus-themes-with-colors -@cindex Extracting colors en masse - -The examples here are for large scale operations. For simple, one-off -tweaks, you may prefer the approach documented in the previous section -(@ref{Case-by-case face specs using the themes' palette (DIY), , Case-by-case face specs using the themes' palette}). - -The @code{modus-themes-with-colors} macro lets you retrieve multiple color -values by employing the backquote/backtick and comma notation. The -values are stored in the alists @code{modus-themes-operandi-colors} and -@code{modus-themes-vivendi-colors}, while the macro always queries that of the -active Modus theme. - -Here is an abstract example that just returns a list of color values -while @code{modus-operandi} is enabled: - -@lisp -(modus-themes-with-colors - (list fg-main - blue-faint - magenta - magenta-alt-other - cyan-alt-other - fg-special-cold - blue-alt - magenta-faint - cyan - fg-main - green-faint - red-alt-faint - blue-alt-faint - fg-special-warm - cyan-alt - blue)) -;; => -;; ("#000000" "#002f88" "#721045" "#5317ac" -;; "#005a5f" "#093060" "#2544bb" "#752f50" -;; "#00538b" "#000000" "#104410" "#702f00" -;; "#003f78" "#5d3026" "#30517f" "#0031a9") -@end lisp - -Getting a list of colors may have its applications, though what you are -most likely interested in is how to use those variables to configure -several faces at once. To do so we can rely on the built-in -@code{custom-set-faces} function, which sets face specifications for the -special @samp{user} theme. That ``theme'' gets applied on top of regular themes -like @code{modus-operandi} and @code{modus-vivendi}. - -This is how it works: - -@lisp -(modus-themes-with-colors - (custom-set-faces - `(cursor ((,class :background ,blue))) - `(mode-line ((,class :background ,yellow-nuanced-bg - :foreground ,yellow-nuanced-fg))) - `(mode-line-inactive ((,class :background ,blue-nuanced-bg - :foreground ,blue-nuanced-fg))))) -@end lisp - -The above snippet will immediately refashion the faces it names once it -is evaluated. However, if you switch between the Modus themes, say, -from @code{modus-operandi} to @code{modus-vivendi}, the colors will not get updated to -match those of the new theme. To make things work across the themes, we -need to employ the same technique we discussed in the previous section, -namely, to pass our changes at the post-theme-load phase via a hook. - -The themes provide the @code{modus-themes-after-load-theme-hook}, which gets -called from @code{modus-themes-load-operandi}, @code{modus-themes-load-vivendi}, as -well as the command @code{modus-themes-toggle}. With this knowledge, you can -wrap the macro in a function and then assign that function to the hook. -Thus: - -@lisp -(defun my-modus-themes-custom-faces () - (modus-themes-with-colors - (custom-set-faces - `(cursor ((,class :background ,blue))) - `(mode-line ((,class :background ,yellow-nuanced-bg - :foreground ,yellow-nuanced-fg))) - `(mode-line-inactive ((,class :background ,blue-nuanced-bg - :foreground ,blue-nuanced-fg)))))) - -(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) -@end lisp - -@ref{A theme-agnostic hook for theme loading (DIY), , A theme-agnostic hook for theme loading}. - -To discover the faces defined by all loaded libraries, you may do -@kbd{M-x list-faces-display}. Be warned that when you @samp{:inherit} a face -you are introducing an implicit dependency, so try to avoid doing so for -libraries other than the built-in @file{faces.el} (or at least understand -that things may break if you inherit from a yet-to-be-loaded face). - -Also bear in mind that these examples are meant to work with the Modus -themes. If you are cycling between multiple themes you may encounter -unforeseen issues, such as the colors of the Modus themes being applied -to a non-Modus item. - -Finally, note that you can still use other functions where those make -sense. For example, the @code{modus-themes-color-alts} that was discussed in -the previous section. Adapt the above example like this: - -@lisp -... -(modus-themes-with-colors - (custom-set-faces - `(cursor ((,class :background ,(modus-themes-color-alts 'blue 'green)))) - ...)) -@end lisp - -@node Override colors (DIY) -@section Override colors (DIY) - -@vindex modus-themes-operandi-color-overrides -@vindex modus-themes-vivendi-color-overrides -@cindex Change a theme's colors - -The themes provide a mechanism for overriding their color values. This -is controlled by the variables @code{modus-themes-operandi-color-overrides} and -@code{modus-themes-vivendi-color-overrides}, which are alists that should -mirror a subset of the associations in @code{modus-themes-operandi-colors} and -@code{modus-themes-vivendi-colors} respectively. As with all customisations, -overriding must be done before loading the affected theme. - -Let us approach the present topic one step at a time. Here is a -simplified excerpt of the default palette for Modus Operandi with some -basic background values that apply to buffers and the mode line -(remember to inspect the actual value to find out all the associations -that can be overridden): - -@lisp -(defconst modus-themes-colors-operandi - '((bg-main . "#ffffff") - (bg-dim . "#f8f8f8") - (bg-alt . "#f0f0f0") - (bg-active . "#d7d7d7") - (bg-inactive . "#efefef"))) -@end lisp - -As one can tell, we bind a key to a hexadecimal RGB color value. Now -say we wish to override those specific values and have our changes -propagate to all faces that use those keys. We could write something -like this, which adds a subtle ochre tint: - -@lisp -(setq modus-themes-operandi-color-overrides - '((bg-main . "#fefcf4") - (bg-dim . "#faf6ef") - (bg-alt . "#f7efe5") - (bg-active . "#e8dfd1") - (bg-inactive . "#f6ece5"))) -@end lisp - -Once this is evaluated, any subsequent loading of @code{modus-operandi} will -use those values instead of the defaults. No further intervention is -required. - -To reset the changes, we apply this and reload the theme: - -@lisp -(setq modus-themes-operandi-color-overrides nil) -@end lisp - -Users who wish to leverage such a mechanism can opt to implement it -on-demand by means of a global minor mode. The following snippet covers -both themes and expands to some more assosiations in the palette: - -@lisp -(define-minor-mode my-modus-themes-tinted - "Tweak some Modus themes colors." - :init-value nil - :global t - (if my-modus-themes-tinted - (setq modus-themes-operandi-color-overrides - '((bg-main . "#fefcf4") - (bg-dim . "#faf6ef") - (bg-alt . "#f7efe5") - (bg-hl-line . "#f4f0e3") - (bg-active . "#e8dfd1") - (bg-inactive . "#f6ece5") - (bg-region . "#c6bab1") - (bg-header . "#ede3e0") - (bg-tab-bar . "#dcd3d3") - (bg-tab-active . "#fdf6eb") - (bg-tab-inactive . "#c8bab8") - (fg-unfocused . "#55556f")) - modus-themes-vivendi-color-overrides - '((bg-main . "#100b17") - (bg-dim . "#161129") - (bg-alt . "#181732") - (bg-hl-line . "#191628") - (bg-active . "#282e46") - (bg-inactive . "#1a1e39") - (bg-region . "#393a53") - (bg-header . "#202037") - (bg-tab-bar . "#262b41") - (bg-tab-active . "#120f18") - (bg-tab-inactive . "#3a3a5a") - (fg-unfocused . "#9a9aab"))) - (setq modus-themes-operandi-color-overrides nil - modus-themes-vivendi-color-overrides nil))) -@end lisp - -With this in place, one can invoke @kbd{M-x my-modus-themes-tinted} and -then load the Modus theme of their choice. The new palette subset will -come into effect: subtle ochre tints for Modus Operandi and night sky -shades for Modus Vivendi. Switching between the two themes, such as -with @kbd{M-x modus-themes-toggle} will also use the overrides. - -Given that this is a user-level customisation, one is free to implement -whatever color values they desire, even if the possible combinations -fall below the minimum 7:1 contrast ratio that governs the design of the -themes (the WCAG AAA legibility standard). Preferences aside, it is -advised to inspect the source code of @code{modus-themes-operandi-colors} and -@code{modus-themes-vivendi-colors} to read the inline commentary: it explains -what the intended use of each palette subset is. - -Furthermore, users may benefit from the @code{modus-themes-contrast} function -that we provide: @ref{Measure color contrast (DIY), , test color combinations}. It measures the contrast -ratio between two color values, so it can help in overriding the palette -(or a subset thereof) without making the end result inaccessible. - -@node Font configurations for Org and others (DIY) -@section Font configurations for Org and others (DIY) - -@cindex Font configurations - -The themes are designed to cope well with mixed font configurations. - -@ref{No mixed fonts, , Option for no font mixing}. - -This mostly concerns @code{org-mode} and @code{markdown-mode}, though expect to find -it elsewhere like in @code{Info-mode}. - -In practice it means that the user can safely opt for a more -prose-friendly proportionately spaced typeface as their default, while -letting spacing-sensitive elements like tables and inline code always -use a monospaced font, by inheriting from the @code{fixed-pitch} face. - -Users can try the built-in @kbd{M-x variable-pitch-mode} to see the -effect in action. - -To make everything use your desired font families, you need to configure -the @code{variable-pitch} (proportional spacing) and @code{fixed-pitch} (monospaced) -faces respectively. It may also be convenient to set your main typeface -by configuring the @code{default} face the same way. - -Put something like this in your initialization file (also consider -reading the doc string of @code{set-face-attribute}): - -@lisp -;; Main typeface -(set-face-attribute 'default nil :family "DejaVu Sans Mono" :height 110) - -;; Proportionately spaced typeface -(set-face-attribute 'variable-pitch nil :family "DejaVu Serif" :height 1.0) - -;; Monospaced typeface -(set-face-attribute 'fixed-pitch nil :family "DejaVu Sans Mono" :height 1.0) -@end lisp - -Note the differences in the @samp{:height} property. The @samp{default} face must -specify an absolute value, which is the point size × 10. So if you want -to use a font at point size @samp{11}, you set the height to @samp{110}.@footnote{@samp{:height} -values do not need to be rounded to multiples of ten: the likes of @samp{115} -are perfectly valid—some typefaces will change to account for those -finer increments.} Whereas every other face must have a value that is -relative to the default, represented as a floating point (if you use an -integer, then that means an absolute height). This is of paramount -importance: it ensures that all fonts can scale gracefully when using -something like the @code{text-scale-adjust} command which only operates on the -base font size (i.e. the @code{default} face's absolute height). - -@node Custom Org user faces (DIY) -@section Custom Org user faces (DIY) - -@cindex Org extra faces - -Users of @code{org-mode} have the option to configure various keywords and -priority cookies to better match their workflow. User options are -@code{org-todo-keyword-faces} and @code{org-priority-faces}. - -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 -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 -the active Modus theme but by how Org maps faces to its constructs. -Editing those while @code{org-mode} is active requires re-initialization of the -mode with @kbd{M-x org-mode-restart} for changes to take effect. - -Let us assume you wish to visually differentiate your keywords. You -have something like this: - -@lisp -(setq org-todo-keywords - '((sequence "TODO(t)" "|" "DONE(D)" "CANCEL(C)") - (sequence "MEET(m)" "|" "MET(M)") - (sequence "STUDY(s)" "|" "STUDIED(S)") - (sequence "WRITE(w)" "|" "WROTE(W)"))) -@end lisp - -You could then use a variant of the following to inherit from a face -that uses the styles you want and also to preserve the properties -applied by the @code{org-todo} face: - -@lisp -(setq org-todo-keyword-faces - '(("MEET" . '(font-lock-preprocessor-face org-todo)) - ("STUDY" . '(font-lock-variable-name-face org-todo)) - ("WRITE" . '(font-lock-type-face org-todo)))) -@end lisp - -This will refashion the keywords you specify, while letting the other -items in @code{org-todo-keywords} use their original styles (which are defined -in the @code{org-todo} and @code{org-done} faces). - -If you want back the defaults, try specifying just the @code{org-todo} face: - -@lisp -(setq org-todo-keyword-faces - '(("MEET" . org-todo) - ("STUDY" . org-todo) - ("WRITE" . org-todo))) -@end lisp - -When you inherit from multiple faces, you need to quote the list as -shown further above. The order is important: the last item is applied -over the previous ones. If you do not want to blend multiple faces, you -do not need a quoted list. A pattern of @samp{keyword . face} will suffice. - -Both approaches can be used simultaneously, as illustrated in this -configuration of the priority cookies: - -@lisp -(setq org-priority-faces - '((?A . '(org-scheduled-today org-priority)) - (?B . org-priority) - (?C . '(shadow org-priority)))) -@end lisp - -To find all the faces that are loaded in your current Emacs session, use -@kbd{M-x list-faces-display}. Try @kbd{M-x describe-variable} as well and -then specify the name of each of those Org variables demonstrated above. -Their documentation strings will offer you further guidance. - -Recall that the themes let you retrieve a color from their palette. Do -it if you plan to control face attributes. - -@ref{Case-by-case face specs using the themes' palette (DIY), , Custom face specs using the themes' palette}. - -@ref{Measure color contrast (DIY), , Check color combinations}. - -@node Measure color contrast (DIY) -@section Measure color contrast (DIY) - -@findex modus-themes-contrast -@findex modus-themes-wcag-formula -@cindex Color contrast - -The themes provide the functions @code{modus-themes-wcag-formula} and -@code{modus-themes-contrast}. The former is a direct implementation of the -WCAG formula: @uref{https://www.w3.org/TR/WCAG20-TECHS/G18.html}. It -calculates the relative luminance of a color value that is expressed in -hexadecimal RGB notation. While the latter function is just a -convenient wrapper for comparing the relative luminance between two -colors. - -In practice, one needs to work only with @code{modus-themes-contrast}. It -accepts two color values and returns their contrast ratio. Values range -from 1 to 21 (lowest to highest). The themes are designed to always be -equal or higher than 7 for each combination of background and foreground -that they use (this is the WCAG AAA standard---the most demanding of its -kind). - -A couple of examples (rounded numbers): - -@lisp -;; Pure white with pure green -(modus-themes-contrast "#ffffff" "#00ff00") -;; => 1.37 -;; That is an outright inaccessible combo - -;; Pure black with pure green -(modus-themes-contrast "#000000" "#00ff00") -;; => 15.3 -;; That is is a highly accessible combo -@end lisp - -It does not matter which color value comes first. The ratio is always -the same. - -If one does not wish to read all the decimal points, it is possible to -try something like this: - -@lisp -(format "%0.2f" (modus-themes-contrast "#000000" "#00ff00")) -@end lisp - -While it is fine to perform such calculations on a case-by-case basis, -it is preferable to implement formulas and tables for more demanding -tasks. Such instruments are provided by @code{org-mode} or @code{orgtbl-mode}, both -of which are built into Emacs. Below is such a table that derives the -contrast ratio of all colors in the first column (pure red, green, blue) -relative to the color specified in the first row of the second column -(pure white) and rounds the results: - -@example -| | #ffffff | -|---------+---------| -| #ff0000 | 4.00 | -| #00ff00 | 1.37 | -| #0000ff | 8.59 | -#+tblfm: $2='(modus-themes-contrast $1 @@1$2);%0.2f -@end example - -To measure color contrast one needs to start from a known value. This -typically is the background. The Modus themes define an expanded -palette in large part because certain colors are only meant to be used -in combination with some others. Consult the source code for the -minutia and relevant commentary. - -Such knowledge may prove valuable while attempting to override some of -the themes' colors: @ref{Override colors (DIY), , Override colors}. - -@node Load theme depending on time of day -@section Load theme depending on time of day - -While we do provide @code{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. - -This can be accomplished by specifying the coordinates of one's location -using the built-in @file{solar.el} and then configuring the @samp{circadian} -package: - -@lisp -(use-package solar ; built-in - :config - (setq calendar-latitude 35.17 - calendar-longitude 33.36)) - -(use-package circadian ; you need to install this - :ensure - :after solar - (setq circadian-themes '((:sunrise . modus-operandi) - (:sunset . modus-vivendi))) - (circadian-setup)) -@end lisp - -@node A theme-agnostic hook for theme loading (DIY) -@section A theme-agnostic hook for theme loading (DIY) - -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 -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 the @code{modus-themes-after-load-theme-hook}, -which runs after @code{modus-themes-toggle}, @code{modus-themes-load-operandi}, or -@code{modus-themes-load-vivendi} is evaluated. We recommend using that hook -for advanced customizations, because (1) we 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. - -Advanced users who have a need to switch between the Modus themes and -other items will find that such a hook does not meet their requirements: -it only works with the Modus themes and only with the aforementioned -functions. - -A theme-agnostic setup can be configured thus: - -@lisp -(defvar after-enable-theme-hook nil - "Normal hook run after enabling a theme.") - -(defun run-after-enable-theme-hook (&rest _args) - "Run `after-enable-theme-hook'." - (run-hooks 'after-enable-theme-hook)) - -(advice-add 'enable-theme :after #'run-after-enable-theme-hook) -@end lisp - -This creates the @code{after-enable-theme-hook} and makes it run after each -call to @code{enable-theme}, which means that it will work for all themes and -also has the benefit that it does not depend on functions such as -@code{modus-themes-toggle} and the others mentioned above. @code{enable-theme} is -called internally by @code{load-theme}, so the hook works everywhere. - -Now this specific piece of Elisp may be simple for experienced users, -but it is not easy to read for newcomers, including the author of the -Modus themes for the first several months of their time as an Emacs -user. Hence our hesitation to recommend it as part of the standard -setup of the Modus themes (it is generally a good idea to understand -what the implications are of advising a function). - -@node Face coverage -@chapter 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 -experience across all available interfaces. - -@menu -* Supported packages:: Full list of covered face groups -* Indirectly covered packages:: -@end menu - -@node Supported packages -@section Full support for packages or face groups - -@cindex Explicitly supported packages - -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 -affected face groups. The items with an appended asterisk @samp{*} tend to -have lots of extensions, so the ``full support'' may not be 100% true… - -@itemize -@item -ace-window -@item -ag -@item -alert -@item -all-the-icons -@item -annotate -@item -anzu -@item -apropos -@item -apt-sources-list -@item -artbollocks-mode -@item -auctex and @TeX{} -@item -auto-dim-other-buffers -@item -avy -@item -awesome-tray -@item -bbdb -@item -binder -@item -bm -@item -bongo -@item -boon -@item -breakpoint (provided by the built-in @file{gdb-mi.el} library) -@item -buffer-expose -@item -calendar and diary -@item -calfw -@item -centaur-tabs -@item -cfrs -@item -change-log and log-view (such as @code{vc-print-log}, @code{vc-print-root-log}) -@item -cider -@item -circe -@item -color-rg -@item -column-enforce-mode -@item -company-mode* -@item -company-posframe -@item -compilation-mode -@item -completions -@item -consult -@item -counsel* -@item -counsel-css -@item -counsel-notmuch -@item -counsel-org-capture-string -@item -cov -@item -cperl-mode -@item -csv-mode -@item -ctrlf -@item -custom (what you get with @kbd{M-x customize}) -@item -dap-mode -@item -dashboard (emacs-dashboard) -@item -deadgrep -@item -debbugs -@item -define-word -@item -deft -@item -dictionary -@item -diff-hl -@item -diff-mode -@item -dim-autoload -@item -dir-treeview -@item -dired -@item -dired-async -@item -dired-git -@item -dired-git-info -@item -dired-narrow -@item -dired-subtree -@item -diredc -@item -diredfl -@item -diredp (dired+) -@item -disk-usage -@item -display-fill-column-indicator-mode -@item -doom-modeline -@item -dynamic-ruler -@item -easy-jekyll -@item -easy-kill -@item -ebdb -@item -ediff -@item -eglot -@item -el-search -@item -eldoc-box -@item -elfeed -@item -elfeed-score -@item -emms -@item -enhanced-ruby-mode -@item -epa -@item -equake -@item -erc -@item -eros -@item -ert -@item -eshell -@item -eshell-fringe-status -@item -eshell-git-prompt -@item -eshell-prompt-extras (epe) -@item -eshell-syntax-highlighting -@item -evil* (evil-mode) -@item -evil-goggles -@item -evil-snipe -@item -evil-visual-mark-mode -@item -eww -@item -exwm -@item -eyebrowse -@item -fancy-dabbrev -@item -flycheck -@item -flycheck-color-mode-line -@item -flycheck-indicator -@item -flycheck-posframe -@item -flymake -@item -flyspell -@item -flyspell-correct -@item -flx -@item -freeze-it -@item -frog-menu -@item -focus -@item -fold-this -@item -font-lock (generic syntax highlighting) -@item -forge -@item -fountain (fountain-mode) -@item -geiser -@item -git-commit -@item -git-gutter (and variants) -@item -git-lens -@item -git-rebase -@item -git-timemachine -@item -git-walktree -@item -gnus -@item -golden-ratio-scroll-screen -@item -helm* -@item -helm-ls-git -@item -helm-switch-shell -@item -helm-xref -@item -helpful -@item -highlight-blocks -@item -highlight-defined -@item -highlight-escape-sequences (@code{hes-mode}) -@item -highlight-indentation -@item -highlight-numbers -@item -highlight-symbol -@item -highlight-tail -@item -highlight-thing -@item -hl-defined -@item -hl-fill-column -@item -hl-line-mode -@item -hl-todo -@item -hydra -@item -hyperlist -@item -ibuffer -@item -icomplete -@item -icomplete-vertical -@item -ido-mode -@item -iedit -@item -iflipb -@item -imenu-list -@item -indium -@item -info -@item -info-colors -@item -interaction-log -@item -ioccur -@item -isearch, occur, etc. -@item -isl (isearch-light) -@item -ivy* -@item -ivy-posframe -@item -jira (org-jira) -@item -journalctl-mode -@item -js2-mode -@item -julia -@item -jupyter -@item -kaocha-runner -@item -keycast -@item -line numbers (@code{display-line-numbers-mode} and global variant) -@item -lsp-mode -@item -lsp-ui -@item -macrostep -@item -magit -@item -magit-imerge -@item -make-mode -@item -man -@item -marginalia -@item -markdown-mode -@item -markup-faces (@code{adoc-mode}) -@item -mentor -@item -messages -@item -minibuffer-line -@item -minimap -@item -mmm-mode -@item -modeline -@item -mood-line -@item -moody -@item -mpdel -@item -mu4e -@item -mu4e-conversation -@item -multiple-cursors -@item -neotree -@item -no-emoji -@item -notmuch -@item -num3-mode -@item -nxml-mode -@item -objed -@item -orderless -@item -org* -@item -org-journal -@item -org-noter -@item -org-pomodoro -@item -org-recur -@item -org-roam -@item -org-superstar -@item -org-table-sticky-header -@item -org-tree-slide -@item -org-treescope -@item -origami -@item -outline-mode -@item -outline-minor-faces -@item -package (what you get with @kbd{M-x list-packages}) -@item -page-break-lines -@item -paradox -@item -paren-face -@item -parrot -@item -pass -@item -pdf-tools -@item -persp-mode -@item -perspective -@item -phi-grep -@item -phi-search -@item -pkgbuild-mode -@item -pomidor -@item -popup -@item -powerline -@item -powerline-evil -@item -prism (@ref{Note for prism, , Note for prism.el}) -@item -proced -@item -prodigy -@item -quick-peek -@item -racket-mode -@item -rainbow-blocks -@item -rainbow-identifiers -@item -rainbow-delimiters -@item -rcirc -@item -recursion-indicator -@item -regexp-builder (also known as @code{re-builder}) -@item -rg (rg.el) -@item -ripgrep -@item -rmail -@item -ruler-mode -@item -sallet -@item -selectrum -@item -selectrum-prescient -@item -semantic -@item -sesman -@item -shell-script-mode -@item -shortdoc -@item -show-paren-mode -@item -shr -@item -side-notes -@item -sieve-mode -@item -skewer-mode -@item -smart-mode-line -@item -smartparens -@item -smerge -@item -solaire -@item -spaceline -@item -speedbar -@item -spell-fu -@item -spray -@item -stripes -@item -suggest -@item -switch-window -@item -swiper -@item -swoop -@item -sx -@item -symbol-overlay -@item -syslog-mode -@item -table (built-in table.el) -@item -telephone-line -@item -terraform-mode -@item -term -@item -tomatinho -@item -transient (pop-up windows such as Magit's) -@item -trashed -@item -treemacs -@item -tty-menu -@item -tuareg -@item -typescript -@item -undo-tree -@item -vc (built-in mode line status for version control) -@item -vc-annotate (the out put of @kbd{C-x v g}) -@item -vdiff -@item -vimish-fold -@item -visible-mark -@item -visual-regexp -@item -volatile-highlights -@item -vterm -@item -wcheck-mode -@item -web-mode -@item -wgrep -@item -which-function-mode -@item -which-key -@item -whitespace-mode -@item -window-divider-mode -@item -winum -@item -writegood-mode -@item -woman -@item -xah-elisp-mode -@item -xref -@item -xterm-color (and ansi-colors) -@item -yaml-mode -@item -yasnippet -@item -ztree -@end itemize - -Plus many other miscellaneous faces that are provided by the upstream -GNU Emacs distribution. - -@node Indirectly covered packages -@section Indirectly covered packages - -@cindex Implicitly supported packages - -These do not require any extra styles because they are configured to -inherit from some basic faces. Please confirm. - -@itemize -@item -edit-indirect -@item -evil-owl -@item -fortran-mode -@item -goggles -@item -i3wm-config-mode -@item -perl-mode -@item -php-mode -@item -rjsx-mode -@item -swift-mode -@item -tab-bar-echo-area -@end itemize - -@node Notes for individual packages -@chapter Notes for individual packages - -This section covers information that may be of interest to users of -individual packages. - -@menu -* Note for display-fill-column-indicator-mode:: -* Note for mmm-mode.el background colors: Note for mmm-modeel background colors. -* Note for prism:: -* Note on company-mode overlay pop-up:: -* Note for ERC escaped color sequences:: -* Note for powerline or spaceline:: -* Note on SHR colors:: -* Note for Helm grep:: -* Note on vc-annotate-background-mode:: -* Note on pdf-tools link hints:: -@end menu - -@node Note for display-fill-column-indicator-mode -@section Note for display-fill-column-indicator-mode - -While designing the style for @code{display-fill-column-indicator-mode}, we -stayed close to the mode's defaults: to apply a subtle foreground color -to the @code{fill-column-indicator} face, which blends well with the rest of -theme and is consistent with the role of that mode. This is to not -upset the expectations of users. - -Nevertheless, @code{display-fill-column-indicator-mode} has some known -limitations pertaining to its choice of using typographic characters to -draw its indicator. What should be a continuous vertical line might -appear as a series of dashes in certain contexts or under specific -conditions: a non-default value for @code{line-spacing}, scaled and/or -variable-pitch headings have been observed to cause this effect. - -Given that we cannot control such factors, it may be better for affected -users to deviate from the default style of the @code{fill-column-indicator} -face. Instead of setting a foreground color, one could use a background -and have the foreground be indistinguishable from it. For example: - -@lisp -(modus-themes-with-colors - (custom-set-faces - `(fill-column-indicator ((,class :background ,bg-inactive - :foreground ,bg-inactive))))) -@end lisp - -@ref{Face specs at scale using the themes' palette (DIY), , Face specs at scale using the themes' palette}. - -@node Note for mmm-modeel background colors -@section Note for mmm-mode.el background colors - -The faces used by @file{mmm-mode.el} are expected to have a colorful -background, while they should not touch any foreground value. The idea -is that they must not interfere with existing fontification. Those -background colors need to be distinct from each other, such as an -unambiguous red juxtaposed with a clear blue. - -While this design may be internally consistent with the raison d'être of -that library, it inevitably produces inaccessible color combinations. - -There are two competing goals at play: - -@enumerate -@item -Legibility of the text, understood as the contrast ratio between the -background and the foreground. - -@item -Semantic precision of each face which entails faithfulness to -color-coding of the underlying background. -@end enumerate - -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 -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. - -@ref{Face specs at scale using the themes' palette (DIY), , Face specs at scale using the themes' palette}. - -This example uses more vivid background colors, though it comes at the -very high cost of degraded legibility. - -@lisp -(modus-themes-with-colors - (custom-set-faces - `(mmm-cleanup-submode-face ((,class :background ,yellow-refine-bg))) - `(mmm-code-submode-face ((,class :background ,bg-active))) - `(mmm-comment-submode-face ((,class :background ,blue-refine-bg))) - `(mmm-declaration-submode-face ((,class :background ,cyan-refine-bg))) - `(mmm-default-submode-face ((,class :background ,bg-alt))) - `(mmm-init-submode-face ((,class :background ,magenta-refine-bg))) - `(mmm-output-submode-face ((,class :background ,red-refine-bg))) - `(mmm-special-submode-face ((,class :background ,green-refine-bg))))) -@end lisp - -@node Note for prism -@section Note for prism.el - -This package by Adam Porter, aka ``alphapapa'' or ``github-alphapapa'', -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 customisations, we 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 offer a starting point for users to adapt to their needs. - -In the following code snippets, we employ the @code{modus-themes-with-colors} -macro: @ref{Face specs at scale using the themes' palette (DIY), , Face specs at scale using the themes' palette}. - -These are the minimum recommended settings with 16 colors: - -@lisp -(setq prism-num-faces 16) - -(prism-set-colors - :desaturations '(0) ; do not change---may lower the contrast ratio - :lightens '(0) ; same - :colors (modus-themes-with-colors - (list fg-main - magenta - cyan-alt-other - magenta-alt-other - blue - magenta-alt - cyan-alt - red-alt-other - green - fg-main - cyan - yellow - blue-alt - red-alt - green-alt-other - fg-special-warm))) -@end lisp - -With 8 colors: - -@lisp -(setq prism-num-faces 8) - -(prism-set-colors - :desaturations '(0) ; do not change---may lower the contrast ratio - :lightens '(0) ; same - :colors (modus-themes-with-colors - (list fg-special-cold - magenta - magenta-alt-other - cyan-alt-other - fg-main - blue-alt - red-alt-other - cyan))) -@end lisp - -And this is with 4 colors, which produces results that are the closest -to the themes' default aesthetic: - -@lisp -(setq prism-num-faces 4) - -(prism-set-colors - :desaturations '(0) ; do not change---may lower the contrast ratio - :lightens '(0) ; same - :colors (modus-themes-with-colors - (list fg-main - cyan-alt-other - magenta-alt-other - magenta))) -@end lisp - -If you need to apply desaturation and lightening, you can use what the -@file{prism.el} documentation recommends, like this (adapting to the -examples with the 4, 8, 16 colors): - -@lisp -(prism-set-colors - :desaturations (cl-loop for i from 0 below 16 collect (* i 2.5)) - :lightens (cl-loop for i from 0 below 16 collect (* i 2.5)) - :colors (modus-themes-with-colors - (list fg-main - cyan-alt-other - magenta-alt-other - magenta))) -@end lisp - -@node Note on company-mode overlay pop-up -@section Note on company-mode overlay pop-up - -By default, the @code{company-mode} pop-up that lists completion candidates is -drawn using an overlay. This creates alignment issues every time it is -placed above a piece of text that has a different height than the -default. - -The solution recommended by the project's maintainer is to use an -alternative front-end for drawing the pop-up which draws child frames -instead of overlays.@footnote{@uref{https://github.com/company-mode/company-mode/issues/1010}}@footnote{@uref{https://github.com/tumashu/company-posframe/}} - -@node Note for ERC escaped color sequences -@section Note for ERC escaped color sequences - -The built-in IRC client @code{erc} has the ability to colorise any text using -escape sequences that start with @samp{^C} (inserted with @kbd{C-q C-c}) and are -followed by a number for the foreground and background.@footnote{This page -explains the basics, though it is not specific to Emacs: -@uref{https://www.mirc.com/colors.html}} Possible numbers are 0-15, with the -first entry being the foreground and the second the background, -separated by a comma. Like this @samp{^C1,6}. The minimum setup is this: - -@lisp -(add-to-list 'erc-modules 'irccontrols) -(setq erc-interpret-controls-p t - erc-interpret-mirc-color t) -@end lisp - -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 -accessibility standard of the themes: - -@table @asis -@item Modus Operandi -Use foreground color 1 for all backgrounds from -2-15. Like so: @kbd{C-q C-c1} where @samp{N} is the background. - -@item Modus Vivendi -Use foreground color 0 for all backgrounds from -2-13. Use foreground @samp{1} for backgrounds 14, 15. -@end table - -Colors 0 and 1 are white and black respectively. So combine them -together, if you must. - -@node Note for powerline or spaceline -@section Note for powerline or spaceline - -Both Powerline and Spaceline package users will likely need to use the -command @code{powerline-reset} whenever they make changes to their themes -and/or modeline setup. - -@node Note on SHR colors -@section Note on SHR colors - -Emacs' HTML rendering library (@file{shr.el}) may need explicit -configuration to respect the theme's colors instead of whatever -specifications the webpage provides. - -Consult @kbd{C-h v shr-use-colors}. - -@node Note for Helm grep -@section Note for Helm grep - -There is one face from the Helm package that is meant to highlight the -matches of a grep or grep-like command (@samp{ag} or @samp{ripgrep}). It is -@code{helm-grep-match}. However, this face can only apply when the user does -not pass @samp{--color=always} as a command-line option for their command. - -Here is the docstring for that face, which is defined in the -@file{helm-grep.el} library (you can always visit the source code with -@kbd{M-x find-library}). - -@quotation -Face used to highlight grep matches. Have no effect when grep backend -use ``--color='' - -@end quotation - -The user must either remove @samp{--color} from the flags passed to the grep -function, or explicitly use @samp{--color=never} (or equivalent). Helm -provides user-facing customization options for controlling the grep -function's parameters, such as @code{helm-grep-default-command} and -@code{helm-grep-git-grep-command}. - -When @samp{--color=always} is in effect, the grep output will use red text in -bold letter forms to present the matching part in the list of -candidates. That style still meets the contrast ratio target of >= 7:1 -(accessibility standard WCAG AAA), because it draws the reference to -ANSI color number 1 (red) from the already-supported array of -@code{ansi-color-names-vector}. - -@node Note on vc-annotate-background-mode -@section Note on vc-annotate-background-mode - -Due to the unique way @code{vc-annotate} (@kbd{C-x v g}) applies colors, support -for its background mode (@code{vc-annotate-background-mode}) is disabled at the -theme level. - -Normally, such a drastic measure should not belong in a theme: assuming -the user's preferences is bad practice. However, it has been deemed -necessary in the interest of preserving color contrast accessibility -while still supporting a useful built-in tool. - -If there actually is a way to avoid such a course of action, without -prejudice to the accessibility standard of this project, then please -report as much or send patches (@ref{Contributing}). - -@node Note on pdf-tools link hints -@section Note on pdf-tools link hints - -Hints are drawn by @uref{https://imagemagick.org/, ImageMagick}, not Emacs, i.e., ImageMagick doesn't -know about the hint face unless you tell ImageMagick about it. By -default, only the foreground and background color attributes are -passed. The below snippet adds to those the various font attributes. As -it queries various faces, specifically @code{pdf-links-read-link} and the faces -it inherits, it needs to be added to your initialization file after -you've customized any faces. - -@lisp -(use-package pdf-links - :config - (let ((spec - (apply #'append - (mapcar - (lambda (name) - (list name - (face-attribute 'pdf-links-read-link - name nil 'default))) - '(:family :width :weight :slant))))) - (setq pdf-links-read-link-convert-commands - `("-density" "96" - "-family" ,(plist-get spec :family) - "-stretch" ,(let* ((width (plist-get spec :width)) - (name (symbol-name width))) - (replace-regexp-in-string "-" "" - (capitalize name))) - "-weight" ,(pcase (plist-get spec :weight) - ('ultra-light "Thin") - ('extra-light "ExtraLight") - ('light "Light") - ('semi-bold "SemiBold") - ('bold "Bold") - ('extra-bold "ExtraBold") - ('ultra-bold "Black") - (_weight "Normal")) - "-style" ,(pcase (plist-get spec :slant) - ('italic "Italic") - ('oblique "Oblique") - (_slant "Normal")) - "-pointsize" "%P" - "-undercolor" "%f" - "-fill" "%b" - "-draw" "text %X,%Y '%c'")))) -@end lisp - -@node Contributing -@chapter Contributing - -This section documents the canonical sources of the themes and the ways -in which you can contribute to their ongoing development. - -@menu -* Sources of the themes:: -* Issues you can help with:: -* Patches require copyright assignment to the FSF:: -@end menu - -@node Sources of the themes -@section Sources of the themes - -@cindex Sources of the themes - -The @code{modus-operandi} and @code{modus-vivendi} themes are built into Emacs. -Currently they are in Emacs' git main branch (trunk), which is tracking -the next development release target. - -The source code of the themes is @uref{https://gitlab.com/protesilaos/modus-themes/, available on Gitlab}, for the time -being. A @uref{https://github.com/protesilaos/modus-themes/, mirror on Github} is also on offer. - -An HTML version of this manual is provided as an extension of the -@uref{https://protesilaos.com/modus-themes/, author's personal website} (does not rely on any non-free code). - -@node Issues you can help with -@section Issues you can help with - -@cindex Contributing - -A few tasks you can help with: - -@itemize -@item -Suggest refinements to packages that are covered. -@item -Report packages not covered thus far. -@item -Report bugs, inconsistencies, shortcomings. -@item -Help expand the documentation of covered-but-not-styled packages. -@item -Suggest refinements to the color palette. -@item -Help expand this document or any other piece of documentation. -@item -Merge requests for code refinements. -@end itemize - -@ref{Patches require copyright assignment to the FSF}. - -It is preferable that your feedback includes some screenshots, GIFs, or -short videos, as well as further instructions to reproduce a given -setup. Though this is not a requirement. - -Whatever you do, bear in mind the overarching objective of the Modus -themes: to keep a contrast ratio that is greater or equal to 7:1 between -background and foreground colors. If a compromise is ever necessary -between aesthetics and accessibility, it shall always be made in the -interest of the latter. - -@node Patches require copyright assignment to the FSF -@section Patches require copyright assignment to the FSF - -Code contributions are most welcome. For any major edit (more than 15 -lines, or so, in aggregate per person), you need to make a copyright -assignment to the Free Software Foundation. This is necessary because -the themes are part of the upstream Emacs distribution: the FSF must at -all times be in a position to enforce the GNU General Public License. - -Copyright assignment is a simple process. Check the request form below -(please adapt it accordingly). You must write an email to the address -mentioned in the form and then wait for the FSF to send you a legal -agreement. Sign the document and file it back to them. This could all -happen via email and take about a week. You are encouraged to go -through this process. You only need to do it once. It will allow you -to make contributions to Emacs in general. - -@example -Please email the following information to assign@@gnu.org, and we -will send you the assignment form for your past and future changes. - -Please use your full legal name (in ASCII characters) as the subject -line of the message. ----------------------------------------------------------------------- -REQUEST: SEND FORM FOR PAST AND FUTURE CHANGES - -[What is the name of the program or package you're contributing to?] - -GNU Emacs - -[Did you copy any files or text written by someone else in these changes? -Even if that material is free software, we need to know about it.] - -Copied a few snippets from the same files I edited. Their author, -Protesilaos Stavrou, has already assigned copyright to the Free Software -Foundation. - -[Do you have an employer who might have a basis to claim to own -your changes? Do you attend a school which might make such a claim?] - - -[For the copyright registration, what country are you a citizen of?] - - -[What year were you born?] - - -[Please write your email address here.] - - -[Please write your postal address here.] - - - - - -[Which files have you changed so far, and which new files have you written -so far?] - -@end example - -@node Acknowledgements -@chapter Acknowledgements - -@cindex Contributors - -The Modus themes are a collective effort. Every bit of work matters. - -@table @asis -@item Author/maintainer -Protesilaos Stavrou. - -@item Contributions to code or documentation -Anders Johansson, Basil -L@.@: Contovounesios, Carlo Zancanaro, Eli Zaretskii, Kostadin -Ninev, Madhavan Krishnan, Markus Beppler, Matthew Stevenson, Nicolas -De Jaeghere, Shreyas Ragavan, Stefan Kangas, Vincent Murphy, Xinglu -Chen. - -@item Ideas and user feedback -Aaron Jensen, Adam Spiers, Adrian Manea, -Alex Griffin, Alex Peitsinis, Alexey Shmalko, Alok Singh, Anders -Johansson, André Alexandre Gomes, Arif Rezai, Basil L@.@: -Contovounesios, Burgess Chang, Christian Tietze, Christopher Dimech, -Damien Cassou, Daniel Mendler, Dario Gjorgjevski, David Edmondson, -Davor Rotim, Divan Santana, Gerry Agbobada, Gianluca Recchia, Gustavo -Barros, Hörmetjan Yiltiz, Ilja Kocken, Iris Garcia, Jeremy Friesen, -John Haman, Joshua O'Connor, Kevin Fleming, Kostadin Ninev, Len Trigg, -Manuel Uberti, Mark Burton, Markus Beppler, Michael Goldenberg, Morgan -Smith, Murilo Pereira, Nicolas De Jaeghere, Paul Poloskov, Pete -Kazmier, Peter Wu, Philip K., Pierre Téchoueyres, Roman Rudakov, Ryan -Phillips, Sam Kleinman, Shreyas Ragavan, Simon Pugnet, Tassilo Horn, -Thibaut Verron, Trey Merkley, Togan Muftuoglu, Toon Claes, Uri Sharf, -Utkarsh Singh, Vincent Foley. As well as users: Ben, CsBigDataHub1, -Emacs Contrib, Eugene, Fourchaux, Fredrik, Moesasji, Nick, TheBlob42, -bepolymathe, doolio, fleimgruber, iSeeU, jixiuf, okamsn. - -@item Packaging -Basil L@.@: Contovounesios, Eli Zaretskii, Glenn -Morris, Mauro Aranda, Richard Stallman, Stefan Kangas (core Emacs), -Stefan Monnier (GNU Elpa), André Alexandre Gomes, Dimakakos Dimos, -Morgan Smith, Nicolas Goaziou (Guix), Dhavan Vaidya (Debian). - -@item Inspiration for certain features -Bozhidar Batsov (zenburn-theme), -Fabrice Niessen (leuven-theme). -@end table - -Special thanks, in no particular order, to Manuel Uberti and Omar -Antolín Camarena for their long time contributions and insightful -commentary. - -@node Meta -@chapter Meta - -@cindex Development notes - -If you are curious about the principles that govern the development of -this project read the essay @uref{https://protesilaos.com/codelog/2020-03-17-design-modus-themes-emacs/, On the design of the Modus themes} -(2020-03-17). - -Here are some more publications for those interested in the kind of work -that goes into this project (sometimes the commits also include details -of this sort): - -@itemize -@item -@uref{https://protesilaos.com/codelog/2020-05-10-modus-operandi-palette-review/, Modus Operandi theme subtle palette review} (2020-05-10) -@item -@uref{https://protesilaos.com/codelog/2020-06-13-modus-vivendi-palette-review/, Modus Vivendi theme subtle palette review} (2020-06-13) -@item -@uref{https://protesilaos.com/codelog/2020-07-04-modus-themes-faint-colours/, Modus themes: new ``faint syntax'' option} (2020-07-04) -@item -@uref{https://protesilaos.com/codelog/2020-07-08-modus-themes-nuanced-colours/, Modus themes: major review of ``nuanced'' colours} (2020-07-08) -@item -@uref{https://protesilaos.com/codelog/2020-09-14-modus-themes-review-blues/, Modus themes: review of blue colours} (2020-09-14) -@item -@uref{https://protesilaos.com/codelog/2020-12-27-modus-themes-review-rainbow-delimiters/, Modus themes: review rainbow-delimiters faces} (2020-12-27) -@item -@uref{https://protesilaos.com/codelog/2021-01-11-modus-themes-review-select-faint-colours/, Modus themes: review of select ``faint'' colours} (2021-01-11) -@item -@uref{https://protesilaos.com/codelog/2021-02-25-modus-themes-diffs-deuteranopia/, The Modus themes now cover deuteranopia in diffs} (2021-02-25) -@end itemize - -And here are the canonical sources of this project's documentation: - -@table @asis -@item Manual -@uref{https://protesilaos.com/modus-themes} -@item Change Log -@uref{https://protesilaos.com/modus-themes-changelog} -@item Screenshots -@uref{https://protesilaos.com/modus-themes-pictures} -@end table - -@node GNU Free Documentation License -@appendix GNU Free Documentation License - -@include doclicense.texi - -@node Indices -@chapter Indices - -@menu -* Function index:: -* Variable index:: -* Concept index:: -@end menu - -@node Function index -@section Function index - -@printindex fn - -@node Variable index -@section Variable index - -@printindex vr - -@node Concept index -@section Concept index - -@printindex cp - -@bye \ No newline at end of file