diff options
Diffstat (limited to 'doc/misc/modus-themes.org')
| -rw-r--r-- | doc/misc/modus-themes.org | 4677 |
1 files changed, 4677 insertions, 0 deletions
diff --git a/doc/misc/modus-themes.org b/doc/misc/modus-themes.org new file mode 100644 index 00000000000..5bb230f892a --- /dev/null +++ b/doc/misc/modus-themes.org @@ -0,0 +1,4677 @@ +#+title: Modus themes for GNU Emacs +#+author: Protesilaos Stavrou +#+email: info@protesilaos.com +#+language: en +#+options: ':t toc:nil author:t email:t num:t +#+startup: content + +#+macro: stable-version 1.5.0 +#+macro: release-date 2021-07-15 +#+macro: development-version 1.6.0-dev +#+macro: file @@texinfo:@file{@@$1@@texinfo:}@@ +#+macro: space @@texinfo:@: @@ +#+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@ + +#+texinfo_filename: modus-themes.info +#+texinfo_dir_category: Emacs misc features +#+texinfo_dir_title: Modus Themes: (modus-themes) +#+texinfo_dir_desc: Highly accessible themes (WCAG AAA) +#+texinfo_header: @set MAINTAINERSITE @uref{https://protesilaos.com,maintainer webpage} +#+texinfo_header: @set MAINTAINER Protesilaos Stavrou +#+texinfo_header: @set MAINTAINEREMAIL @email{info@protesilaos.com} +#+texinfo_header: @set MAINTAINERCONTACT @uref{mailto:info@protesilaos.com,contact the maintainer} + +#+texinfo: @insertcopying + +This manual, written by Protesilaos Stavrou, describes the customization +options for the ~modus-operandi~ and ~modus-vivendi~ themes, and provides +every other piece of information pertinent to them. + +The documentation furnished herein corresponds to stable version +{{{stable-version}}}, released on {{{release-date}}}. Any reference to a newer +feature which does not yet form part of the latest tagged commit, is +explicitly marked as such. + +Current development target is {{{development-version}}}. + +#+toc: headlines 8 insert TOC here, with eight headline levels + +* COPYING +:properties: +:copying: t +:custom_id: h:b14c3fcb-13dd-4144-9d92-2c58b3ed16d3 +:end: + +Copyright (C) 2020-2021 Free Software Foundation, Inc. + +#+begin_quote +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 the Front-Cover Texts being “A GNU Manual,” and +with the Back-Cover Texts as in (a) below. A copy of the license is +included in the section entitled “GNU Free Documentation License.” + +(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and +modify this GNU manual.” +#+end_quote + +* Overview +:properties: +:custom_id: h:f0f3dbcb-602d-40cf-b918-8f929c441baf +:end: + +The Modus themes are designed for accessible readability. They conform +with the highest standard for color contrast between 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 (~modus-operandi~) is a light theme, while Modus Vivendi +(~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 +([[#h:a9c8f29d-7f72-4b54-b74b-ddefe15d6a19][Face coverage]]). + +Furthermore, the themes are designed to empower users with red-green +color deficiency (deuteranopia). This is achieved through customization +options which have the effect of replacing all relevant instances of +green with a variant of blue ([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization Options]]). + +Starting with version 0.12.0 and onwards, the themes are built into GNU +Emacs. + +** How do the themes look like +:properties: +:custom_id: h:69b92089-069c-4ba1-9d94-cc3415fc4f87 +:end: +#+cindex: Screenshots + +Check the web page with [[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. + +[[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization options]]. + +** Learn about the latest changes +:properties: +:custom_id: h:2cc37c36-6c1a-48b2-a010-1050b270ee18 +:end: +#+cindex: Changelog + +Please refer to the [[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. + +* Installation +:properties: +:custom_id: h:1af85373-7f81-4c35-af25-afcef490c111 +:end: + +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. + +** Install manually from source +:properties: +:custom_id: h:da3414b7-1426-46b8-8e76-47b845b76fd0 +:end: + +In the following example, we are assuming that your Emacs files are +stored in =~/.emacs.d= and that you want to place the Modus themes in +=~/.emacs.d/modus-themes=. + +1. Get the source and store it in the desired path by running the + following in the command line shell: + +: $ git clone https://gitlab.com/protesilaos/modus-themes.git ~/.emacs.d/modus-themes + +2. 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)}}}): + +#+begin_src emacs-lisp +(add-to-list 'load-path "~/.emacs.d/modus-themes") +#+end_src + +The themes are now ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]. + +** Install from the archives +:properties: +:custom_id: h:c4b10085-149f-43e2-bd4d-347f33aee054 +:end: + +The ~modus-themes~ package is available from the GNU ELPA archive, which +is configured by default. + +Prior to querying any package archive, make sure to 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 ~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: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]. + +** Install on GNU/Linux +:properties: +:custom_id: h:da640eb1-95dd-4e86-bb4e-1027b27885f0 +:end: + +The themes are also available from the archives of some distributions of +GNU/Linux. These should correspond to a tagged release rather than +building directly from the latest Git commit. It all depends on the +distro's packaging policies. + +*** Debian 11 Bullseye +:properties: +:custom_id: h:7e570360-9ee6-4bc5-8c04-9dc11418a3e4 +:end: + +The themes are part of Debian 11 Bullseye. Get them with: + +#+begin_src sh +sudo apt install elpa-modus-themes +#+end_src + +They are now ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]. + +*** GNU Guix +:properties: +:custom_id: h:a4ca52cd-869f-46a5-9e16-4d9665f5b88e +:end: + +Users of Guix can get the themes with this command: + +#+begin_src sh +guix package -i emacs-modus-themes +#+end_src + +They are now ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]. + +* Enable and load +:properties: +:custom_id: h:3f3c3728-1b34-437d-9d0c-b110f5b161a9 +:end: +#+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: + +#+begin_src emacs-lisp +(load-theme 'modus-operandi) ; Light theme +(load-theme 'modus-vivendi) ; Dark theme +#+end_src + +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: + +#+begin_src emacs-lisp +(require 'modus-themes) +#+end_src + +Then it is recommended to load the individual theme files with the +helper function ~modus-themes-load-themes~: + +#+begin_src emacs-lisp +;; Load the theme files before enabling a theme (else you get an error). +(modus-themes-load-themes) +#+end_src + +Once the libraries that define the themes are enabled, one can activate +a theme with either of the following expressions: + +#+begin_src emacs-lisp +(modus-themes-load-operandi) ; Light theme +;; OR +(modus-themes-load-vivendi) ; Dark theme +#+end_src + +Changes to the available customization options must always be evaluated +before loading a theme ([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization Options]]). An exception to this +norm is when using the various Custom interfaces or with commands like +{{{kbd(M-x customize-set-variable)}}}, which automatically reload the theme by +default ([[#h:9001527a-4e2c-43e0-98e8-3ef72d770639][Option for inhibiting theme reload]]). This is how a basic setup +could look like: + +#+begin_src emacs-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 "<f5>") #'modus-themes-toggle) +#+end_src + +[[#h:e979734c-a9e1-4373-9365-0f2cd36107b8][Sample configuration for use-package]]. + +With those granted, bear in mind a couple of technical points on +~modus-themes-load-operandi~ and ~modus-themes-load-vivendi~, as well as +~modus-themes-toggle~ which relies on them: + +1. Those functions call ~load-theme~. Some users prefer to opt for + ~enable-theme~ instead ([[#h:e68560b3-7fb0-42bc-a151-e015948f8a35][Differences between loading and enabling]]). + +2. The functions will run the ~modus-themes-after-load-theme-hook~ as + their final step. This can be employed for bespoke configurations + ([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][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 ([[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][A theme-agnostic hook for theme loading]]). + +** Sample configuration for use-package +:properties: +:custom_id: h:e979734c-a9e1-4373-9365-0f2cd36107b8 +:end: +#+cindex: use-package configuration + +It is common for Emacs users to rely on ~use-package~ for declaring +package configurations in their setup. We use this as an example: + +#+begin_src emacs-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-italic-constructs t + modus-themes-bold-constructs nil + modus-themes-region '(bg-only no-extend)) + + ;; 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 ("<f5>" . modus-themes-toggle)) +#+end_src + +[[#h:e68560b3-7fb0-42bc-a151-e015948f8a35][Differences between loading and enabling]]. + +Note: make sure not to customize the variable ~custom-theme-load-path~ +or ~custom-theme-directory~ after the themes' package declaration. That +will lead to failures in loading the files. If either or both of those +variables need to be changed, their values should be defined before the +package declaration of the themes. + +** Differences between loading and enabling +:properties: +:custom_id: h:e68560b3-7fb0-42bc-a151-e015948f8a35 +:end: +#+cindex: load-theme VS enable-theme + +The reason we recommend ~load-theme~ instead of the other option of +~enable-theme~ is that the former does a kind of "reset" on the face +specs. It quite literally loads (or 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, ~load-theme~ reads all customizations that may happen during +any given Emacs session: even after the initial setup of a theme. +Examples are calls to ~custom-set-faces~, as well as new values assigned +to the options the Modus themes provide ([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization Options]]). + +Our tests show that ~enable-theme~ does not read such variables anew, so +it might appear to the unsuspecting user that the themes are somehow +broken whenever they try to assign a new value to a customization option +or some face. + +This "reset" that ~load-theme~ conducts does, however, come at the cost +of being somewhat slower than ~enable-theme~. Users who have a stable +setup and who seldom update their variables during a given Emacs +session, are better off using something like this: + +#+begin_src emacs-lisp +(require 'modus-themes) +(load-theme 'modus-operandi t t) +(load-theme 'modus-vivendi t t) + +(enable-theme 'modus-operandi) ;; OR (enable-theme 'modus-vivendi) +#+end_src + +[[#h:e979734c-a9e1-4373-9365-0f2cd36107b8][Sample configuration for use-package]]. + +With the above granted, other sections of the manual discuss how to +configure custom faces, where ~load-theme~ is expected, though +~enable-theme~ could still apply in stable setups: + +[[#h:1487c631-f4fe-490d-8d58-d72ffa3bd474][Case-by-case face specs using the themes' palette]]. + +[[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]. + +* Customization Options +:properties: +:custom_id: h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f +:end: + +The Modus themes are highly configurable, though they should work well +without any further tweaks. By default, all customization options are +set to nil, unless otherwise noted in this manual. + +Remember that all customization options must be evaluated before loading +a theme ([[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]). + +Below is a summary of what you will learn in the subsequent sections of +this manual. + +#+begin_src emacs-lisp +(setq modus-themes-italic-constructs t + modus-themes-bold-constructs nil + modus-themes-no-mixed-fonts nil + modus-themes-subtle-line-numbers nil + modus-themes-success-deuteranopia t + modus-themes-inhibit-reload t ; only applies to `customize-set-variable' and related + + modus-themes-fringes nil ; {nil,'subtle,'intense} + + ;; Options for `modus-themes-lang-checkers' are either nil (the + ;; default), or a list of properties that may include any of those + ;; symbols: `straight-underline', `text-also', `background', + ;; `intense' + modus-themes-lang-checkers nil + + ;; Options for `modus-themes-mode-line' are either nil, or a list + ;; that can combine any of `3d' OR `moody', `borderless', + ;; `accented'. The variable's doc string shows all possible + ;; combinations. + modus-themes-mode-line '(3d accented) + + ;; Options for `modus-themes-syntax' are either nil (the default), + ;; or a list of properties that may include any of those symbols: + ;; `faint', `yellow-comments', `green-strings', `alt-syntax' + modus-themes-syntax nil + + ;; Options for `modus-themes-hl-line' are either nil (the default), + ;; or a list of properties that may include any of those symbols: + ;; `accented', `underline', `intense' + modus-themes-hl-line '(underline accented) + + ;; Options for `modus-themes-paren-match' are either nil (the + ;; default), or a list of properties that may include any of those + ;; symbols: `bold', `intense', `underline' + modus-themes-paren-match '(bold intense) + + ;; Options for `modus-themes-links' are either nil (the default), + ;; or a list of properties that may include any of those symbols: + ;; `neutral-underline' OR `no-underline', `faint' OR `no-color', + ;; `bold', `italic', `background' + modus-themes-links '(neutral-underline background) + + ;; Options for `modus-themes-prompts' are either nil (the + ;; default), or a list of properties that may include any of those + ;; symbols: `background', `bold', `gray', `intense', `italic' + modus-themes-prompts '(intense bold) + + modus-themes-completions 'moderate ; {nil,'moderate,'opinionated} + + modus-themes-mail-citations nil ; {nil,'faint,'monochrome} + + ;; Options for `modus-themes-region' are either nil (the default), + ;; or a list of properties that may include any of those symbols: + ;; `no-extend', `bg-only', `accented' + modus-themes-region '(bg-only no-extend) + + ;; Options for `modus-themes-diffs': nil, 'desaturated, + ;; 'bg-only, 'deuteranopia, 'fg-only-deuteranopia + modus-themes-diffs 'fg-only-deuteranopia + + modus-themes-org-blocks 'gray-background ; {nil,'gray-background,'tinted-background} + + modus-themes-org-agenda ; this is an alist: read the manual or its doc string + '((header-block . (variable-pitch scale-title)) + (header-date . (grayscale workaholic bold-today)) + (scheduled . uniform) + (habit . traffic-light-deuteranopia)) + + modus-themes-headings ; this is an alist: read the manual or its doc string + '((1 . (overline background)) + (2 . (rainbow overline)) + (t . (no-bold))) + + modus-themes-variable-pitch-ui nil + modus-themes-variable-pitch-headings t + modus-themes-scale-headings t + modus-themes-scale-1 1.1 + modus-themes-scale-2 1.15 + modus-themes-scale-3 1.21 + modus-themes-scale-4 1.27 + modus-themes-scale-title 1.33) +#+end_src + +** Option for inhibiting theme reload +:properties: +:alt_title: Custom reload theme +:description: Toggle auto-reload of the theme when setting custom variables +:custom_id: h:9001527a-4e2c-43e0-98e8-3ef72d770639 +:end: +#+vindex: modus-themes-inhibit-reload + +Symbol: ~modus-themes-inhibit-reload~ + +Possible values: + +1. ~nil~ +2. ~t~ (default) + +By default, customizing a theme-related user option through the Custom +interfaces or with {{{kbd(M-x customize-set-variable)}}} will not reload the +currently active Modus theme. + +Enable this behaviour by setting this variable to ~nil~. + +** Option for color-coding success state (deuteranopia) +:properties: +:alt_title: Success' color-code +:description: Toggle blue color for success or done states +:custom_id: h:3ed03a48-20d8-4ce7-b214-0eb7e4c79abe +:end: +#+vindex: modus-themes-success-deuteranopia + +Symbol: ~modus-themes-success-deuteranopia~ + +Possible values: + +1. ~nil~ (default) +2. ~t~ + +The default is to colorise all faces that denote "success", "done", or +similar with a variant of green. + +With a non-nil value (~t~), use variants of blue instead of green. This +is meant to empower users with red-green color deficiency. + +The present customization option should apply to all contexts where +there can be a color-coded distinction between success and failure, +to-do and done, and so on. + +Diffs, which have a red/green dichotomy by default, can also be +configured to conform with deuteranopia. + +[[#h:ea7ac54f-5827-49bd-b09f-62424b3b6427][Option for diff buffer looks]]. + +** Option for more bold constructs +:properties: +:alt_title: Bold constructs +:description: Toggle bold constructs in code +:custom_id: h:b25714f6-0fbe-41f6-89b5-6912d304091e +:end: +#+vindex: modus-themes-bold-constructs + +Symbol: ~modus-themes-bold-constructs~ + +Possible values: + +1. ~nil~ (default) +2. ~t~ + +The default is to use a bold typographic weight only when it is +required. + +With a non-nil value (~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. + +Advanced users may also want to configure the exact attributes of the +~bold~ face. + +[[#h:2793a224-2109-4f61-a106-721c57c01375][Configure bold and italic faces]]. + +** Option for more italic constructs +:properties: +:alt_title: Italic constructs +:description: Toggle italic font constructs in code +:custom_id: h:977c900d-0d6d-4dbb-82d9-c2aae69543d6 +:end: +#+vindex: modus-themes-italic-constructs + +Symbol: ~modus-themes-italic-constructs~ + +Possible values: + +1. ~nil~ (default) +2. ~t~ + +The default is to not use slanted text forms (italics) unless it is +absolutely necessary. + +With a non-nil value (~t~) choose to render more faces in italics. This +typically affects documentation strings and code comments. + +Advanced users may also want to configure the exact attributes of the +~italic~ face. + +[[#h:2793a224-2109-4f61-a106-721c57c01375][Configure bold and italic faces]]. + +** Option for syntax highlighting +:properties: +:alt_title: Syntax styles +:description: Choose the overall aesthetic of code syntax +:custom_id: h:c119d7b2-fcd4-4e44-890e-5e25733d5e52 +:end: +#+vindex: modus-themes-syntax + +Symbol: ~modus-themes-syntax~ + +Possible values are expressed as a list of properties (default is ~nil~ or +an empty list). The list can include any of the following symbols: + ++ ~faint~ ++ ~yellow-comments~ ++ ~green-strings~ ++ ~alt-syntax~ + +The default (a ~nil~ value or an empty list) is to use a balanced +combination of colors on the cyan-blue-magenta side of the spectrum. +There is little to no use of greens, yellows, and reds. Comments are +gray, strings are blue colored, doc strings are a shade of cyan, while +color combinations are designed to avoid exaggerations. + +The property ~faint~ fades the saturation of all applicable colors, where +that is possible or appropriate. + +The property ~yellow-comments~ applies a yellow color to comments. + +The property ~green-strings~ applies a green color to strings and a green +tint to doc strings. + +The property ~alt-syntax~ changes the combination of colors beyond strings +and comments, so that the effective palette is broadened to provide +greater variety relative to the default. + +Combinations of any of those properties are expressed as a list, like in +these examples: + +#+begin_src emacs-lisp +(faint) +(green-strings yellow-comments) +(alt-syntax green-strings yellow-comments) +(faint alt-syntax green-strings yellow-comments) +#+end_src + +The order in which the properties are set is not significant. + +In user configuration files the form may look like this: + +#+begin_src emacs-lisp +(setq modus-themes-syntax '(faint alt-syntax)) +#+end_src + +Independent of this variable, users may also control the use of a bold +weight or italic text: ~modus-themes-bold-constructs~ and +~modus-themes-italic-constructs~. + +[[#h:b25714f6-0fbe-41f6-89b5-6912d304091e][Option for more bold constructs]]. + +[[#h:977c900d-0d6d-4dbb-82d9-c2aae69543d6][Option for more italic constructs]]. + +** Option for no font mixing +:properties: +:alt_title: No mixed fonts +:description: Toggle mixing of font families +:custom_id: h:115e6c23-ee35-4a16-8cef-e2fcbb08e28b +:end: +#+vindex: modus-themes-no-mixed-fonts + +Symbol: ~modus-themes-no-mixed-fonts~ + +Possible values: + +1. ~nil~ (default) +2. ~t~ + +By default, the themes configure some spacing-sensitive faces like Org +tables and code blocks to always inherit from the ~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 ~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 ~org-variable-pitch~ and ~mixed-pitch~. + +[[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. + +** Option for links +:properties: +:alt_title: Link styles +:description: Choose among several styles, with or without underline +:custom_id: h:c119d7b2-fcd4-4e44-890e-5e25733d5e52 +:end: +#+vindex: modus-themes-links + +Symbol: ~modus-themes-links~ + +Possible values are expressed as a list of properties (default is ~nil~ or +an empty list). The list can include any of the following symbols: + ++ Underline style: + - ~neutral-underline~ + - ~no-underline~ ++ Text coloration: + - ~faint~ + - ~no-color~ ++ ~bold~ ++ ~italic~ ++ ~background~ + +The default (a ~nil~ value or an empty list) is a prominent text color, +typically blue, with an underline of the same color. + +For the style of the underline, a ~neutral-underline~ property turns the +color of the line into a subtle gray, while the ~no-underline~ property +removes the line altogether. If both of those are set, the latter takes +precedence. + +For text coloration, a ~faint~ property desaturates the color of the text +and the underline, unless the underline is affected by the +aforementioned properties. While a ~no-color~ property removes the color +from the text. If both of those are set, the latter takes precedence. + +A ~bold~ property applies a heavy typographic weight to the text of the +link. + +An ~italic~ property adds a slant to the link's text (italic or oblique +forms, depending on the typeface). + +A ~background~ property applies a subtle tinted background color. + +In case both ~no-underline~ and ~no-color~ are set, then a subtle gray +background is applied to all links. This can still be combined with the +~bold~ and ~italic~ properties. + +Combinations of any of those properties are expressed as a list, +like in these examples: + +#+begin_src emacs-lisp +(faint) +(no-underline faint) +(no-color no-underline bold) +(italic bold background no-color no-underline) +#+end_src + +The order in which the properties are set is not significant. + +In user configuration files the form may look like this: + +#+begin_src emacs-lisp +(setq modus-themes-links '(neutral-underline background)) +#+end_src + +The placement of the underline, meaning its proximity to the text, is +controlled by ~x-use-underline-position-properties~, +~x-underline-at-descent-line~, ~underline-minimum-offset~. Please refer to +their documentation strings. + +** Option for command prompt styles +:properties: +:alt_title: Command prompts +:description: Choose among plain, subtle, or intense prompts +:custom_id: h:db5a9a7c-2928-4a28-b0f0-6f2b9bd52ba1 +:end: +#+vindex: modus-themes-prompts + +Symbol: ~modus-themes-prompts~ + +Possible values are expressed as a list of properties (default is ~nil~ or +an empty list). The list can include any of the following symbols: + ++ ~background~ ++ ~bold~ ++ ~gray~ ++ ~intense~ ++ ~italic~ + +The default (a ~nil~ value or an empty list) means to only use a subtle +accented foreground color. + +The property ~background~ applies a background color to the prompt's text. +By default, this is a subtle accented value. + +The property ~intense~ makes the foreground color more prominent. If the +~background~ property is also set, it amplifies the value of the +background as well. + +The property ~gray~ changes the prompt's colors to grayscale. This +affects the foreground and, if the ~background~ property is also set, the +background. Its effect is subtle, unless it is combined with the +~intense~ property. + +The property ~bold~ makes the text use a bold typographic weight. +Similarly, ~italic~ adds a slant to the font's forms (italic or oblique +forms, depending on the typeface). + +Combinations of any of those properties are expressed as a list, like in +these examples: + +#+begin_src emacs-lisp +(intense) +(bold intense) +(intense bold gray) +(intense background gray bold) +#+end_src + +The order in which the properties are set is not significant. + +In user configuration files the form may look like this: + +#+begin_src emacs-lisp +(setq modus-themes-prompts '(background gray)) +#+end_src + +** Option for mode line presentation +:properties: +:alt_title: Mode line +:description: Choose among several styles, with or without borders +:custom_id: h:27943af6-d950-42d0-bc23-106e43f50a24 +:end: +#+vindex: modus-themes-mode-line + +Symbol: ~modus-themes-mode-line~ + +Possible values, which can be expressed as a list of combinations of box +effect, color, and border visibility: + ++ Overall style: + - ~3d~ + - ~moody~ ++ ~accented~ ++ ~borderless~ + +The default (a nil value or an empty list) is a two-dimensional +rectangle with a border around it. The active and the inactive +mode lines use different shades of grayscale values for the +background, foreground, border. + +The ~3d~ property applies a three-dimensional effect to the +active mode line. The inactive mode lines remain two-dimensional +and are toned down a bit, relative to the default style. + +The ~moody~ property optimizes the mode line for use with the +library of the same name (hereinafter referred to as 'Moody'). +In practice, it removes the box effect and replaces it with +underline and overline properties. It also tones down the +inactive mode lines. Despite its intended purpose, this option +can also be used without the Moody library (please consult the +themes' manual on this point for more details). If both ~3d~ and +~moody~ properties are set, the latter takes precedence. + +The ~borderless~ property removes the color of the borders. It +does not actually remove the borders, but only makes their color +the same as the background, effectively creating some padding. + +The ~accented~ property ensures that the active mode line uses a +colored background instead of the standard shade of gray. + +Combinations of any of those properties are expressed as a list, +like in these examples: + +#+begin_src emacs-lisp +(accented) +(borderless 3d) +(moody accented borderless) +#+end_src + +The order in which the properties are set is not significant. + +In user configuration files the form may look like this: + +#+begin_src emacs-lisp +(setq modus-themes-prompts '(borderless accented)) +#+end_src + +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 ~moody~ property, +which will come into effect when the background of the mode line changes +to something less accessible, such as Moody ribbons (read the doc string +of ~set-face-attribute~, specifically ~: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 practice, users will need to experiment with the variable +~face-near-same-color-threshold~ to trigger the effect. We find that a +value of =45000= shall suffice, contrary to the default =30000=. Though for +the combinations that involve the ~accented~ and ~moody~ properties, as +mentioned above, that should be raised up to =70000=. Do not set it too +high, because it has the adverse effect of always overriding the default +colors (which have been carefully designed to be highly accessible). + +Furthermore, because Moody expects an underline and overline instead of +a box style, it is advised to set ~x-underline-at-descent-line~ to a +non-nil value. + +** Option for completion framework aesthetics +:properties: +:alt_title: Completion UIs +:description: Choose among standard, moderate, or opinionated looks +:custom_id: h:f1c20c02-7b34-4c35-9c65-99170efb2882 +:end: +#+vindex: modus-themes-completions + +Symbol: ~modus-themes-completions~ + +Possible values: + +1. ~nil~ (default) +2. ~moderate~ +3. ~opinionated~ + +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, Vertico, as +well as pattern matching styles like Orderless and Flx. The latter +covers Helm, Ivy, and Sallet. + +A value of ~nil~ (the default) will simply respect the metaphors of each +completion framework. + +Option ~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 ~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 ~nil~ (default), ~moderate~, and ~opinionated~ +possibilities. + +** Option for mail citations +:properties: +:alt_title: Mail citations +:description: Choose among colorful, desaturated, monochrome citations +:custom_id: h:5a12765d-0ba0-4a75-ab11-e35d3bbb317d +:end: +#+vindex: modus-themes-mail-citations + +Symbol: ~modus-themes-mail-citations~ + +Possible values: + +1. ~nil~ (default) +2. ~faint~ +3. ~monochrome~ + +By default, citations in email-related buffers apply contrasting hues to +different levels of depth in cited text. The colors are fairly easy to +tell apart. + +A value of ~faint~ makes all citation levels less intense, while retaining +the default style of contrasting hues (albeit very subtle ones). + +Option ~monochrome~ turns all citations in to a uniform shade of gray. + +Whatever the value assigned to this variable, citations in emails are +controlled by typographic elements or indentation, which the themes do +not touch. + +** Option for fringe visibility +:properties: +:alt_title: Fringes +:description: Choose among invisible, subtle, or intense fringe styles +:custom_id: h:1983c3fc-74f6-44f3-b917-967c403bebae +:end: +#+vindex: modus-themes-fringes + +Symbol: ~modus-themes-fringes~ + +Possible values: + +1. ~nil~ (default) +2. ~subtle~ +3. ~intense~ + +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 ~fringe-mode~. + +Options ~subtle~ and ~intense~ apply a gray background, making the fringes +visible. The difference between the two is one of degree, as their +names imply. + +** Option for language checkers +:properties: +:alt_title: Language checkers +:description: Control the style of language checkers/linters +:custom_id: h:4b13743a-8ebf-4d2c-a043-cceba10b1eb4 +:end: +#+vindex: modus-themes-lang-checkers + +Symbol: ~modus-themes-lang-checkers~ + +Possible values are expressed as a list of properties (default is ~nil~ or +an empty list). The list can include any of the following symbols: + ++ ~straight-underline~ ++ ~text-also~ ++ ~background~ ++ ~intense~ + +The default (a ~nil~ value or an empty list) applies a color-coded +underline to the affected text, while it leaves the original foreground +intact. If the display spec of Emacs has support for it, the +underline's style is that of a wave, otherwise it is a straight line. + +The property ~straight-underline~ ensures that the underline under the +affected text is always drawn as a straight line. + +The property ~text-also~ applies the same color of the underline to the +affected text. + +The property ~background~ adds a color-coded background. + +The property ~intense~ amplifies the applicable colors if ~background~ +and/or ~text-only~ are set. If ~intense~ is set on its own, then it implies +~text-only~. + +To disable fringe indicators for Flymake or Flycheck, refer to variables +~flymake-fringe-indicator-position~ and ~flycheck-indication-mode~, +respectively. + +Combinations of any of those properties can be expressed in a +list, as in those examples: + +#+begin_src emacs-lisp +(background) +(straight-underline intense) +(background text-also straight-underline) +#+end_src + +The order in which the properties are set is not significant. + +In user configuration files the form may look like this: + +#+begin_src emacs-lisp +(setq modus-themes-lang-checkers '(text-also background)) +#+end_src + +NOTE: The placement of the straight underline, though not the wave +style, is controlled by the built-in variables ~underline-minimum-offset~, +~x-underline-at-descent-line~, ~x-use-underline-position-properties~. + +** Option for line highlighting (hl-line-mode) +:properties: +:alt_title: Line highlighting +:description: Choose style of current line (hl-line-mode) +:custom_id: h:1dba1cfe-d079-4c13-a810-f768e8789177 +:end: +#+vindex: modus-themes-hl-line + +Symbol: ~modus-themes-hl-line~ + +Possible values are expressed as a list of properties (default is ~nil~ or +an empty list). The list can include any of the following symbols: + ++ ~accented~ ++ ~intense~ ++ ~underline~ + +The default (a ~nil~ value or an empty list) is a subtle gray background +color. + +The property ~accented~ changes the background to a colored variant. + +An ~underline~ property draws a line below the highlighted area. Its +color is similar to the background, so gray by default or an accent +color when ~accented~ is also set. + +An ~intense~ property amplifies the colors in use, which may be both the +background and the underline. + +Combinations of any of those properties are expressed as a list, like in +these examples: + +#+begin_src emacs-lisp +(intense) +(underline intense) +(accented intense underline) +#+end_src + +The order in which the properties are set is not significant. + +In user configuration files the form may look like this: + +#+begin_src emacs-lisp +(setq modus-themes-hl-line '(underline accented)) +#+end_src + +Set ~x-underline-at-descent-line~ to a non-nil value for better results +with underlines. + +This style affects several packages that enable ~hl-line-mode~, such as +=elfeed=, =notmuch=, and =mu4e=. + +** Option for line numbers (display-line-numbers-mode) +:properties: +:alt_title: Line numbers +:description: Toggle subtle style for line numbers +:custom_id: h:8c4a6230-2e43-4aa2-a631-3b7179392e09 +:end: +#+vindex: modus-themes-subtle-line-numbers + +Symbol: ~modus-themes-subtle-line-numbers~ + +Possible value: + +1. ~nil~ (default) +2. ~t~ + +The default style for ~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 ~display-line-numbers-major-tick~ and its +counterpart ~display-line-numbers-minor-tick~ use appropriate styles that +involve a bespoke background and foreground combination. + +With a non-nil value (~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. + +** Option for parenthesis matching (show-paren-mode) +:properties: +:alt_title: Matching parentheses +:description: Choose between various styles for matching delimiters/parentheses +:custom_id: h:e66a7e4d-a512-4bc7-9f86-fbbb5923bf37 +:end: +#+vindex: modus-themes-paren-match + +Symbol: ~modus-themes-paren-match~ + +Possible values are expressed as a list of properties (default is ~nil~ or +an empty list). The list can include any of the following symbols: + ++ ~bold~ ++ ~intense~ ++ ~underline~ + +The default (a ~nil~ value or an empty list) is a subtle background color. + +The ~bold~ property adds a bold weight to the characters of the matching +delimiters. + +The ~intense~ property applies a more prominent background color to the +delimiters. + +The ~underline~ property draws a straight line under the affected text. + +Combinations of any of those properties are expressed as a list, like in +these examples: + +#+begin_src emacs-lisp +(bold) +(underline intense) +(bold intense underline) +#+end_src + +The order in which the properties are set is not significant. + +In user configuration files the form may look like this: + +#+begin_src emacs-lisp +(setq modus-themes-paren-match '(bold intense)) +#+end_src + +This customization variable affects the built-in ~show-paren-mode~ and the +=smartparens= package. + +** Option for active region +:properties: +:alt_title: Active region +:description: Choose between various styles for the active region +:custom_id: h:60798063-b4ad-45ea-b9a7-ff7b5c0ab74c +:end: +#+vindex: modus-themes-region + +Symbol: ~modus-themes-region~ + +Possible values are expressed as a list of properties (default is ~nil~ or +an empty list). The list can include any of the following symbols: + ++ ~no-extend~ ++ ~bg-only~ ++ ~accented~ + +The default (a ~nil~ value or an empty list) is a prominent gray +background that overrides all foreground colors in the area it +encompasses. Its reach extends to the edge of the window. + +The ~no-extend~ property limits the region to the end of the line, so that +it does not reach the edge of the window. + +The ~bg-only~ property makes the region's background color more subtle to +allow the underlying text to retain its foreground colors. + +The ~accented~ property applies a more colorful background to the region. + +Combinations of any of those properties are expressed as a list, like in +these examples: + +#+begin_src emacs-lisp +(no-extend) +(bg-only accented) +(accented bg-only no-extend) +#+end_src + +The order in which the properties are set is not significant. + +In user configuration files the form may look like this: + +#+begin_src emacs-lisp +(setq modus-themes-region '(bg-only no-extend)) +#+end_src + +** Option for diff buffer looks +:properties: +:alt_title: Diffs +:description: Choose among intense, desaturated, or text-only diffs +:custom_id: h:ea7ac54f-5827-49bd-b09f-62424b3b6427 +:end: +#+vindex: modus-themes-diffs + +Symbol: ~modus-themes-diffs~ + +Possible values: + +1. ~nil~ (default) +2. ~desaturated~ +3. ~bg-only~ +4. ~deuteranopia~ +5. ~fg-only-deuteranopia~ + +The default (~nil~) uses fairly intense color combinations for diffs, by +applying prominently colored backgrounds, with appropriate foregrounds. + +Option ~desaturated~ follows the same principles as with the default +(~nil~), though it tones down all relevant colors. + +Option ~bg-only~ applies a background but does not override the text's +foreground. This makes it suitable for a non-nil value passed to +~diff-font-lock-syntax~ (note: Magit does not support syntax highlighting +in diffs---last checked on 2021-04-21). + +Option ~deuteranopia~ is like the default (~nil~) in terms of using +prominently colored backgrounds, except that it also accounts for +red-green color defficiency by replacing all instances of green with +colors on the blue side of the spectrum. Other stylistic changes are +made in the interest of optimizing for such a use-case. + +Option ~fg-only-deuteranopia~ removes all colored backgrounds, except from +word-wise or refined changes. Instead, it only uses color-coded +foreground values to differentiate between added, removed, and changed +lines. If a background is necessary to denote context, a subtle +grayscale value is applied. The color used for added lines is a variant +of blue to account for red-green color defficiency but also because +green text alone is hard to discern in the diff's context (hard for our +accessibility purposes). The ~fg-only~ option that existed in older +versions of the themes is now an alias of ~fg-only-deuteranopia~, in the +interest of backward compatibility. + +** Option for org-mode block styles +:properties: +:alt_title: Org mode blocks +:description: Choose among plain, gray, or tinted backgrounds +:custom_id: h:b7e328c0-3034-4db7-9cdf-d5ba12081ca2 +:end: +#+vindex: modus-themes-org-blocks + +Symbol: ~modus-themes-org-blocks~ + +Possible values: + +1. ~nil~ (default) +2. ~gray-background~ (value ~grayscale~ exists for backward compatibility) +3. ~tinted-background~ (value ~rainbow~ exists for backward compatibility) + +The default means that the block has no distinct background of its own +and uses the one that applies to the rest of the buffer. + +Option ~gray-background~ applies a subtle gray background to the block's +contents. It also affects the begin and end lines of the block: their +background extends to the edge of the window for Emacs version >= 27 +where the ~:extend~ keyword is recognized by ~set-face-attribute~ (this is +contingent on the variable ~org-fontify-whole-block-delimiter-line~). + +Option ~tinted-background~ uses a slightly colored background for the +contents of the block. The exact color will depend on the programming +language and is controlled by the variable ~org-src-block-faces~ (refer to +the theme's source code for the current association list). For this to +take effect, Org must be restarted with {{{kbd(M-x org-mode-restart)}}}. + +Code blocks use their major mode's colors only when the variable +~org-src-fontify-natively~ is non-nil. While quote/verse blocks require +setting ~org-fontify-quote-and-verse-blocks~ to a non-nil value. + +[[#h:f44cc6e3-b0f1-4a5e-8a90-9e48fa557b50][Update Org block delimiter fontification]]. + +Older versions of the themes provided options ~grayscale~ (or ~greyscale~) +and ~rainbow~. Those will continue to work as they are aliases for +~gray-background~ and ~tinted-background~, respectively. + +** Option for Org agenda constructs +:properties: +:alt_title: Org agenda +:description: Control each element in the presentation of the agenda +:custom_id: h:68f481bc-5904-4725-a3e6-d7ecfa7c3dbc +:end: +#+vindex: modus-themes-org-agenda + +Symbol: ~modus-themes-org-agenda~ + +This is an alist that accepts a =(key . value)= combination. Some values +are specified as a list. Here is a sample, followed by a description of +all possible combinations: + +#+begin_src emacs-lisp +(setq modus-themes-org-agenda + '((header-block . (variable-pitch scale-title)) + (header-date . (grayscale workaholic bold-today)) + (scheduled . uniform) + (habit . traffic-light))) +#+end_src + +A ~header-block~ key applies to elements that concern the headings which +demarcate blocks in the structure of the agenda. By default (a ~nil~ +value) those are rendered in a bold typographic weight, plus a height +that is slightly taller than the default font size. Acceptable values +come in the form of a list that can include either or both of those +properties: + +- ~variable-pitch~ to use a proportionately spaced typeface; +- ~scale-title~ to increase the size to the number assigned to + ~modus-themes-scale-title~ ([[#h:6868baa1-beba-45ed-baa5-5fd68322ccb3][Control the scale of headings]]) or ~no-scale~ + to make the font use the same height as the rest of the buffer. + +In case both ~scale-title~ and ~no-scale~ are in the list, the latter takes +precedence. + +Example usage: + +#+begin_src emacs-lisp +(header-block . nil) +(header-block . (scale-title)) +(header-block . (no-scale)) +(header-block . (variable-pitch scale-title)) +#+end_src + +A ~header-date~ key covers date headings. Dates use only a foreground +color by default (a ~nil~ value), with weekdays and weekends having a +slight difference in hueness. The current date has an added gray +background. This key accepts a list of values that can include any of +the following properties: + +- ~grayscale~ to make weekdays use the main foreground color and + weekends a more subtle gray; +- ~workaholic~ to make weekdays and weekends look the same in + terms of color; +- ~bold-today~ to apply a bold typographic weight to the current + date; +- ~bold-all~ to render all date headings in a bold weight. + +For example: + +#+begin_src emacs-lisp +(header-date . nil) +(header-date . (workaholic)) +(header-date . (grayscale bold-all)) +(header-date . (grayscale workaholic)) +(header-date . (grayscale workaholic bold-today)) +#+end_src + +A ~scheduled~ key applies to tasks with a scheduled date. By default (a +~nil~ value), those use varying shades of yellow to denote (i) a past or +current date and (ii) a future date. Valid values are symbols: + +- nil (default); +- ~uniform~ to make all scheduled dates the same color; +- ~rainbow~ to use contrasting colors for past, present, future + scheduled dates. + +For example: + +#+begin_src emacs-lisp +(scheduled . nil) +(scheduled . uniform) +(scheduled . rainbow) +#+end_src + +A ~habit~ key applies to the ~org-habit~ graph. All possible value are +passed as a symbol. Those are: + +- The default (~nil~) is meant to conform with the original aesthetic of + ~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 ~org-habit~ consistency graph. +- ~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. +- ~traffic-light~ further reduces the available colors to red, yellow, and + green. As in ~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. +- ~traffic-light-deuteranopia~ is like the ~traffic-light~ except its three + colors are red, yellow, and blue to be suitable for users with + red-green color deficiency (deuteranopia). + +For example: + +#+begin_src emacs-lisp +(habit . nil) +(habit . simplified) +(habit . traffic-light) +#+end_src + +Putting it all together, the alist can look like this: + +#+begin_src emacs-lisp +'((header-block . (scale-title variable-pitch)) + (header-date . (grayscale workaholic bold-today)) + (scheduled . uniform) + (habit . traffic-light)) + +;; Or else: +(setq modus-themes-org-agenda + '((header-block . (scale-title variable-pitch)) + (header-date . (grayscale workaholic bold-today)) + (scheduled . uniform) + (habit . traffic-light))) +#+end_src + +** Option for the headings' overall style +:properties: +:alt_title: Heading styles +:description: Choose among several styles, also per heading level +:custom_id: h:271eff19-97aa-4090-9415-a6463c2f9ae1 +:end: +#+vindex: modus-themes-headings + +Symbol: ~modus-themes-headings~ + +This is an alist that accepts a =(key . list-of-values)= combination. The +key is either a number, representing the heading's level or ~t~, which +pertains to the fallback style. The list of values covers symbols that +refer to properties, as described below. Here is a sample, followed by +a presentation of all available properties: + +#+begin_src emacs-lisp +(setq modus-themes-headings + '((1 . (background overline)) + (2 . (overline rainbow)) + (t . (monochrome)))) +#+end_src + +Properties: + ++ ~rainbow~ ++ ~overline~ ++ ~background~ ++ ~no-bold~ ++ ~monochrome~ + +By default (a ~nil~ value for this variable), all headings have a bold +typographic weight and use a desaturated text color. + +A ~rainbow~ property makes the text color more saturated. + +An ~overline~ property draws a line above the area of the heading. + +A ~background~ property adds a subtle tinted color to the background of +the heading. + +A ~no-bold~ property removes the bold weight from the heading's text. + +A ~monochrome~ property makes all headings the same base color, which is +that of the default for the active theme (black/white). When ~background~ +is also set, ~monochrome~ changes its color to gray. If both ~monochrome~ +and ~rainbow~ are set, the former takes precedence. + +Combinations of any of those properties are expressed as a list, like in +these examples: + +#+begin_src emacs-lisp +(no-bold) +(rainbow background) +(overline monochrome no-bold) +#+end_src + +The order in which the properties are set is not significant. + +In user configuration files the form may look like this: + +#+begin_src emacs-lisp +(setq modus-themes-headings + '((1 . (background overline rainbow)) + (2 . (background overline)) + (t . (overline no-bold)))) +#+end_src + +When defining the styles per heading level, it is possible to pass a +non-nil value (~t~) instead of a list of properties. This will retain the +original aesthetic for that level. For example: + +#+begin_src emacs-lisp +(setq modus-themes-headings + '((1 . t) ; keep the default style + (2 . (background overline)) + (t . (rainbow)))) ; style for all other headings + +(setq modus-themes-headings + '((1 . (background overline)) + (2 . (rainbow no-bold)) + (t . t))) ; default style for all other levels +#+end_src + +For Org users, the extent of the heading depends on the variable +~org-fontify-whole-heading-line~. This affects the ~overline~ and +~background~ properties. Depending on the version of Org, there may be +others, such as ~org-fontify-done-headline~. + +[[#h:075eb022-37a6-41a4-a040-cc189f6bfa1f][Option for scaled headings]]. + +[[#h:97caca76-fa13-456c-aef1-a2aa165ea274][Option for variable-pitch font in headings]]. + +** Option for scaled headings +:properties: +:alt_title: Scaled headings +:description: Toggle scaling of headings +:custom_id: h:075eb022-37a6-41a4-a040-cc189f6bfa1f +:end: +#+vindex: modus-themes-scale-headings + +Symbol: ~modus-themes-scale-headings~ + +Possible values: + +1. ~nil~ (default) +2. ~t~ + +The default is to use the same size for headings and paragraph text. + +With a non-nil value (~t~) make headings larger in height relative to the +main text. This is noticeable in modes like Org, Markdown, and Info. + +*** Control the scale of headings +:properties: +:alt_title: Scaled heading sizes +:description: Specify rate of increase for scaled headings +:custom_id: h:6868baa1-beba-45ed-baa5-5fd68322ccb3 +:end: + +In addition to the toggle for enabling scaled headings, users can also +specify a number of their own. + ++ If it is a floating point, say, =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 ~text-scale-adjust~ command. + ++ 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 =18pt= must be + expressed as =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 ~text-scale-adjust~ command ([[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][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. + +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 =1.2=, =1.4=, =1.6=, =1.8=, =2.0=---or use a +resource for finding a consistent scale: + +#+begin_src emacs-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-title 1.3) +#+end_src + +As for the application of that scale, the variables that range from +~modus-themes-scale-1~ up to ~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 ~modus-themes-scale-title~ 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 or at least have +some unique purpose in the buffer. Put concretely, Org's =#+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 ~modus-themes-scale-title~ ([[#h:68f481bc-5904-4725-a3e6-d7ecfa7c3dbc][Option for Org agenda constructs]]). + +Users who wish to maintain scaled headings for the normal syntax while +preventing special headings from standing out, can assign a value of =1.0= +to ~modus-themes-scale-title~ 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: +<https://protesilaos.com/codelog/2020-09-24-org-headings-adapt/>. + +** Option for variable-pitch font in UI elements +:properties: +:alt_title: UI typeface +:description: Toggle the use of variable-pitch across the User Interface +:custom_id: h:16cf666c-5e65-424c-a855-7ea8a4a1fcac +:end: +#+vindex: modus-themes-variable-pitch-ui + +Symbol: ~modus-themes-variable-pitch-ui~ + +Possible values: + +1. ~nil~ (default) +2. ~t~ + +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 (~t~) apply a proportionately spaced typeface. This +is done by assigning the ~variable-pitch~ face to the relevant items. + +[[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. + +** Option for variable-pitch font in headings +:properties: +:alt_title: Headings' typeface +:description: Toggle the use of variable-pitch in headings +:custom_id: h:97caca76-fa13-456c-aef1-a2aa165ea274 +:end: +#+vindex: modus-themes-variable-pitch-headings + +Symbol: ~modus-themes-variable-pitch-headings~ + +Possible values: + +1. ~nil~ (default) +2. ~t~ + +The default is to use the main font family, which typically is +monospaced. + +With a non-nil value (~t~) apply a proportionately spaced typeface, else +"variable-pitch", to headings (such as in Org mode). + +[[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. + +* Advanced customization (do-it-yourself) +:properties: +:custom_id: h:f4651d55-8c07-46aa-b52b-bed1e53463bb +:end: + +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 ([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][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". + +** Per-theme customization settings (DIY) +:properties: +:custom_id: h:a897b302-8e10-4a26-beab-3caaee1e1193 +:end: + +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). + +#+begin_src emacs-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_src + +Then assign ~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 +~modus-themes-toggle~ and relevant functions. + +** Case-by-case face specs using the themes' palette (DIY) +:properties: +:custom_id: h:1487c631-f4fe-490d-8d58-d72ffa3bd474 +:end: +#+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: [[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][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 ~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 ~modus-themes-color~ function. It accepts a symbol that is +associated with a color in ~modus-themes-operandi-colors~ and +~modus-themes-vivendi-colors~. Like this: + +#+begin_src emacs-lisp +(modus-themes-color 'blue) +#+end_src + +The function always extracts the color value of the active Modus theme. + +#+begin_src emacs-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_src + +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 +~cursor~ face's background property. We employ the built-in function of +~set-face-attribute~: + +#+begin_src emacs-lisp +(set-face-attribute 'cursor nil :background (modus-themes-color 'blue)) +#+end_src + +If you evaluate this form, your cursor will become blue. But if you +change themes, such as with ~modus-themes-toggle~, your edits will be +lost, because the newly loaded theme will override the ~: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 ~modus-themes-after-load-theme-hook~, which gets +called from ~modus-themes-load-operandi~, ~modus-themes-load-vivendi~, as +well as the command ~modus-themes-toggle~. Here is a sample function that +tweaks two faces and then gets added to the hook: + +#+begin_src emacs-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_src + +[[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][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 ~bold~ face. For example: + +#+begin_src emacs-lisp +(set-face-attribute 'bold nil :weight 'semibold) +#+end_src + +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 +~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 ~modus-themes-operandi-colors~ and +~modus-themes-vivendi-colors~, only here you pass the two keys you want, +first for ~modus-operandi~ then ~modus-vivendi~. + +Take the previous example with the ~cursor~ face: + +#+begin_src emacs-lisp +;; Blue for `modus-operandi' and red for `modus-vivendi' +(set-face-attribute 'cursor nil :background (modus-themes-color-alts 'blue 'red)) +#+end_src + +** Face specs at scale using the themes' palette (DIY) +:properties: +:custom_id: h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae +:end: +#+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 +([[#h:1487c631-f4fe-490d-8d58-d72ffa3bd474][Case-by-case face specs using the themes' palette]]). + +The ~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 ~modus-themes-operandi-colors~ and +~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 ~modus-operandi~ is enabled: + +#+begin_src emacs-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_src + +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 +~custom-set-faces~ function, which sets face specifications for the +special ~user~ theme. That "theme" gets applied on top of regular themes +like ~modus-operandi~ and ~modus-vivendi~. + +This is how it works: + +#+begin_src emacs-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_src + +The above snippet will immediately refashion the faces it names once it +is evaluated. However, if you switch between the Modus themes, say, +from ~modus-operandi~ to ~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 ~modus-themes-after-load-theme-hook~, which gets +called from ~modus-themes-load-operandi~, ~modus-themes-load-vivendi~, as +well as the command ~modus-themes-toggle~. With this knowledge, you can +wrap the macro in a function and then assign that function to the hook. +Thus: + +#+begin_src emacs-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_src + +[[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][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 ~: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 ~modus-themes-color-alts~ that was discussed in +the previous section. Adapt the above example like this: + +#+begin_src emacs-lisp +... +(modus-themes-with-colors + (custom-set-faces + `(cursor ((,class :background ,(modus-themes-color-alts 'blue 'green)))) + ...)) +#+end_src + +** Remap face with local value (DIY) +:properties: +:custom_id: h:7a93cb6f-4eca-4d56-a85c-9dcd813d6b0f +:end: +#+cindex: Remapping faces + +There are cases where we need to change the buffer-local attributes of a +face. This might be because we have our own minor mode that re-uses a +face for a particular purpose, such as a line selection tool that +activates ~hl-line-mode~, but we wish to keep it distinct from other +buffers. This is where ~face-remap-add-relative~ can be applied and may +be combined with ~modus-themes-with-colors~ to deliver consistent results. + +[[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]. + +In this example we will write a simple interactive function that adjusts +the background color of the ~region~ face. This is the sample code: + +#+begin_src emacs-lisp +(defvar my-rainbow-region-colors + (modus-themes-with-colors + `((red . ,red-subtle-bg) + (green . ,green-subtle-bg) + (yellow . ,yellow-subtle-bg) + (blue . ,blue-subtle-bg) + (magenta . ,magenta-subtle-bg) + (cyan . ,cyan-subtle-bg))) + "Sample list of color values for `my-rainbow-region'.") + +(defun my-rainbow-region (color) + "Remap buffer-local attribute of `region' using COLOR." + (interactive + (list + (completing-read "Pick a color: " my-rainbow-region-colors))) + (face-remap-add-relative + 'region + `( :background ,(alist-get (intern color) my-rainbow-region-colors) + :foreground ,(face-attribute 'default :foreground)))) +#+end_src + +When ~my-rainbow-region~ is called interactively, it prompts for a color +to use. The list of candidates is drawn from the car of each +association in ~my-rainbow-region-colors~ (so "red", "green", etc.). + +To extend this principle, we may write wrapper functions that pass a +color directly. Those can be useful in tandem with hooks. Consider +this example: + +#+begin_src emacs-lisp +(defun my-rainbow-region-magenta () + (my-rainbow-region 'magenta)) + +(add-hook 'diff-mode-hook #'my-rainbow-region-magenta) +#+end_src + +Whenever we enter a ~diff-mode~ buffer, we now get a magenta-colored +region. + +Perhaps you may wish to generalise those findings in to a set of +functions that also accept an arbitrary face. We shall leave the +experimentation up to you. + +** Cycle through arbitrary colors (DIY) +:properties: +:custom_id: h:77dc4a30-b96a-4849-85a8-fee3c2995305 +:end: +#+cindex: Cycle colors + +Users may opt to customize individual faces of the themes to accommodate +their particular needs. One such case is with the color intensity of +comments, specifically the foreground of ~font-lock-comment-face~. The +Modus themes set that to a readable value, in accordance with their +accessibility objective, though users may prefer to lower the overall +contrast on an on-demand basis. + +One way to achieve this is to design a command that cycles through three +distinct levels of intensity, though the following can be adapted to any +kind of cyclic behaviour, such as to switch between red, green, and +blue. + +In the following example, we employ the ~modus-themes-color~ function +which reads a symbol that represents an entry in the active theme's +color palette ([[#h:1487c631-f4fe-490d-8d58-d72ffa3bd474][Case-by-case face specs using the themes' palette]]). +Those are stored in ~my-modus-themes-comment-colors~. + +#+begin_src emacs-lisp +(defvar my-modus-themes-comment-colors + ;; We are abusing the palette here, as those colors have their own + ;; purpose in the palette, so please ignore the semantics of their + ;; names. + '((low . bg-region) + (medium . bg-tab-inactive-alt) + (high . fg-alt)) + "Alist of levels of intensity mapped to color palette entries. +The entries are found in `modus-themes-operandi-colors' or +`modus-themes-vivendi-colors'.") + +(defvar my-modus-themes--adjust-comment-color-state nil + "The cyclic state of `my-modus-themes-adjust-comment-color'. +For internal use.") + +(defun my-modus-themes--comment-foreground (degree state) + "Set `font-lock-comment-face' foreground. +Use `my-modus-themes-comment-colors' to extract the color value +for each level of intensity. + +This is complementary to `my-modus-themes-adjust-comment-color'." + (let ((palette-colors my-modus-themes-comment-colors)) + (set-face-foreground + 'font-lock-comment-face + (modus-themes-color (alist-get degree palette-colors))) + (setq my-modus-themes--adjust-comment-color-state state) + (message "Comments are set to %s contrast" degree))) + +(defun my-modus-themes-adjust-comment-color () + "Cycle through levels of intensity for comments. +The levels are determined by `my-modus-themes-comment-colors'." + (interactive) + (pcase my-modus-themes--adjust-comment-color-state + ('nil + (my-modus-themes--comment-foreground 'low 1)) + (1 + (my-modus-themes--comment-foreground 'medium 2)) + (_ + (my-modus-themes--comment-foreground 'high nil)))) +#+end_src + +With the above, {{{kbd(M-x my-modus-themes-adjust-comment-color)}}} will cycle +through the three levels of intensity that have been specified. + +Another approach is to not read from the active theme's color palette +and instead provide explicit color values, either in hexadecimal RGB +notation (like =#123456=) or as the names that are displayed in the output +of {{{kbd(M-x list-colors-display)}}}. In this case, the alist with the +colors will have to account for the active theme, so as to set the +appropriate colors. While this introduces a bit more complexity, it +ultimately offers greater flexibility on the choice of colors for such a +niche functionality (so there is no need to abuse the palette of the +active Modus theme): + +#+begin_src emacs-lisp +(defvar my-modus-themes-comment-colors + '((light . ((low . "gray75") + (medium . "gray50") + (high . "#505050"))) ; the default for `modus-operandi' + + (dark . ((low . "gray25") + (medium . "gray50") + (high . "#a8a8a8")))) ; the default for `modus-vivendi' + "Alist of levels of intensity mapped to color values. +For such colors, consult the command `list-colors-display'. Pass +the name of a color or its hex value.") + +(defvar my-modus-themes--adjust-comment-color-state nil + "The cyclic state of `my-modus-themes-adjust-comment-color'. +For internal use.") + +(defun my-modus-themes--comment-foreground (degree state) + "Set `font-lock-comment-face' foreground. +Use `my-modus-themes-comment-colors' to extract the color value +for each level of intensity. + +This is complementary to `my-modus-themes-adjust-comment-color'." + (let* ((colors my-modus-themes-comment-colors) + (levels (pcase (car custom-enabled-themes) + ('modus-operandi (alist-get 'light colors)) + ('modus-vivendi (alist-get 'dark colors))))) + (set-face-foreground + 'font-lock-comment-face + (alist-get degree levels)) + (setq my-modus-themes--adjust-comment-color-state state) + (message "Comments are set to %s contrast" degree))) + +(defun my-modus-themes-adjust-comment-color () + "Cycle through levels of intensity for comments. +The levels are determined by `my-modus-themes-comment-colors'." + (interactive) + (pcase my-modus-themes--adjust-comment-color-state + ('nil + (my-modus-themes--comment-foreground 'low 1)) + (1 + (my-modus-themes--comment-foreground 'medium 2)) + (_ + (my-modus-themes--comment-foreground 'high nil)))) +#+end_src + +The effect of the above configurations on ~font-lock-comment-face~ is +global. To make it buffer-local, one must tweak the code to employ the +function ~face-remap-add-relative~ ([[#h:7a93cb6f-4eca-4d56-a85c-9dcd813d6b0f][Remap face with local value]]). + +So this form in ~my-modus-themes--comment-foreground~: + +#+begin_src emacs-lisp +;; example 1 +(... + (set-face-foreground + 'font-lock-comment-face + (modus-themes-color (alist-get degree palette-colors))) + ...) + +;; example 2 +(... + (set-face-foreground + 'font-lock-comment-face + (alist-get degree levels)) + ...) +#+end_src + +Must become this: + +#+begin_src emacs-lisp +;; example 1 +(... + (face-remap-add-relative + 'font-lock-comment-face + `(:foreground ,(modus-themes-color (alist-get degree palette-colors)))) + ...) + +;; example 2 +(... + (face-remap-add-relative + 'font-lock-comment-face + `(:foreground ,(alist-get degree levels))) + ...) +#+end_src + +** Override colors (DIY) +:properties: +:custom_id: h:307d95dd-8dbd-4ece-a543-10ae86f155a6 +:end: +#+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 ~modus-themes-operandi-color-overrides~ and +~modus-themes-vivendi-color-overrides~, which are alists that should +mirror a subset of the associations in ~modus-themes-operandi-colors~ and +~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): + +#+begin_src emacs-lisp +(defconst modus-themes-operandi-colors + '((bg-main . "#ffffff") + (bg-dim . "#f8f8f8") + (bg-alt . "#f0f0f0") + (bg-active . "#d7d7d7") + (bg-inactive . "#efefef"))) +#+end_src + +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: + +#+begin_src emacs-lisp +(setq modus-themes-operandi-color-overrides + '((bg-main . "#fefcf4") + (bg-dim . "#faf6ef") + (bg-alt . "#f7efe5") + (bg-active . "#e8dfd1") + (bg-inactive . "#f6ece5"))) +#+end_src + +Once this is evaluated, any subsequent loading of ~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: + +#+begin_src emacs-lisp +(setq modus-themes-operandi-color-overrides nil) +#+end_src + +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: + +#+begin_src emacs-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_src + +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). Alternatively, this can also +be done programmatically ([[#h:4589acdc-2505-41fc-9f5e-699cfc45ab00][Override color saturation]]). + +For manual interventions it is advised to inspect the source code of +~modus-themes-operandi-colors~ and ~modus-themes-vivendi-colors~ for the +inline commentary: it explains what the intended use of each palette +subset is. + +Furthermore, users may benefit from the ~modus-themes-contrast~ function +that we provide: [[#h:02e25930-e71a-493d-828a-8907fc80f874][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. + +** Override color saturation (DIY) +:properties: +:custom_id: h:4589acdc-2505-41fc-9f5e-699cfc45ab00 +:end: +#+cindex: Change a theme's color saturation + +In the previous section we documented how one can override color values +manually ([[#h:307d95dd-8dbd-4ece-a543-10ae86f155a6][Override colors]]). Here we use a programmatic approach which +leverages the built-in ~color-saturate-name~ function to adjust the +saturation of all color values used by the active Modus theme. Our goal +is to prepare a counterpart of the active theme's palette that holds +modified color values, adjusted for a percent change in saturation. A +positive number amplifies the effect, while a negative one will move +towards a grayscale spectrum. + +We start with a function that can be either called from Lisp or invoked +interactively. In the former scenario, we pass to it the rate of change +we want. While in the latter, a minibuffer prompt asks for a number to +apply the desired effect. In either case, we intend to assign anew the +value of ~modus-themes-operandi-color-overrides~ (light theme) and the +same for ~modus-themes-vivendi-color-overrides~ (dark theme). + +#+begin_src emacs-lisp +(defun my-modus-themes-saturate (percent) + "Saturate current Modus theme palette overrides by PERCENT." + (interactive + (list (read-number "Saturation by percent: "))) + (let* ((theme (modus-themes--current-theme)) + (palette (pcase theme + ('modus-operandi modus-themes-operandi-colors) + ('modus-vivendi modus-themes-vivendi-colors) + (_ (error "No Modus theme is active")))) + (overrides (pcase theme + ('modus-operandi 'modus-themes-operandi-color-overrides) + ('modus-vivendi 'modus-themes-vivendi-color-overrides) + (_ (error "No Modus theme is active"))))) + (let (name cons colors) + (dolist (cons palette) + (setq name (color-saturate-name (cdr cons) percent)) + (setq name (format "%s" name)) + (setq cons `(,(car cons) . ,name)) + (push cons colors)) + (set overrides colors)) + (pcase theme + ('modus-operandi (modus-themes-load-operandi)) + ('modus-vivendi (modus-themes-load-vivendi))))) + +;; sample Elisp calls (or call `my-modus-themes-saturate' interactively) +(my-modus-themes-saturate 50) +(my-modus-themes-saturate -75) +#+end_src + +Using the above has an immediate effect, as it reloads the active Modus +theme. + +The =my-modus-themes-saturate= function stores new color values in the +variables =modus-themes-operandi-color-overrides= and +=modus-themes-vivendi-color-overrides=, meaning that it undoes changes +implemented by the user on individual colors. To have both automatic +saturation adjustment across the board and retain per-case edits to the +palette, some tweaks to the above function are required. For example: + +#+begin_src emacs-lisp +(defvar my-modus-themes-vivendi-extra-color-overrides + '((fg-main . "#ead0c0") + (bg-main . "#050515")) + "My bespoke colors for `modus-vivendi'.") + +(defvar my-modus-themes-operandi-extra-color-overrides + '((fg-main . "#1a1a1a") + (bg-main . "#fefcf4")) + "My bespoke colors for `modus-operandi'.") + +(defun my-modus-themes-saturate (percent) + "Saturate current Modus theme palette overrides by PERCENT. +Preserve the color values stored in +`my-modus-themes-operandi-extra-color-overrides', +`my-modus-themes-vivendi-extra-color-overrides'." + (interactive + (list (read-number "Saturation by percent: "))) + (let* ((theme (modus-themes--current-theme)) + (palette (pcase theme + ('modus-operandi modus-themes-operandi-colors) + ('modus-vivendi modus-themes-vivendi-colors) + (_ (error "No Modus theme is active")))) + (overrides (pcase theme + ('modus-operandi 'modus-themes-operandi-color-overrides) + ('modus-vivendi 'modus-themes-vivendi-color-overrides) + (_ (error "No Modus theme is active")))) + (extra-overrides (pcase theme + ('modus-operandi my-modus-themes-operandi-extra-color-overrides) + ('modus-vivendi my-modus-themes-vivendi-extra-color-overrides) + (_ (error "No Modus theme is active"))))) + (let (name cons colors) + (dolist (cons palette) + (setq name (color-saturate-name (cdr cons) percent)) + (setq name (format "%s" name)) + (setq cons `(,(car cons) . ,name)) + (push cons colors)) + (set overrides (append extra-overrides colors))) + (pcase theme + ('modus-operandi (modus-themes-load-operandi)) + ('modus-vivendi (modus-themes-load-vivendi))))) +#+end_src + +To disable the effect, one must reset the aforementioned variables of +the themes to ~nil~. Or specify a command for it, such as by taking +inspiration from the ~modus-themes-toggle~ we already provide: + +#+begin_src emacs-lisp +(defun my-modus-themes-revert-overrides () + "Reset palette overrides and reload active Modus theme." + (interactive) + (setq modus-themes-operandi-color-overrides nil + modus-themes-vivendi-color-overrides nil) + (pcase (modus-themes--current-theme) + ('modus-operandi (modus-themes-load-operandi)) + ('modus-vivendi (modus-themes-load-vivendi)))) +#+end_src + +** Font configurations for Org and others (DIY) +:properties: +:custom_id: h:defcf4fc-8fa8-4c29-b12e-7119582cc929 +:end: +#+cindex: Font configurations + +The themes are designed to cope well with mixed font configurations. + +[[#h:115e6c23-ee35-4a16-8cef-e2fcbb08e28b][Option for no font mixing]]. + +This mostly concerns ~org-mode~ and ~markdown-mode~, though expect to find +it elsewhere like in ~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 ~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 ~variable-pitch~ (proportional spacing) and ~fixed-pitch~ (monospaced) +faces respectively. It may also be convenient to set your main typeface +by configuring the ~default~ face the same way. + +Put something like this in your initialization file (also consider +reading the doc string of ~set-face-attribute~): + +#+begin_src emacs-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_src + +The next section shows how to make those work in a more elaborate setup +that is robust to changes between the Modus themes. + +[[#h:2793a224-2109-4f61-a106-721c57c01375][Configure bold and italic faces]]. + +Note the differences in the ~:height~ property. The ~default~ face must +specify an absolute value, which is the point size × 10. So if you want +to use a font at point size =11=, you set the height to =110=.[fn:: ~:height~ +values do not need to be rounded to multiples of ten: the likes of =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 ~text-scale-adjust~ command which only operates on the +base font size (i.e. the ~default~ face's absolute height). + +[[#h:e6c5451f-6763-4be7-8fdb-b4706a422a4c][Note for EWW and Elfeed fonts (SHR fonts)]]. + +** Configure bold and italic faces (DIY) +:properties: +:custom_id: h:2793a224-2109-4f61-a106-721c57c01375 +:end: +#+cindex: Bold and italic fonts + +The Modus themes do not hardcode a ~:weight~ or ~:slant~ attribute in the +thousands of faces they cover. Instead, they configure the generic +faces called ~bold~ and ~italic~ to use the appropriate styles and then +instruct all relevant faces that require emphasis to inherit from them. + +This practically means that users can change the particularities of what +it means for a construct to be bold/italic, by tweaking the ~bold~ and +~italic~ faces. Cases where that can be useful include: + ++ The default typeface does not have a variant with slanted glyphs + (e.g. Fira Mono/Code as of this writing on 2021-07-07), so the user + wants to add another family for the italics, such as Hack. + ++ The typeface of choice provides a multitude of weights and the user + prefers the light one by default. To prevent the bold weight from + being too heavy compared to the light one, they opt to make ~bold~ use a + semibold weight. + ++ The typeface distinguishes between oblique and italic forms by + providing different font variants (the former are just slanted + versions of the upright forms, while the latter have distinguishing + features as well). In this case, the user wants to specify the font + that applies to the ~italic~ face. + +To achieve those effects, one must first be sure that the fonts they use +have support for those features. It then is a matter of following the +instructions for all face tweaks. + +[[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. + +In this example, we set the default font family to Fira Code, while we +choose to render italics in the Hack typeface (obviously you need to +pick fonts that work well together): + +#+begin_src emacs-lisp +(set-face-attribute 'default nil :family "Fira Code" :height 110) +(set-face-attribute 'italic nil :family "Hack") +#+end_src + +And here we play with different weights, using Source Code Pro: + +#+begin_src emacs-lisp +(set-face-attribute 'default nil :family "Source Code Pro" :height 110 :weight 'light) +(set-face-attribute 'bold nil :weight 'semibold) +#+end_src + +To reset the font family, one can use this: + +#+begin_src emacs-lisp +(set-face-attribute 'italic nil :family 'unspecified) +#+end_src + +To ensure that the effects persist after switching between the Modus +themes (such as with {{{kbd(M-x modus-themes-toggle)}}}), the user needs to +write their configurations to a function and hook it up to the +~modus-themes-after-load-theme-hook~. This is necessary because the +themes set the default styles of faces (otherwise changing themes would +not be possible). + +[[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][A theme-agnostic hook for theme loading]]. + +This is a minimal setup to preserve font configurations across theme +load phases. For a more permanent setup, it is better to employ the +~custom-set-faces~ function: ~set-face-attribute~ works just fine, though it +is more convenient for quick previews or for smaller scale operations +(~custom-set-faces~ follows the format used in the source code of the +themes). + +#+begin_src emacs-lisp +;; our generic function +(defun my-modes-themes-bold-italic-faces () + (set-face-attribute 'default nil :family "Source Code Pro" :height 110) + (set-face-attribute 'bold nil :weight 'semibold)) + +;; or use this if you configure a lot of face and attributes and +;; especially if you plan to use `modus-themes-with-colors', as shown +;; elsewhere in the manual +(defun my-modes-themes-bold-italic-faces () + (custom-set-faces + '(default ((t :family "Source Code Pro" :height 110))) + '(bold ((t :weight semibold))))) + +;; and here is the hook +(add-hook 'modus-themes-after-load-theme-hook #'my-modes-themes-bold-italic-faces) +#+end_src + +** Custom Org user faces (DIY) +:properties: +:custom_id: h:89f0678d-c5c3-4a57-a526-668b2bb2d7ad +:end: +#+cindex: Org extra faces + +Users of ~org-mode~ have the option to configure various keywords and +priority cookies to better match their workflow. User options are +~org-todo-keyword-faces~ and ~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 ~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: + +#+begin_src emacs-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_src + +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 ~org-todo~ face (in case there is a difference between the +two): + +#+begin_src emacs-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_src + +This will refashion the keywords you specify, while letting the other +items in ~org-todo-keywords~ use their original styles (which are defined +in the ~org-todo~ and ~org-done~ faces). + +If you want back the defaults, try specifying just the ~org-todo~ face: + +#+begin_src emacs-lisp +(setq org-todo-keyword-faces + '(("MEET" . org-todo) + ("STUDY" . org-todo) + ("WRITE" . org-todo))) +#+end_src + +When you inherit from multiple faces, you need to quote the list as +shown further above. The order is significant: the first entry is +applied on top of the second, overriding any properties that are +explicitly set for both of them: any property that is not specified is +not overridden, so, for example, if ~org-todo~ has a background and a +foreground, while ~font-lock-type-face~ only has a foreground, the merged +face will include the background of the former and the foreground of the +latter. If you do not want to blend multiple faces, you do not need a +quoted list. A pattern of =keyword . face= will suffice. + +Both approaches can be used simultaneously, as illustrated in this +configuration of the priority cookies: + +#+begin_src emacs-lisp +(setq org-priority-faces + '((?A . '(org-scheduled-today org-priority)) + (?B . org-priority) + (?C . '(shadow org-priority)))) +#+end_src + +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. + +[[#h:1487c631-f4fe-490d-8d58-d72ffa3bd474][Custom face specs using the themes' palette]]. + +[[#h:02e25930-e71a-493d-828a-8907fc80f874][Check color combinations]]. + +** Update Org block delimiter fontification (DIY) +:properties: +:custom_id: h:f44cc6e3-b0f1-4a5e-8a90-9e48fa557b50 +:end: + +As noted in the section about ~modus-themes-org-blocks~, Org contains a +variable that determines whether the block's begin and end lines are +extended to the edge of the window ([[#h:b7e328c0-3034-4db7-9cdf-d5ba12081ca2][Option for org-mode block styles]]). +The variable is ~org-fontify-whole-block-delimiter-line~. + +Users who change the style of Org blocks from time to time may prefer to +automatically update delimiter line fontification, such as with the +following setup: + +#+begin_src emacs-lisp +(defun my-modus-themes-org-fontify-block-delimiter-lines () + "Match `org-fontify-whole-block-delimiter-line' to theme style. +Run this function at the post theme load phase, such as with the +`modus-themes-after-load-theme-hook'." + (if (eq modus-themes-org-blocks 'gray-background) + (setq org-fontify-whole-block-delimiter-line t) + (setq org-fontify-whole-block-delimiter-line nil))) + +(add-hook 'modus-themes-after-load-theme-hook + #'my-modus-themes-org-fontify-block-delimiter-lines) +#+end_src + +Then {{{kbd(M-x org-mode-restart)}}} for changes to take effect, though manual +intervention can be circumvented by tweaking the function thus: + +#+begin_src emacs-lisp +(defun my-modus-themes-org-fontify-block-delimiter-lines () + "Match `org-fontify-whole-block-delimiter-line' to theme style. +Run this function at the post theme load phase, such as with the +`modus-themes-after-load-theme-hook'." + (if (eq modus-themes-org-blocks 'gray-background) + (setq org-fontify-whole-block-delimiter-line t) + (setq org-fontify-whole-block-delimiter-line nil)) + (when (derived-mode-p 'org-mode) + (font-lock-flush))) +#+end_src + +** Measure color contrast (DIY) +:properties: +:custom_id: h:02e25930-e71a-493d-828a-8907fc80f874 +:end: +#+findex: modus-themes-contrast +#+findex: modus-themes-wcag-formula +#+cindex: Color contrast + +The themes provide the functions ~modus-themes-wcag-formula~ and +~modus-themes-contrast~. The former is a direct implementation of the +WCAG formula: <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 ~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): + +#+begin_src emacs-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_src + +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: + +#+begin_src emacs-lisp +(format "%0.2f" (modus-themes-contrast "#000000" "#00ff00")) +#+end_src + +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 ~org-mode~ or ~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: + +#+begin_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: [[#h:307d95dd-8dbd-4ece-a543-10ae86f155a6][Override colors]]. + +** Load theme depending on time of day (DIY) +:properties: +:custom_id: h:1d1ef4b4-8600-4a09-993c-6de3af0ddd26 +:end: + +While we do provide ~modus-themes-toggle~ to manually switch between the +themes, users may also set up their system to perform such a task +automatically at sunrise and sunset. + +This can be accomplished by specifying the coordinates of one's location +using the built-in {{{file(solar.el)}}} and then configuring the =circadian= +package: + +#+begin_src emacs-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_src + +** Backdrop for pdf-tools (DIY) +:properties: +:custom_id: h:ff69dfe1-29c0-447a-915c-b5ff7c5509cd +:end: +#+cindex: Remapping pdf-tools backdrop + +Most PDF files use a white background for their page, making it +impossible to discern the file's boundaries in the buffer while using +the Modus Operandi theme. To introduce a distinction between the +buffer's backdrop and the PDF page's background, the former must be +rendered as some shade of gray. Ideally, ~pdf-tools~ would provide a face +that the themes could support directly, though this does not seem to be +the case for the time being. We must thus employ the face remapping +technique that is documented elsewhere in this document to change the +buffer-local value of the ~default~ face. + +[[#h:7a93cb6f-4eca-4d56-a85c-9dcd813d6b0f][Remap face with local value]]. + +To remap the buffer's backdrop, we start with a function like this one: + +#+begin_src emacs-lisp +(defun my-pdf-tools-backdrop () + (face-remap-add-relative + 'default + `(:background ,(modus-themes-color 'bg-alt)))) + +(add-hook 'pdf-tools-enabled-hook #'my-pdf-tools-backdrop) +#+end_src + +The idea is to assign that function to a hook that gets called when +~pdf-tools~ renders the document: ~pdf-tools-enabled-hook~. This is enough +when you only use one theme. However it has the downside of setting the +background color value only at render time. In other words, the face +remapping function does not get evaluated anew whenever the theme +changes, such as upon invoking {{{kbd(M-x modus-themes-toggle)}}}. + +To have our face remapping adapt gracefully while switching between the +Modus themes, we need to also account for the current theme and control +the activation of ~pdf-view-midnight-minor-mode~. To which end we arrive +at something like the following, which builds on the above example: + +#+begin_src emacs-lisp +(defun my-pdf-tools-backdrop () + (face-remap-add-relative + 'default + `(:background ,(modus-themes-color 'bg-alt)))) + +(defun my-pdf-tools-midnight-mode-toggle () + (when (derived-mode-p 'pdf-view-mode) + (if (eq (car custom-enabled-themes) 'modus-vivendi) + (pdf-view-midnight-minor-mode 1) + (pdf-view-midnight-minor-mode -1)) + (my-pdf-tools-backdrop))) + +(add-hook 'pdf-tools-enabled-hook #'my-pdf-tools-midnight-mode-toggle) +(add-hook 'modus-themes-after-load-theme-hook #'my-pdf-tools-midnight-mode-toggle) +#+end_src + +With those in place, PDFs have a distinct backdrop for their page, while +they automatically switch to their dark mode when ~modus-themes-toggle~ is +called from inside a buffer whose major-mode is ~pdf-view-mode~. + +** A theme-agnostic hook for theme loading (DIY) +:properties: +:custom_id: h:86f6906b-f090-46cc-9816-1fe8aeb38776 +:end: + +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 ~modus-themes-after-load-theme-hook~, +which runs after ~modus-themes-toggle~, ~modus-themes-load-operandi~, or +~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: + +#+begin_src emacs-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_src + +This creates the ~after-enable-theme-hook~ and makes it run after each +call to ~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 +~modus-themes-toggle~ and the others mentioned above. ~enable-theme~ is +called internally by ~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). + +* Face coverage +:properties: +:custom_id: h:a9c8f29d-7f72-4b54-b74b-ddefe15d6a19 +:end: + +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. + +** Full support for packages or face groups +:properties: +:alt_title: Supported packages +:description: Full list of covered face groups +:custom_id: h:60ed4275-60d6-49f8-9287-9a64e54bea0e +:end: +#+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 =*= tend to +have lots of extensions, so the "full support" may not be 100% true… + ++ ace-window ++ ag ++ alert ++ all-the-icons ++ annotate ++ anzu ++ apropos ++ apt-sources-list ++ artbollocks-mode ++ auctex and TeX ++ auto-dim-other-buffers ++ avy ++ awesome-tray ++ bbdb ++ binder ++ bm ++ bongo ++ boon ++ bookmark ++ breakpoint (provided by the built-in {{{file(gdb-mi.el)}}} library) ++ buffer-expose ++ calendar and diary ++ calfw ++ centaur-tabs ++ cfrs ++ change-log and log-view (such as ~vc-print-log~, ~vc-print-root-log~) ++ cider ++ circe ++ color-rg ++ column-enforce-mode ++ company-mode* ++ company-posframe ++ compilation-mode ++ completions ++ consult ++ corfu ++ counsel* ++ counsel-css ++ counsel-org-capture-string ++ cov ++ cperl-mode ++ css-mode ++ csv-mode ++ ctrlf ++ custom (what you get with {{{kbd(M-x customize)}}}) ++ dap-mode ++ dashboard (emacs-dashboard) ++ deadgrep ++ debbugs ++ define-word ++ deft ++ dictionary ++ diff-hl ++ diff-mode ++ dim-autoload ++ dir-treeview ++ dired ++ dired-async ++ dired-git ++ dired-git-info ++ dired-narrow ++ dired-subtree ++ diredc ++ diredfl ++ diredp (dired+) ++ disk-usage ++ display-fill-column-indicator-mode ++ doom-modeline ++ dynamic-ruler ++ easy-jekyll ++ easy-kill ++ ebdb ++ ediff ++ eglot ++ el-search ++ eldoc-box ++ elfeed ++ elfeed-score ++ embark ++ emms ++ enh-ruby-mode (enhanced-ruby-mode) ++ epa ++ equake ++ erc ++ eros ++ ert ++ eshell ++ eshell-fringe-status ++ eshell-git-prompt ++ eshell-prompt-extras (epe) ++ eshell-syntax-highlighting ++ evil* (evil-mode) ++ evil-goggles ++ evil-snipe ++ evil-visual-mark-mode ++ eww ++ exwm ++ eyebrowse ++ fancy-dabbrev ++ flycheck ++ flycheck-color-mode-line ++ flycheck-indicator ++ flycheck-posframe ++ flymake ++ flyspell ++ flyspell-correct ++ flx ++ freeze-it ++ frog-menu ++ focus ++ fold-this ++ font-lock (generic syntax highlighting) ++ forge ++ fountain (fountain-mode) ++ geiser ++ git-commit ++ git-gutter (and variants) ++ git-lens ++ git-rebase ++ git-timemachine ++ git-walktree ++ gnus ++ gotest ++ golden-ratio-scroll-screen ++ helm* ++ helm-ls-git ++ helm-switch-shell ++ helm-xref ++ helpful ++ highlight-blocks ++ highlight-defined ++ highlight-escape-sequences (~hes-mode~) ++ highlight-indentation ++ highlight-numbers ++ highlight-symbol ++ highlight-tail ++ highlight-thing ++ hl-defined ++ hl-fill-column ++ hl-line-mode ++ hl-todo ++ hydra ++ hyperlist ++ ibuffer ++ icomplete ++ icomplete-vertical ++ ido-mode ++ iedit ++ iflipb ++ imenu-list ++ indium ++ info ++ info-colors ++ interaction-log ++ ioccur ++ isearch, occur, etc. ++ isl (isearch-light) ++ ivy* ++ ivy-posframe ++ jira (org-jira) ++ journalctl-mode ++ js2-mode ++ julia ++ jupyter ++ kaocha-runner ++ keycast ++ ledger-mode ++ line numbers (~display-line-numbers-mode~ and global variant) ++ lsp-mode ++ lsp-ui ++ macrostep ++ magit ++ magit-imerge ++ make-mode ++ man ++ marginalia ++ markdown-mode ++ markup-faces (~adoc-mode~) ++ mentor ++ messages ++ minibuffer-line ++ minimap ++ mmm-mode ++ mode-line ++ mood-line ++ moody ++ mpdel ++ mu4e ++ mu4e-conversation ++ multiple-cursors ++ neotree ++ no-emoji ++ notmuch ++ num3-mode ++ nxml-mode ++ objed ++ orderless ++ org* ++ org-journal ++ org-noter ++ org-pomodoro ++ org-recur ++ org-roam ++ org-superstar ++ org-table-sticky-header ++ org-tree-slide ++ org-treescope ++ origami ++ outline-mode ++ outline-minor-faces ++ package (what you get with {{{kbd(M-x list-packages)}}}) ++ page-break-lines ++ pandoc-mode ++ paradox ++ paren-face ++ parrot ++ pass ++ pdf-tools ++ persp-mode ++ perspective ++ phi-grep ++ phi-search ++ pkgbuild-mode ++ pomidor ++ popup ++ powerline ++ powerline-evil ++ prism ([[#h:a94272e0-99da-4149-9e80-11a7e67a2cf2][Note for prism.el]]) ++ proced ++ prodigy ++ pulse ++ quick-peek ++ racket-mode ++ rainbow-blocks ++ rainbow-identifiers ++ rainbow-delimiters ++ rcirc ++ recursion-indicator ++ regexp-builder (also known as ~re-builder~) ++ rg (rg.el) ++ ripgrep ++ rmail ++ ruler-mode ++ sallet ++ selectrum ++ selectrum-prescient ++ semantic ++ sesman ++ shell-script-mode ++ shortdoc ++ show-paren-mode ++ shr ++ side-notes ++ sieve-mode ++ skewer-mode ++ smart-mode-line ++ smartparens ++ smerge ++ solaire ++ spaceline ++ speedbar ++ spell-fu ++ spray ++ stripes ++ suggest ++ switch-window ++ swiper ++ swoop ++ sx ++ symbol-overlay ++ syslog-mode ++ tab-bar-groups ++ tab-bar-mode ++ tab-line-mode ++ table (built-in table.el) ++ telega ++ telephone-line ++ terraform-mode ++ term ++ tomatinho ++ transient (pop-up windows such as Magit's) ++ trashed ++ treemacs ++ tty-menu ++ tuareg ++ typescript ++ undo-tree ++ vc (vc-dir.el, vc-hooks.el) ++ vc-annotate (the output of {{{kbd(C-x v g)}}}) ++ vdiff ++ vertico ++ vimish-fold ++ visible-mark ++ visual-regexp ++ volatile-highlights ++ vterm ++ wcheck-mode ++ web-mode ++ wgrep ++ which-function-mode ++ which-key ++ whitespace-mode ++ window-divider-mode ++ winum ++ writegood-mode ++ woman ++ xah-elisp-mode ++ xref ++ xterm-color (and ansi-colors) ++ yaml-mode ++ yasnippet ++ ztree + +Plus many other miscellaneous faces that are provided by the upstream +GNU Emacs distribution. + +** Indirectly covered packages +:properties: +:custom_id: h:2cb359c7-3a84-4262-bab3-dcdc1d0034d7 +:end: +#+cindex: Implicitly supported packages + +These do not require any extra styles because they are configured to +inherit from some basic faces or their dependencies which are directly +supported by the themes. + ++ counsel-notmuch ++ edit-indirect ++ evil-owl ++ fortran-mode ++ goggles ++ i3wm-config-mode ++ perl-mode ++ php-mode ++ rjsx-mode ++ swift-mode ++ tab-bar-echo-area + +* Notes on individual packages +:properties: +:custom_id: h:4c4d901a-84d7-4f20-bd99-0808c2b06eba +:end: + +This section covers information that may be of interest to users of +individual packages. + +** Note on avy hints +:properties: +:custom_id: h:2fdce705-6de7-44e6-ab7f-18f59af99e01 +:end: + +Hints can appear everywhere, in wildly varying contexts, hence, their +appearance, by necessity, is a compromise. However, there are various +options for making them stand out. First is dimming the surroundings: + +#+begin_src emacs-lisp +(setq avy-background t) +#+end_src + +Dimming works well when you find it difficult to spot hints, any hint. +Second is limiting the number of faces used by hints: + +#+begin_src emacs-lisp +(setq avy-lead-faces + '(avy-lead-face + avy-lead-face-1 + avy-lead-face-1 + avy-lead-face-1 + avy-lead-face-1)) +#+end_src + +Limiting the number of faces works well with longer hints when you find +it difficult to identify individual hints, especially with hints +touching each other. The first character of the hint will have an +intense color, the remaining ones the same neutral color. + +Third is preferring commands that produce fewer candidates. Fewer hints +is less noise: ~avy-goto-char-timer~ is an excellent alternative to +~avy-goto-char~. + +** Note on calendar.el weekday and weekend colors +:properties: +:custom_id: h:b2db46fb-32f4-44fd-8e11-d2b261cf51ae +:end: + +By default, the {{{kbd(M-x calendar)}}} interface differentiates weekdays from +weekends by applying a gray color to the former and a faint red to the +latter. The idea for this approach is that the weekend should serve as +a subtle warning that no work is supposed to be done on that day, per +the design of traditional calendars. + +Users who prefer all days to look the same can configure the variable +~calendar-weekend-days~ to either use gray of weekdays or the faint red of +weekends uniformly. + +#+begin_src emacs-lisp +;; All are treated like weekdays (gray color) +(setq calendar-weekend-days nil) + +;; All are treated like weekends (red-faint color) +(setq calendar-weekend-days (number-sequence 0 6)) + +;; The default marks the Saturday and Sunday as the weekend +(setq calendar-weekend-days '(0 6)) +#+end_src + +For changes to take effect, the Calendar buffer needs to be generated +anew. + +** Note on underlines in compilation buffers +:properties: +:custom_id: h:420f5a33-c7a9-4112-9b04-eaf2cbad96bd +:end: + +Various buffers that produce compilation results or run tests on code +apply an underline to the file names they reference or to relevant +messages. Users may consider this unnecessary or excessive. + +To outright disable the effect, use this: + +#+begin_src emacs-lisp +(setq compilation-message-face nil) +#+end_src + +If some element of differentiation is still desired, a good option is to +render the affected text using the ~italic~ face: + +#+begin_src emacs-lisp +(setq compilation-message-face 'italic) +#+end_src + +[[#h:2793a224-2109-4f61-a106-721c57c01375][Configure bold and italic faces]]. + +** Note on inline Latex in Org buffers +:properties: +:custom_id: h:dd8478da-f56a-45cd-b199-b836c85c3c5a +:end: + +Org can work with inline latex and related syntax. To actually fontify +those constructs, set the variable ~org-highlight-latex-and-related~ to +the desired list of values (per its doc string). For example: + +#+begin_src emacs-lisp +(setq org-highlight-latex-and-related '(latex script)) +#+end_src + +Remember to use {{{kbd(M-x org-mode-restart)}}} for changes to take effect. + +** Note on dimmer.el +:properties: +:custom_id: h:8eb4b758-d318-4480-9ead-357a571beb93 +:end: + +The {{{file(dimmer.el)}}} library by Neil Okamoto can be configured to +automatically dim the colors of inactive Emacs windows. To guarantee +consistent results with the Modus themes, we suggest some tweaks to the +default styles, such as in this minimal setup: + +#+begin_src emacs-lisp +(use-package dimmer + :config + (setq dimmer-fraction 0.3) + (setq dimmer-adjustment-mode :foreground) + (setq dimmer-use-colorspace :rgb) + + (dimmer-mode 1)) +#+end_src + +Of the above, we strongly recommend the RGB color space because it is +the one that remains faithful to the hueness of the colors used by the +themes. Whereas the default CIELAB space has a tendency to distort +colors in addition to applying the dim effect, which can be somewhat +disorienting. + +The value of the ~dimmer-fraction~ has been selected empirically. Users +might prefer to tweak it further (increasing it makes the dim effect +more pronounced). + +Changing the ~dimmer-adjustment-mode~ is a matter of preference. Though +because the Modus themes use black and white as their base colors, any +other value for that variable will turn the main background gray. This +inadvertently leads to the opposite of the intended utility of this +package: it draws too much attention to unfocused windows. + +** Note on display-fill-column-indicator-mode +:properties: +:custom_id: h:2a602816-bc1b-45bf-9675-4cbbd7bf6cab +:end: + +While designing the style for ~display-fill-column-indicator-mode~, we +stayed close to the mode's defaults: to apply a subtle foreground color +to the ~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, ~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 ~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 ~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: + +#+begin_src emacs-lisp +(modus-themes-with-colors + (custom-set-faces + `(fill-column-indicator ((,class :background ,bg-inactive + :foreground ,bg-inactive))))) +#+end_src + +[[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]. + +** Note on mmm-mode.el background colors +:properties: +:custom_id: h:99cf0d6c-e478-4e26-9932-3bf3427d13f6 +:end: + +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: + +1. Legibility of the text, understood as the contrast ratio between the + background and the foreground. + +2. Semantic precision of each face which entails faithfulness to + color-coding of the underlying background. + +As the Modus themes are designed with the express purpose of conforming +with the first point, we have to forgo the apparent color-coding of the +background elements. Instead we use subtle colors that do not undermine +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. + +[[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][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. + +#+begin_src emacs-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_src + +** Note on prism.el +:properties: +:alt_title: Note for prism +:custom_id: h:a94272e0-99da-4149-9e80-11a7e67a2cf2 +:end: + +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 ~modus-themes-with-colors~ +macro: [[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]. + +These are the minimum recommended settings with 16 colors: + +#+begin_src emacs-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_src + +With 8 colors: + +#+begin_src emacs-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_src + +And this is with 4 colors, which produces results that are the closest +to the themes' default aesthetic: + +#+begin_src emacs-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_src + +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): + +#+begin_src emacs-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_src + +** Note on god-mode.el +:properties: +:alt_title: Note for god-mode +:custom_id: h:4da1d515-3e05-47ef-9e45-8251fc7e986a +:end: + +The ~god-mode~ library does not provide faces that could be configured by +the Modus themes. Users who would like to get some visual feedback on +the status of {{{kbd(M-x god-mode)}}} are instead encouraged by upstream to +set up their own configurations, such as by changing the ~mode-line~ face +([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization (do-it-yourself)]]). This is an adaptation of the +approach followed in the upstream README: + +#+begin_src emacs-lisp +(defun my-god-mode-update-mode-line () + "Make `mode-line' blue if God local mode is active." + (modus-themes-with-colors + (if god-local-mode + (set-face-attribute 'mode-line nil + :foreground blue-active + :background bg-active-accent + :box blue) + (set-face-attribute 'mode-line nil + :foreground fg-active + :background bg-active + :box fg-alt)))) + +(add-hook 'post-command-hook 'my-god-mode-update-mode-line) +#+end_src + +We employ the ~modus-themes-with-colors~ which provides access to color +variables defined by the active theme. Its use is covered elsewhere in +this manual ([[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]). As for the +attributes that can be passed to each face, start by consulting the +documentation string of ~set-face-attribute~. + +** Note on company-mode overlay pop-up +:properties: +:custom_id: h:20cef8c4-d11f-4053-8b2c-2872925780b1 +:end: + +By default, the ~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.[fn:: +https://github.com/company-mode/company-mode/issues/1010][fn:: +https://github.com/tumashu/company-posframe/] + +** Note on ERC escaped color sequences +:properties: +:custom_id: h:98bdf319-1e32-4469-8a01-771200fba65c +:end: + +The built-in IRC client ~erc~ has the ability to colorise any text using +escape sequences that start with =^C= (inserted with {{{kbd(C-q C-c)}}}) and are +followed by a number for the foreground and background.[fn:: This page +explains the basics, though it is not specific to Emacs: +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 =^C1,6=. The minimum setup is this: + +#+begin_src emacs-lisp +(add-to-list 'erc-modules 'irccontrols) +(setq erc-interpret-controls-p t + erc-interpret-mirc-color t) +#+end_src + +As this allows users the chance to make arbitrary combinations, it is +impossible to guarantee a consistently high contrast ratio. All we can +we do is provide guidance on the combinations that satisfy the +accessibility standard of the themes: + ++ Modus Operandi :: Use foreground color 1 for all backgrounds from + 2-15. Like so: {{{kbd(C-q C-c1,N)}}} where =N= is the background. + ++ Modus Vivendi :: Use foreground color 0 for all backgrounds from + 2-13. Use foreground =1= for backgrounds 14, 15. + +Colors 0 and 1 are white and black respectively. So combine them +together, if you must. + +** Note on powerline or spaceline +:properties: +:custom_id: h:9130a8ba-d8e3-41be-a58b-3cb1eb7b6d17 +:end: + +Both Powerline and Spaceline package users will likely need to use the +command ~powerline-reset~ whenever they make changes to their themes +and/or mode line setup. + +** Note on SHR colors +:properties: +:custom_id: h:4cc767dc-ffef-4c5c-9f10-82eb7b8921bf +:end: + +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)}}}. + +** Note on EWW and Elfeed fonts (SHR fonts) +:properties: +:custom_id: h:e6c5451f-6763-4be7-8fdb-b4706a422a4c +:end: + +EWW and Elfeed rely on the Simple HTML Renderer to display their +content. The {{{file(shr.el)}}} library contains the variable ~shr-use-fonts~ +that controls whether the text in the buffer is set to a ~variable-pitch~ +typeface (proportionately spaced) or if just retains whatever the +default font family is. Its default value is non-nil, which means that +~variable-pitch~ is applied. + +[[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. + +** Note on Helm grep +:properties: +:custom_id: h:d28879a2-8e4b-4525-986e-14c0f873d229 +:end: + +There is one face from the Helm package that is meant to highlight the +matches of a grep or grep-like command (=ag= or =ripgrep=). It is +~helm-grep-match~. However, this face can only apply when the user does +not pass =--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)}}}). + +#+begin_quote +Face used to highlight grep matches. Have no effect when grep backend +use "--color=" +#+end_quote + +The user must either remove =--color= from the flags passed to the grep +function, or explicitly use =--color=never= (or equivalent). Helm +provides user-facing customization options for controlling the grep +function's parameters, such as ~helm-grep-default-command~ and +~helm-grep-git-grep-command~. + +When =--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 +~ansi-color-names-vector~. + +** Note on vc-annotate-background-mode +:properties: +:custom_id: h:5095cbd1-e17a-419c-93e8-951c186362a3 +:end: + +Due to the unique way ~vc-annotate~ ({{{kbd(C-x v g)}}}) applies colors, support +for its background mode (~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 ([[#h:9c3cd842-14b7-44d7-84b2-a5c8bc3fc3b1][Contributing]]). + +** Note on pdf-tools link hints +:properties: +:custom_id: h:2659d13e-b1a5-416c-9a89-7c3ce3a76574 +:end: + +Hints are drawn by [[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 ~pdf-links-read-link~ and the faces +it inherits, it needs to be added to your initialization file after +you've customized any faces. + +#+begin_src emacs-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_src + +* Frequently Asked Questions (FAQ) +:properties: +:custom_id: h:b3384767-30d3-4484-ba7f-081729f03a47 +:end: +#+cindex: Frequently Asked Questions (FAQ) + +In this section we provide answers related to some aspects of the Modus +themes' design and application. + +** Is the contrast ratio about adjacent colors? +:properties: +:custom_id: h:5ce7ae2e-9348-4e55-b4cf-9302345b1826 +:end: +#+cindex: Contrast between adjacent colors + +The minimum contrast ratio in relative luminance that the themes conform +with always refers to any given combination of background and foreground +colors. If we have some blue colored text next to a magenta one, both +against a white background, we do not mean to imply that blue:magenta is +7:1 in terms of relative luminance. Rather, we state that blue:white +and magenta:white each are 7:1 or higher. + +The point of reference is always the background. Because colors have +about the same minimum distance in luminance from their backdrop, they +necessarily are fairly close to each other in this measure. A possible +blue:magenta combination would naturally be around 1:1 in contrast of +the sort here considered. + +To differentiate between sequential colors, we rely on hueness by +mapping contrasting hues to adjacent constructs, while avoiding +exaggerations. A blue next to a magenta can be told apart regardless of +their respective contrast ratio against their common background. +Exceptions would be tiny characters in arguably not so realistic cases, +such as two dots drawn side-by-side which for some reason would need to +be colored differently. They would still be legible though, which is +the primary objective of the Modus themes. + +** What does it mean to avoid exaggerations? +:properties: +:custom_id: h:44284e1f-fab8-4c4f-92f0-544728a7c91e +:end: +#+cindex: Avoiding exaggerations in design + +The Modus themes are designed with restraint, so that their default +looks do not overdo it with the application of color. + +[[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization Options]]. + +This is the non-quantifiable aspect of the themes' design: the artistic +part, if you will. There are a lot of cases where color can be used +inconsiderately, without accounting for layout, typographic, or other +properties of the presentation. For example, two headings with distinct +markers, such as leading asterisks in Org buffers, do not have to have +highly contrasting hues between them in order to be told apart: the +added element of contrast in hueness does not contribute significantly +more to the distinction between the headings than colors whose hues are +relatively closer to each other in the color space. + +Exaggerations can be hard to anticipate or identify. Multiple shades of +blue and magenta in the same context may not seem optimal: one might +think that it would be better to use highly contrasting hues to ensure +that all colors stand out, such as by placing blue next to yellow, next +to magenta, and green. That would, however, be a case of design for its +own sake; a case where color is being applied without consideration of +its end results in the given context. Too many contrasting hues in +close proximity force an erratic rate to how the eye jumps from one +piece of text to the next. Whereas multiple shades of, say, blue and +magenta can suffice to tell things apart and avoid excess coloration: a +harmonious rhythm. + +** Why are colors mostly variants of blue, magenta, cyan? +:properties: +:custom_id: h:0b26cb47-9733-4cb1-87d9-50850cb0386e +:end: +#+cindex: Innate color qualities of the palette + +Due to the innate properties of color, some options are better than +others for the accessibility purposes of the themes, the stylistic +consistency between ~modus-operandi~ and ~modus-vivendi~, and the avoidance +of exaggerations in design. + +[[#h:44284e1f-fab8-4c4f-92f0-544728a7c91e][What does it mean to avoid exaggerations?]] + +What we describe as color is a function of three distinct channels of +light: red, green, blue. In hexadecimal RGB notation, a color value is +read as three pairs of red, green, and blue light: =#RRGGBB=. Of those +three, the most luminant is green, while the least luminant is blue. + +The three basic colors represent each of the channels of light. They +can be intermixed to give us six colors: red and green derive yellow, +green and blue make cyan, red and blue turn into magenta. + +We can test the luminance of each of those against white and black to +get a sense of how not all colors are equally good for accessibility +(white is =#ffffff=, which means that all three light channels are fully +luminated, while black is =#000000= meaning that no light is present +(notwithstanding display technology)). + +#+begin_example +| Name | | #ffffff | #000000 | +|---------+---------+---------+---------| +| red | #ff0000 | 4.00 | 5.25 | +| yellow | #ffff00 | 1.07 | 19.56 | +| green | #00ff00 | 1.37 | 15.30 | +| cyan | #00ffff | 1.25 | 16.75 | +| blue | #0000ff | 8.59 | 2.44 | +| magenta | #ff00ff | 3.14 | 6.70 | +#+end_example + +[[#h:02e25930-e71a-493d-828a-8907fc80f874][Measure color contrast]]. + +By reading this table we learn that every color that has a high level of +green light (green, yellow, cyan) is virtually unreadable against a +white background and, conversely, can be easily read against black. + +We can then infer that red and blue, in different combinations, with +green acting as calibrator for luminance, will give us fairly moderate +colors that pass the 7:1 target. Blue with a bit of green produce +appropriate variants of cyan. Similarly, blue combined with some red +and hints of green give us suitable shades of purple. + +Due to the need of maintaining some difference in hueness between +adjacent colors, it is not possible to make red, green, and yellow the +primary colors, because blue could not be used to control their +luminance and, thus the relevant space would shrink considerably. + +[[#h:5ce7ae2e-9348-4e55-b4cf-9302345b1826][Is the contrast ratio about adjacent colors?]] + +This phenomenon is best illustrated by the following table that measures +the relative luminance of shades of red, yellow, magenta against white: + +#+begin_example +| | #ffffff | +|---------+---------| +| #990000 | 8.92 | +| #995500 | 5.75 | +| #990099 | 7.46 | +#+end_example + +We notice that equal values of red and blue light in =#990099= (magenta +shade) do not lead to a considerable change in luminance compared with +=#990000= (red variant). Whereas less amount of green light in =#995500= +leads to a major drop in luminance relative to white. It follows that +using the green channel of light to calibrate the luminance of colors is +more effective than trying to do the same with either red or blue (the +latter is the least effective in that regard). + +When we need to work with several colors, it is always better to have +sufficient manoeuvring space, especially since we cannot pick arbitrary +colors but only those that satisfy the accessibility objectives of the +themes. + +As for why we do not mostly use green, yellow, cyan for the dark theme, +it is because those colors are far more luminant than their counterparts +on the other side of the spectrum, so to ensure that they all have about +the same contrast ratios we would have to alter their hueness +considerably. In short, the effect would not be optimal as it would +lead to exaggerations. Plus, it would make ~modus-vivendi~ look +completely different than ~modus-operandi~, to the effect that the two +could not be properly considered part of the same project. + +** What is the best setup for legibility? +:properties: +:custom_id: h:f60cc2ae-129d-47c0-9849-4f6bbd87d8be +:end: +#+cindex: General setup for readability + +The Modus themes can be conceptually simplified as combinations of color +values that account for relative luminance and inner harmony. Those +qualities do not guarantee that every end-user will have the same +experience, due to differences between people, but also because of +variances in hardware capabilities and configurations. For the purposes +of this document, we may only provide suggestions pertaining to the +latter case. + +~modus-operandi~ is best used outdoors or in a room that either gets +direct sunlight or has plenty of light. Whereas ~modus-vivendi~ works +better when there is not a lot of sunshine or the room has a source of +light, preferably a faint or warm one. It is possible to use +~modus-operandi~ at night and ~modus-vivendi~ during the day, though that +will depend on several variables, such as one's overall perception of +color, the paint on the walls and how that contributes to the impression +of lightness in the room, the sense of space within the eye's peripheral +vision, hardware specifications, and environmental factors. + +In general, an additional source of light other than that of the monitor +can help reduce eye strain: the eyes are more relaxed when they do not +have to focus on one point to gather light. + +The monitor's display settings must be accounted for. Gamma values, in +particular, need to be calibrated to neither amplify nor distort the +perception of black. Same principle for sharpness, brightness, and +contrast as determined by the hardware, which all have an effect on how +text is read on the screen. + +There are software level methods on offer, such as the XrandR utility +for the X Window System (X.org), which can make gamma corrections for +each of the three channels of light (red, green, blue). For example: + +: xrandr --output LVDS1 --brightness 1.0 --gamma 0.76:0.75:0.68 + +Typography is another variable. Some font families are blurry at small +point sizes. Others may have a regular weight that is lighter (thiner) +than that of their peers which may, under certain circumstances, cause a +halo effect around each glyph. + +The gist is that legibility cannot be fully solved at the theme level. +The color combinations may have been optimized for accessibility, though +the remaining contributing factors in each case need to be considered in +full. + +* Contributing +:properties: +:custom_id: h:9c3cd842-14b7-44d7-84b2-a5c8bc3fc3b1 +:end: + +This section documents the canonical sources of the themes and the ways +in which you can contribute to their ongoing development. + +** Sources of the themes +:properties: +:custom_id: h:89504f1c-c9a1-4bd9-ab39-78fd0eddb47c +:end: +#+cindex: Sources of the themes + +The ~modus-operandi~ and ~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 [[https://gitlab.com/protesilaos/modus-themes/][available on Gitlab]], for the time +being. A [[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 +[[https://protesilaos.com/modus-themes/][author's personal website]] (does not rely on any non-free code). + +** Issues you can help with +:properties: +:custom_id: h:6536c8d5-3f98-43ab-a787-b94120e735e8 +:end: +#+cindex: Contributing + +A few tasks you can help with: + ++ Suggest refinements to packages that are covered. ++ Report packages not covered thus far. ++ Report bugs, inconsistencies, shortcomings. ++ Help expand the documentation of covered-but-not-styled packages. ++ Suggest refinements to the color palette. ++ Help expand this document or any other piece of documentation. ++ Merge requests for code refinements. + +[[#h:111773e2-f26f-4b68-8c4f-9794ca6b9633][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. + +** Patches require copyright assignment to the FSF +:properties: +:custom_id: h:111773e2-f26f-4b68-8c4f-9794ca6b9633 +:end: + +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. + +#+begin_example text +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 + +* Acknowledgements +:properties: +:custom_id: h:95c3da23-217f-404e-b5f3-56c75760ebcf +:end: +#+cindex: Contributors + +The Modus themes are a collective effort. Every bit of work matters. + ++ Author/maintainer :: Protesilaos Stavrou. + ++ Contributions to code or documentation :: Anders Johansson, Basil + L.{{{space()}}} Contovounesios, Carlo Zancanaro, Eli Zaretskii, Fritz Grabo, + Kostadin Ninev, Madhavan Krishnan, Markus Beppler, Matthew Stevenson, + Mauro Aranda, Nicolas De Jaeghere, Philip Kaludercic, Rudolf + Adamkovič, Shreyas Ragavan, Stefan Kangas, Vincent Murphy, Xinglu + Chen. + ++ 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.{{{space()}}} + Contovounesios, Burgess Chang, Christian Tietze, Christopher Dimech, + Damien Cassou, Daniel Mendler, Dario Gjorgjevski, David Edmondson, + Davor Rotim, Divan Santana, Emanuele Michele Alberto Monterosso, + Farasha Euker, Gautier Ponsinet, Gerry Agbobada, Gianluca Recchia, + Gustavo Barros, Hörmetjan Yiltiz, Ilja Kocken, Iris Garcia, Jeremy + Friesen, Jerry Zhang, John Haman, Joshua O'Connor, Kevin Fleming, + Kévin Le Gouguec, Kostadin Ninev, Len Trigg, Manuel Uberti, Mark + Burton, Markus Beppler, Mauro Aranda, Michael Goldenberg, Morgan + Smith, Murilo Pereira, Nicky van Foreest, Nicolas De Jaeghere, Paul + Poloskov, Pengji Zhang, Pete Kazmier, Peter Wu, Philip Kaludercic, + Pierre Téchoueyres, Roman Rudakov, Ryan Phillips, Rudolf Adamkovič, + Sam Kleinman, Shreyas Ragavan, Simon Pugnet, Tassilo Horn, Thibaut + Verron, Thomas Heartman, 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, Trey, bepolymathe, doolio, fleimgruber, iSeeU, + jixiuf, okamsn, pRot0ta1p. + ++ Packaging :: Basil L.{{{space()}}} 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). + ++ Inspiration for certain features :: Bozhidar Batsov (zenburn-theme), + Fabrice Niessen (leuven-theme). + +Special thanks, in no particular order, to Manuel Uberti, Gustavo +Barros, and Omar Antolín Camarena for their long time contributions and +insightful commentary. + +* Meta +:properties: +:custom_id: h:13752581-4378-478c-af17-165b6e76bc1b +:end: +#+cindex: Development notes + +If you are curious about the principles that govern the development of +this project read the essay [[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): + ++ [[https://protesilaos.com/codelog/2020-05-10-modus-operandi-palette-review/][Modus Operandi theme subtle palette review]] (2020-05-10) ++ [[https://protesilaos.com/codelog/2020-06-13-modus-vivendi-palette-review/][Modus Vivendi theme subtle palette review]] (2020-06-13) ++ [[https://protesilaos.com/codelog/2020-07-04-modus-themes-faint-colours/][Modus themes: new "faint syntax" option]] (2020-07-04) ++ [[https://protesilaos.com/codelog/2020-07-08-modus-themes-nuanced-colours/][Modus themes: major review of "nuanced" colours]] (2020-07-08) ++ [[https://protesilaos.com/codelog/2020-09-14-modus-themes-review-blues/][Modus themes: review of blue colours]] (2020-09-14) ++ [[https://protesilaos.com/codelog/2020-12-27-modus-themes-review-rainbow-delimiters/][Modus themes: review rainbow-delimiters faces]] (2020-12-27) ++ [[https://protesilaos.com/codelog/2021-01-11-modus-themes-review-select-faint-colours/][Modus themes: review of select "faint" colours]] (2021-01-11) ++ [[https://protesilaos.com/codelog/2021-02-25-modus-themes-diffs-deuteranopia/][The Modus themes now cover deuteranopia in diffs]] (2021-02-25) + +And here are the canonical sources of this project's documentation: + ++ Manual :: <https://protesilaos.com/modus-themes> ++ Change Log :: <https://protesilaos.com/modus-themes-changelog> ++ Screenshots :: <https://protesilaos.com/modus-themes-pictures> + +* GNU Free Documentation License +:properties: +:appendix: t +:custom_id: h:3077c3d2-7f90-4228-8f0a-73124f4026f6 +:end: + +#+texinfo: @include doclicense.texi + +#+begin_export html +<pre> + + GNU Free Documentation License + Version 1.3, 3 November 2008 + + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + <https://fsf.org/> + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + +0. PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document "free" in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +1. APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The "Document", below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as "you". You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A "Modified Version" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A "Secondary Section" is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The "Invariant Sections" are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The "Cover Texts" are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A "Transparent" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not "Transparent" is called "Opaque". + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. + +The "Title Page" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +The "publisher" means any person or entity that distributes copies of +the Document to the public. + +A section "Entitled XYZ" means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as "Acknowledgements", +"Dedications", "Endorsements", or "History".) To "Preserve the Title" +of such a section when you modify the Document means that it remains a +section "Entitled XYZ" according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +2. VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no +other conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +3. COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to +give them a chance to provide you with an updated version of the +Document. + + +4. MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +A. Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. +B. List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has fewer than five), + unless they release you from this requirement. +C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. +D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. +F. Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. +G. Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +H. Include an unaltered copy of this License. +I. Preserve the section Entitled "History", Preserve its Title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section Entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. +J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section all + the substance and tone of each of the contributor acknowledgements + and/or dedications given therein. +L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. +M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. +N. Do not retitle any existing section to be Entitled "Endorsements" + or to conflict in title with any Invariant Section. +O. Preserve any Warranty Disclaimers. + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +5. COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled "History" +in the various original documents, forming one section Entitled +"History"; likewise combine any sections Entitled "Acknowledgements", +and any sections Entitled "Dedications". You must delete all sections +Entitled "Endorsements". + + +6. COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other +documents released under this License, and replace the individual +copies of this License in the various documents with a single copy +that is included in the collection, provided that you follow the rules +of this License for verbatim copying of each of the documents in all +other respects. + +You may extract a single document from such a collection, and +distribute it individually under this License, provided you insert a +copy of this License into the extracted document, and follow this +License in all other respects regarding verbatim copying of that +document. + + +7. AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an "aggregate" if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + + +8. TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled "Acknowledgements", +"Dedications", or "History", the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + + +9. TERMINATION + +You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. + + +10. FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions of the +GNU Free Documentation License from time to time. Such new versions +will be similar in spirit to the present version, but may differ in +detail to address new problems or concerns. See +https://www.gnu.org/licenses/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy's public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. + +11. RELICENSING + +"Massive Multiauthor Collaboration Site" (or "MMC Site") means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +"Massive Multiauthor Collaboration" (or "MMC") contained in the site +means any set of copyrightable works thus published on the MMC site. + +"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. + +"Incorporate" means to publish or republish a Document, in whole or in +part, as part of another Document. + +An MMC is "eligible for relicensing" if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole or +in part into the MMC, (1) had no cover texts or invariant sections, and +(2) were thus incorporated prior to November 1, 2008. + +The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. + + +ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + + Copyright (c) YEAR YOUR NAME. + 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, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. +</pre> +#+end_export + +#+html: <!-- + +* Indices +:properties: +:custom_id: h:55104b26-8e94-46cf-9975-43ea00316489 +:end: + +** Function index +:properties: +:index: fn +:custom_id: h:6bec5005-529c-4521-ae05-3d990baffb5b +:end: + +** Variable index +:properties: +:index: vr +:custom_id: h:16ad8df6-b015-40a9-9259-03d4f7a23ee4 +:end: + +** Concept index +:properties: +:index: cp +:custom_id: h:6aa7a656-884b-4c39-b759-087e412eec13 +:end: + +#+html: --> |