diff options
Diffstat (limited to 'doc/misc/modus-themes.org')
| -rw-r--r-- | doc/misc/modus-themes.org | 3303 |
1 files changed, 3303 insertions, 0 deletions
diff --git a/doc/misc/modus-themes.org b/doc/misc/modus-themes.org new file mode 100644 index 00000000000..ed464e84656 --- /dev/null +++ b/doc/misc/modus-themes.org @@ -0,0 +1,3303 @@ +#+title: Modus themes for GNU Emacs +#+author: Protesilaos Stavrou +#+email: info@protesilaos.com +#+language: en +#+options: ':t toc:nil author:t email:t + +#+macro: stable-version 1.2.3 +#+macro: release-date 2021-03-05 +#+macro: development-version 1.3.0-dev +#+macro: export-date (eval (format-time-string "%F %R %z" (current-time))) +#+macro: file @@texinfo:@file{@@$1@@texinfo:}@@ +#+macro: space @@texinfo:@: @@ +# The "kbd" macro turns KBD into @kbd{KBD}. Additionally, it +# encloses case-sensitive special keys (SPC, RET...) within @key{...}. +# I got this from the Org source code. +#+macro: kbd (eval (let ((case-fold-search nil) (regexp (regexp-opt '("SPC" "RET" "LFD" "TAB" "BS" "ESC" "DELETE" "SHIFT" "Ctrl" "Meta" "Alt" "Cmd" "Super" "UP" "LEFT" "RIGHT" "DOWN") 'words))) (format "@@texinfo:@kbd{@@%s@@texinfo:}@@" (replace-regexp-in-string regexp "@@texinfo:@key{@@\\&@@texinfo:}@@" $1 t)))) + +#+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}}}. This manual was +built on {{{export-date}}}. + +#+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 no Front-Cover Texts, +and with no Back-Cover Texts. +#+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]]). + +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]]). 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-slanted-constructs t + modus-themes-bold-constructs nil) + + ;; Load the theme files before enabling a theme (else you get an error). + (modus-themes-load-themes) + :config + ;; Load the theme of your choice: + (modus-themes-load-operandi) ;; OR (modus-themes-load-vivendi) + :bind ("<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. + +Remember that all customization options must be evaluated before loading +a theme ([[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]). + +** 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. + +** Option for more slanted constructs +:properties: +:alt_title: Slanted constructs +:description: Toggle slanted constructs (italics) in code +:custom_id: h:977c900d-0d6d-4dbb-82d9-c2aae69543d6 +:end: +#+vindex: modus-themes-slanted-constructs + +Symbol: ~modus-themes-slanted-constructs~ + +Possible values: + +1. =nil= (default) +2. =t= + +The default is to not use slanted text (italics) unless it is absolutely +necessary. + +With a non-nil value (=t=) choose to render more faces in slanted text. +This typically affects documentation strings and code comments. + +** 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: + +1. =nil= (default) +2. ~faint~ +3. ~yellow-comments~ +4. ~green-strings~ +5. ~yellow-comments-green-strings~ +6. ~alt-syntax~ +7. ~alt-syntax-yellow-comments~ +8. ~faint-yellow-comments~ + +The default style (nil) for code syntax highlighting is a balanced +combination of colors on the cyan-blue-magenta side of the spectrum. +There is little to no use of greens, yellows, or reds, except when it is +necessary. + +Option ~faint~ is like the default in terms of the choice of palette but +applies desaturated color values. + +Option ~yellow-comments~ adds a yellow tint to comments. The rest of the +syntax is the same as the default. + +Option ~green-strings~ replaces the blue/cyan/cold color variants in +strings with greener alternatives. The rest of the syntax remains the +same. + +Option ~yellow-comments-green-strings~ combines yellow comments with green +strings and the rest of the default syntax highlighting style. + +Option ~alt-syntax~ expands the active spectrum by applying color +combinations with more contrasting hues between them. Expect to find +red and green variants in addition to cyan, blue, magenta. + +Option ~alt-syntax-yellow-comments~ combines ~alt-syntax~ with +~yellow-comments~. + +Option ~faint-yellow-comments~ combines the ~faint~ style with +~yellow-comments~. + +** 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: + +1. =nil= (default) +2. ~faint~ +3. ~neutral-underline~ +4. ~faint-neutral-underline~ +5. ~no-underline~ +6. ~underline-only~ +7. ~neutral-underline-only~ + +The default style (nil) for links is to apply an underline and a +saturated color to the affected text. The color of the two is the same, +which makes the link fairly prominent. + +Option ~faint~ follows the same approach as the default, but uses less +intense colors. + +Option ~neutral-underline~ changes the underline's color to a subtle gray, +while retaining the default text color. + +Option ~faint-neutral-underline~ combines a desaturated text color with a +subtle gray underline. + +Option ~no-underline~ removes link underlines altogether, while retaining +their original fairly vivid color. + +Option ~underline-only~ applies a prominent underline while making the +affected text colorless (it uses the same foreground as the theme's +default). + +Option ~neutral-underline-only~ makes the text colorless while using a +subtle gray underline below it. + +NOTE: The placement of the underline, i.e. its proximity to the affected +text, is controlled by the built-in ~x-underline-at-descent-line~, +~x-use-underline-position-properties~, ~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: + +1. =nil= (default) +2. ~subtle-accented~ (~subtle~ exists for backward compatibility) +3. ~intense-accented~ (~intense~ exists for backward compatibility) +4. ~subtle-gray~ +5. ~intense-gray~ + +The default does not use any background for minibuffer and command line +prompts. It relies exclusively on an accented foreground color. + +Options ~subtle-accented~ and ~intense-accented~ will change both the +background and the foreground values to use accented color combinations +that follow the hue of the default styles' foreground (e.g. the default +minibuffer prompt is cyan text, so these combinations will involved a +cyan background and an appropriate cyan foreground). The difference +between the two is that the latter has a more pronounced/noticeable +effect than the former. + +Options ~subtle-gray~, ~intense-gray~ are like their accented counterparts, +except they use grayscale values. + +** 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: + +1. =nil= (default) +2. ~3d~ +3. ~moody~ +4. ~borderless~ +5. ~borderless-3d~ +6. ~borderless-moody~ + +The default produces a two-dimensional effect both for the active and +inactive modelines. The differences between the two are limited to +distinct shades of grayscale values, with the active being more intense +than the inactive. + +Option ~3d~ will make the active modeline look like a three-dimensional +rectangle. Inactive modelines remain 2D, though they are slightly toned +down relative to the default. This aesthetic is virtually the same as +what you get when you run Emacs without any customizations (=emacs -Q= on +the command line). + +While ~moody~ removes all box effects from the modelines and applies +underline and overline properties instead. It also tones down a bit the +inactive modelines. This is meant to optimize things for use with the +[[https://github.com/tarsius/moody][moody package]] (hereinafter referred to as "Moody"), though it can work +fine even without it. + +The ~borderless~ option uses the same colors as the default (nil value), +but removes the border effect. This is done by making the box property +use the same color as the background, effectively blending the two and +creating some padding. + +The ~borderless-3d~ and ~borderless-moody~ approximate the ~3d~ and ~moody~ +options respectively, while removing the borders. However, to ensure +that the inactive modelines remain visible, they apply a slightly more +prominent background to them than what their counterparts do (same +inactive background as with the default). + +Note that Moody does not expose any faces that the themes could style +directly. Instead it re-purposes existing ones to render its tabs and +ribbons. As such, there may be cases where the contrast ratio falls +below the 7:1 target that the themes conform with (WCAG AAA). To hedge +against this, we configure a fallback foreground for the ~moody~ option, +which will come into effect when the background of the modeline changes +to something less accessible, such as Moody ribbons (read the doc string +of ~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 effect, users would need to experiment with the variable +~face-near-same-color-threshold~ to trigger the effect. We find that a +value of =45000= will suffice, contrary to the default =30000=. Do not set +the value too high, because that would have the adverse effect of always +overriding the default color (which has been carefully designed to be +highly accessible). + +Furthermore, because Moody expects an underline and overline instead of +a box style, it is advised you include this in your setup: + +#+begin_src emacs-lisp +(setq x-underline-at-descent-line t) +#+end_src + +** 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 as well as +pattern matching styles like Orderless and Flx. The latter covers Helm, +Ivy, and similar. + +A value of =nil= will 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 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: + +1. =nil= (default) +2. ~subtle-foreground~ +3. ~intense-foreground~ +4. ~straight-underline~ +5. ~subtle-foreground-straight-underline~ +6. ~intense-foreground-straight-underline~ +7. ~colored-background~ + +Nil (the default) applies a color-coded underline to the affected text, +while it leaves the original foreground in tact. If the display spec +where Emacs runs in has support for it (e.g. Emacs GUI), the underline's +style is that of a wave, otherwise it is a straight line. + +Options ~subtle-foreground~ and ~intense-foreground~ follow the same +color-coding pattern and wavy underline of the default, while extending +it with a corresponding foreground value for the affected text. The +difference between the two options is one of degree, as their names +suggest. + +Option ~straight-underline~ is like the default but always applies a +straight line under the affected text. Same principle for +~subtle-foreground-straight-underline~ and its counterpart +~intense-foreground-straight-underline~. + +Option ~colored-background~ uses a straight underline, a tinted +background, and a suitable foreground. All are color-coded. This is +the most intense combination of face properties. + +The present variable affects packages and/or face groups such as those +of =flyspell=, =flymake=, =flycheck=, ~artbollocks-mode~, and ~writegood-mode~. + +NOTE: The placement of the straight underline, though not the wave +style, is controlled by the built-in ~x-underline-at-descent-line~, +~x-use-underline-position-properties~, ~underline-minimum-offset~. Please +refer to their documentation strings. + +** Option for line highlighting (hl-line-mode) +:properties: +:alt_title: Line highlighting +:description: Toggle intense style for current line highlighting +:custom_id: h:1dba1cfe-d079-4c13-a810-f768e8789177 +:end: +#+vindex: modus-themes-intense-hl-line + +Symbol: ~modus-themes-intense-hl-line~ + +Possible values: + +1. =nil= (default) +2. =t= + +The default is to use a subtle gray background for ~hl-line-mode~ and its +global equivalent. + +With a non-nil value (=t=) use a more prominent background color instead. + +This affects several packages that enable ~hl-line-mode~, such as =elfeed= +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: + +1. =nil= (default) +2. ~subtle-bold~ +3. ~intense~ +4. ~intense-bold~ + +Nil means to use a subtle tinted background color for the matching +delimiters. + +Option ~intense~ applies a saturated background color. + +Option ~subtle-bold~ is the same as the default, but also makes use of +bold typographic weight (inherits the ~bold~ face). + +Option ~intense-bold~ is the same as ~intense~, while it also uses a bold +weight. + +This customization variable affects tools such as 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: + +1. =nil= (default) +2. ~no-extend~ +3. ~bg-only~ +4. ~bg-only-no-extend~ + +Nil means to only use a prominent gray background with a neutral +foreground. The foreground overrides all syntax highlighting. The +region extends to the edge of the window. + +Option ~no-extend~ preserves the default aesthetic but prevents the region +from extending to the edge of the window. + +Option ~bg-only~ applies a faint tinted background that is distinct from +all others used in the theme, while it does not override any existing +colors. It extends to the edge of the window. + +Option ~bg-only-no-extend~ is a combination of the ~bg-only~ and ~no-extend~ +options. + +** 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. ~fg-only~ +4. ~bg-only~ +5. ~deuteranopia~ + +By default the themes apply rich coloration to the output of diffs, such +as those of ~diff-mode~, ~ediff~, ~smerge-mode~, and Magit. These are +color combinations of an accented background and foreground so that, for +example, added lines have a pronounced green background with an +appropriate shade of green for the affected text. Word-wise or +"refined" changes follow this pattern but use different shades of those +colors to remain distinct. + +Option ~desaturated~ tones down all relevant color values. It still +combines an accented background with an appropriate foreground, yet its +overall impression is fairly subtle. Refined changes are a bit more +intense to fulfil their intended function, though still less saturated +than default. + +Option ~fg-only~ will remove most accented backgrounds and instead rely +on color-coded text to denote changes. For instance, added lines use a +green foreground, while their background is the same as the rest of the +buffer. Word-wise highlights still use a background value which is, +nonetheless, more subtle than its default equivalent. + +Option ~bg-only~ applies color-coded backgrounds but does not override +any syntax highlighting that may be present. This makes it suitable for +use with a non-nil value for ~diff-font-lock-syntax~ (which is the +default for ~diff-mode~ buffers in Emacs 27 or higher). + +Option ~deuteranopia~ optimizes for red-green color deficiency. It +replaces all instances of green with blue variants. This is to ensure +that indicators for "removed" and "added" states are not mistaken for +each other. + +Concerning Magit, an extra set of tweaks are introduced for the effect +of highlighting the current diff hunk, so as to remain aligned with the +overall experience of that mode. Expect changes that are consistent +with the overall intent of the aforementioned. Note, however, that the +~bg-only~ option will not deliver the intended results in Magit diffs +because no syntax highlighting is used there (last checked with Magit +version 20201116.1057, though upstream has a plan to eventually support +such a feature---this entry shall be updated accordingly). + +** Option for org-mode block styles +:properties: +:alt_title: Org mode blocks +:description: Choose among plain, grayscale, or rainbow styles +: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. ~grayscale~ +3. ~rainbow~ + +The default is to use the same background as the rest of the buffer for +the contents of the block. + +Option ~grayscale~ applies a subtle neutral gray background to the block's +contents. It will also extend to the edge of the window the background +of the "begin" and "end" block delimiter lines (only relevant for Emacs +versions >= 27 where the 'extend' keyword is part of the face +specifications). + +Option ~rainbow~ uses an accented background for the contents of the +block. The exact color will depend on the programming language and is +controlled by the ~org-src-block-faces~ variable. This is most suitable +for users who work on literate programming documents that mix and match +several languages. + +Note that the "rainbow" blocks may require you to also reload the +major-mode so that the colors are applied consistently throughout: use +{{{kbd(M-x org-mode)}}} or {{{kbd(M-x org-mode-restart)}}} to refresh the buffer. +Or start typing in each code block (inefficient at scale, but it still +works). + +** Option for org-habit graph styles +:properties: +:alt_title: Org agenda habits +:description: Choose among standard, simplified, or traffic light styles +:custom_id: h:b7e328c0-3034-4db7-9cdf-d5ba12081ca2 +:end: +#+vindex: modus-themes-org-habit + +Symbol: ~modus-themes-org-habit~ + +Possible values: + +1. =nil= (default) +2. ~simplified~ +3. ~traffic-light~ + +The default 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. + +Option ~simplified~ is like the default except that it removes the +dichotomy between current and future variants by applying uniform +color-coded values. It applies a total of four colors: red, yellow, +green, blue. They produce a simplified consistency graph that is more +legible (or less "busy") than the default. The intent is to shift focus +towards the distinction between the four states of a habit task, rather +than each state's present/future outlook. + +Option ~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. + +** 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 + +This is defined as an alist and, therefore, uses a different approach +than other customization options documented in this manual. + +Symbol: ~modus-themes-headings~ + +Possible values, which can be specified for each heading level (examples +further below): + ++ nil (default fallback option---covers all heading levels) ++ =t= (default style for a single heading, when the fallback differs) ++ ~no-bold~ ++ ~line~ ++ ~line-no-bold~ ++ ~rainbow~ ++ ~rainbow-line~ ++ ~rainbow-line-no-bold~ ++ ~highlight~ ++ ~highlight-no-bold~ ++ ~rainbow-highlight~ ++ ~rainbow-highlight-no-bold~ ++ ~section~ ++ ~section-no-bold~ ++ ~rainbow-section~ ++ ~rainbow-section-no-bold~ ++ ~no-color~ ++ ~no-color-no-bold~ + +To control faces per level from 1-8, use something like this: + +#+begin_src emacs-lisp +(setq modus-themes-headings + '((1 . section) + (2 . section-no-bold) + (3 . rainbow-line) + (t . rainbow-line-no-bold))) +#+end_src + +The above uses the ~section~ value for heading levels 1, ~section-no-bold~ +for headings 2, ~rainbow-line~ for 3. All other levels fall back to +~rainbow-line-no-bold~. + +To set a uniform value for all heading levels, use this pattern: + +#+begin_src emacs-lisp +;; A given style for every heading +(setq modus-themes-headings + '((t . section))) + +;; Default aesthetic for every heading +(setq modus-themes-headings + '()) +#+end_src + +The default style for headings uses a fairly desaturated foreground +value in combination with bold typographic weight. To specify this +style for a given level N, assuming you wish to have another fallback +option, just specify the value =t= like this: + +#+begin_src emacs-lisp +(setq modus-themes-headings + '((1 . t) + (2 . line) + (t . rainbow-line-no-bold))) +#+end_src + +A description of all other possible styles beyond the default: + ++ ~no-bold~ retains the default text color while removing the bold + typographic weight. + ++ ~line~ is the same as the default plus an overline across the + heading's length. + ++ ~line-no-bold~ is the same as ~line~ without bold weight. + ++ ~rainbow~ uses a more colorful foreground in combination with bold + typographic weight. + ++ ~rainbow-line~ is the same as ~rainbow~ plus an overline. + ++ ~rainbow-line-no-bold~ is the same as ~rainbow-line~ without the bold + weight. + ++ ~highlight~ retains the default style of a fairly desaturated + foreground combined with a bold weight and adds to it a subtle + accented background. + ++ ~highlight-no-bold~ is the same as ~highlight~ without a bold weight. + ++ ~rainbow-highlight~ is the same as ~highlight~ but with a more + colorful foreground. + ++ ~rainbow-highlight-no-bold~ is the same as ~rainbow-highlight~ without + a bold weight. + ++ ~section~ retains the default looks and adds to them both an overline + and a slightly accented background. It is, in effect, a combination + of the ~line~ and ~highlight~ values. + ++ ~section-no-bold~ is the same as ~section~ without a bold weight. + ++ ~rainbow-section~ is the same as ~section~ but with a more colorful + foreground. + ++ ~rainbow-section-no-bold~ is the same as ~rainbow-section~ without a + bold weight. + ++ ~no-color~ does not apply any color to the heading, meaning that it + uses the foreground of the ~default~ face. It still renders the text + with a bold typographic weight. + ++ ~no-color-no-bold~ is like ~no-color~ but without the bold weight. + +** 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-5 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-5~ is applied to special headings that do not +conform with the aforementioned syntax, yet which are expected to be +larger than the largest value on that implied scale. Put concretely, +Org's =#+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-5~. + +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-5~ to make it the same as body text (or whatever +value would render it indistinguishable from the desired point of +reference). + +Note that in earlier versions of Org, scaling would only increase the +size of the heading, but not of keywords that were added to it, like +"TODO". The issue has been fixed upstream: +<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 + +** 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-colors-operandi + '((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). Preferences aside, it is +advised to inspect the source code of ~modus-themes-operandi-colors~ and +~modus-themes-vivendi-colors~ to read the inline commentary: it explains +what the intended use of each palette subset is. + +Furthermore, users may benefit from the ~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. + +** 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 + +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). + +** 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: + +#+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 important: the last item is applied +over the previous ones. If you do not want to blend multiple faces, you +do not need a quoted list. A pattern of =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]]. + +** 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 +: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 + +** 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 ++ 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 ++ counsel* ++ counsel-css ++ counsel-notmuch ++ counsel-org-capture-string ++ cov ++ cperl-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 ++ emms ++ 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 ++ 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 ++ 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 ++ modeline ++ 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 ++ 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 ++ 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 ++ table (built-in table.el) ++ telephone-line ++ terraform-mode ++ term ++ tomatinho ++ transient (pop-up windows such as Magit's) ++ trashed ++ treemacs ++ tty-menu ++ tuareg ++ typescript ++ undo-tree ++ vc (built-in mode line status for version control) ++ vc-annotate (the out put of {{{kbd(C-x v g)}}}) ++ vdiff ++ 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. Please confirm. + ++ edit-indirect ++ evil-owl ++ fortran-mode ++ goggles ++ i3wm-config-mode ++ perl-mode ++ php-mode ++ rjsx-mode ++ swift-mode ++ tab-bar-echo-area + +* Notes for 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 for 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 for 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 for 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 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 for 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 for 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 modeline 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 for 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 + +* 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, Kostadin + Ninev, Madhavan Krishnan, Markus Beppler, Matthew Stevenson, Nicolas + De Jaeghere, 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, Gerry Agbobada, Gianluca Recchia, Gustavo + Barros, Hörmetjan Yiltiz, Ilja Kocken, Iris Garcia, Jeremy Friesen, + John Haman, Joshua O'Connor, Kevin Fleming, Kostadin Ninev, Len Trigg, + Manuel Uberti, Mark Burton, Markus Beppler, Michael Goldenberg, Morgan + Smith, Murilo Pereira, Nicolas De Jaeghere, Paul Poloskov, Pete + Kazmier, Peter Wu, Philip K., Pierre Téchoueyres, Roman Rudakov, Ryan + Phillips, Sam Kleinman, Shreyas Ragavan, Simon Pugnet, Tassilo Horn, + Thibaut Verron, Trey Merkley, Togan Muftuoglu, Toon Claes, Uri Sharf, + Utkarsh Singh, Vincent Foley. As well as users: Ben, CsBigDataHub1, + Emacs Contrib, Eugene, Fourchaux, Fredrik, Moesasji, Nick, TheBlob42, + bepolymathe, doolio, fleimgruber, iSeeU, jixiuf, okamsn. + ++ 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 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 + + 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. +#+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: --> |