From 3984044ad3f481b0c67e906a405176ae276dd44d Mon Sep 17 00:00:00 2001 From: Protesilaos Stavrou Date: Fri, 26 Feb 2021 19:27:57 -0800 Subject: [PATCH] Import org source file for modus-themes manual * doc/misc/modus-themes.org: New file. Import from https://gitlab.com/protesilaos/modus-themes 515180ac. --- doc/misc/modus-themes.org | 1955 +++++++++++++++++++++++++++++++++++++ 1 file changed, 1955 insertions(+) create mode 100644 doc/misc/modus-themes.org diff --git a/doc/misc/modus-themes.org b/doc/misc/modus-themes.org new file mode 100644 index 00000000000..db15db46b5e --- /dev/null +++ b/doc/misc/modus-themes.org @@ -0,0 +1,1955 @@ +#+TITLE: Modus themes for GNU Emacs +#+AUTHOR: Protesilaos Stavrou +#+EMAIL: info@protesilaos.com +#+TEXINFO_DIR_CATEGORY: Emacs misc features +#+TEXINFO_DIR_TITLE: Modus Themes: (modus-themes) +#+TEXINFO_DIR_DESC: Highly accessible themes (WCAG AAA) +#+OPTIONS: ':t toc:nil author:t email:t +#+MACRO: version-tag 0.13.0 +#+MACRO: release-date 2020-10-08 + +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 version {{{version-tag}}}, +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. + +Copyright (C) 2020 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 + +#+TOC: headlines 8 insert TOC here, with eight headline levels + +* 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 +(see [[#h:a9c8f29d-7f72-4b54-b74b-ddefe15d6a19][Face coverage]]). + +Starting with version 0.12.0 and onwards, the themes are built into GNU +Emacs (current version is {{{version-tag}}}). + +** How do the themes look like +:PROPERTIES: +:CUSTOM_ID: h:69b92089-069c-4ba1-9d94-cc3415fc4f87 +:END: + +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: + +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. + +Modus Operandi (light theme) and Modus Vivendi (dark) are normally +distributed as standalone packages in Emacs-specific archives. There +also exist packages for GNU/Linux distributions. + +** Install from the archives +:PROPERTIES: +:CUSTOM_ID: h:c4b10085-149f-43e2-bd4d-347f33aee054 +:END: + +=modus-operandi-theme= and =modus-vivendi-theme= are available from GNU the +ELPA archive, which is configured by default. + +Prior to querying any package archive, make sure to have updated the +index, with =M-x package-refresh-contents=. Then all you need to do is +type =M-x package-install= and specify the theme of your choice. + +** Install on GNU/Linux +:PROPERTIES: +:CUSTOM_ID: h:da640eb1-95dd-4e86-bb4e-1027b27885f0 +:END: + +The themes are also available from the archives of some GNU/Linux +distributions. 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 two themes are distributed as a single package for Debian and its +derivatives. Currently in the unstable and testing suites and should be +available in time for Debian 11 Bullseye (next stable). + +Get them with: + +#+begin_src sh +sudo apt install elpa-modus-themes +#+end_src + +*** GNU Guix +:PROPERTIES: +:CUSTOM_ID: h:a4ca52cd-869f-46a5-9e16-4d9665f5b88e +:END: + +Users of either the Guix System (the distro) or just Guix (the package +manager) can get each theme as a standalone package. + +#+begin_src sh +guix package -i emacs-modus-operandi-theme +#+end_src + +And/or: + +#+begin_src sh +guix package -i emacs-modus-vivendi-theme +#+end_src + +* Enable and load +:PROPERTIES: +:CUSTOM_ID: h:3f3c3728-1b34-437d-9d0c-b110f5b161a9 +:END: + +This section documents how to load the theme of your choice and how to +further control its initialization. It also includes some sample code +snippets that could help you in the task, especially if you intend to +use both Modus Operandi and Modus Vivendi. + +** Load automatically +:PROPERTIES: +:CUSTOM_ID: h:1777c247-1b56-46b7-a4ce-54e720b33d06 +:END: + +A simple way to load the theme from your Emacs initialization file is to +include either of the following expressions: + +#+BEGIN_SRC emacs-lisp +(load-theme 'modus-operandi t) ; Light theme +(load-theme 'modus-vivendi t) ; Dark theme +#+END_SRC + +Make sure to remove any other theme that is being loaded, otherwise you +might run into unexpected issues. + +Note that you can always =M-x disable-theme= and specify an item. The +command does exactly what its name suggests. To deactivate all enabled +themes at once, in case you have multiple of them enabled, you may +evaluate the expression: + +#+begin_src emacs-lisp +(mapc #'disable-theme custom-enabled-themes) +#+end_src + +** Load at a given time or at sunset/sunrise +:PROPERTIES: +:CUSTOM_ID: h:4e936e31-e9eb-4b50-8fdd-45d827a03cca +:END: + +It is possible to schedule a time during the day at or after which a +given theme will be loaded.[fn:: Contributed on Reddit by user =b3n=, +https://www.reddit.com/r/emacs/comments/gdtqov/weekly_tipstricketc_thread/fq9186h/.] + +#+begin_src emacs-lisp +;; Light for the day +(load-theme 'modus-operandi t t) +(run-at-time "05:00" (* 60 60 24) + (lambda () + (enable-theme 'modus-operandi))) + +;; Dark for the night +(load-theme 'modus-vivendi t t) +(run-at-time "21:00" (* 60 60 24) + (lambda () + (enable-theme 'modus-vivendi))) +#+end_src + +A modified version of the above technique is to use the sunrise and +sunset as references, instead of specifying a fixed hour value.[fn:: +Contributed directly by André Alexandre Gomes https://gitlab.com/aadcg.] +If you set =calendar-latitude= and =calendar-longitude= (defined in the +built-in =solar.el= library---read it with =M-x find-library=), you can +automatically switch between both themes at the appropriate time-of-day. +Note that /those calendar variables need to be set before loading the +themes/. + +#+begin_src emacs-lisp +;; Define coordinates +(setq calendar-latitude 35.17 + calendar-longitude 33.36) + +;; Light at sunrise +(load-theme 'modus-operandi t t) +(run-at-time (nth 1 (split-string (sunrise-sunset))) + (* 60 60 24) + (lambda () + (enable-theme 'modus-operandi))) + +;; Dark at sunset +(load-theme 'modus-vivendi t t) +(run-at-time (nth 4 (split-string (sunrise-sunset))) + (* 60 60 24) + (lambda () + (enable-theme 'modus-vivendi))) +#+end_src + +For the sake of completeness, the =load-theme= call in these snippets is +slightly different than the one shown in [[#h:1777c247-1b56-46b7-a4ce-54e720b33d06][Load automatically]], because it +does not enable the theme directly: the subsequent =enable-theme= does +that when needed. + +** Toggle between the themes on demand +:PROPERTIES: +:CUSTOM_ID: h:2a0895a6-3281-4e55-8aa1-8a737555821e +:END: + +With both themes available, it is possible to design a simple command to +switch between them on demand. + +#+begin_src emacs-lisp +(defun modus-themes-toggle () + "Toggle between `modus-operandi' and `modus-vivendi' themes." + (interactive) + (if (eq (car custom-enabled-themes) 'modus-operandi) + (progn + (disable-theme 'modus-operandi) + (load-theme 'modus-vivendi t)) + (disable-theme 'modus-vivendi) + (load-theme 'modus-operandi t))) +#+end_src + +You could use =(mapc #'disable-theme custom-enabled-themes)= instead of +disabling a single target, but you get the idea. + +** Configure options prior to loading +:PROPERTIES: +:CUSTOM_ID: h:a897b302-8e10-4a26-beab-3caaee1e1193 +:END: + +If you plan to use both themes and wish to apply styles consistently +(see [[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization Options]]), you could define wrapper functions around +the standard =load-theme= command. These extend the simple function we +presented in [[#h:2a0895a6-3281-4e55-8aa1-8a737555821e][Toggle between the themes on demand]]. + +Here is a comprehensive setup (the values assigned to the variables are +just for the sake of this demonstration):[fn:: The =defmacro= and =dolist= +method were contributed on Reddit by user =b3n= +https://www.reddit.com/r/emacs/comments/gqsz8u/weekly_tipstricketc_thread/fsfakhg/.] + +#+begin_src emacs-lisp +(defmacro modus-themes-format-sexp (sexp &rest objects) + `(eval (read (format ,(format "%S" sexp) ,@objects)))) + +(dolist (theme '("operandi" "vivendi")) + (modus-themes-format-sexp + (defun modus-%1$s-theme-load () + (setq modus-%1$s-theme-slanted-constructs t + modus-%1$s-theme-bold-constructs t + modus-%1$s-theme-fringes 'subtle ; {nil,'subtle,'intense} + modus-%1$s-theme-mode-line '3d ; {nil,'3d,'moody} + modus-%1$s-theme-syntax 'alt-syntax ; {nil,faint,'yellow-comments,'green-strings,'yellow-comments-green-strings,'alt-syntax,'alt-syntax-yellow-comments} + modus-%1$s-theme-intense-hl-line nil + modus-%1$s-theme-intense-paren-match nil + modus-%1$s-theme-links 'faint ; {nil,'faint,'neutral-underline,'faint-neutral-underline,'no-underline} + modus-%1$s-theme-no-mixed-fonts nil + modus-%1$s-theme-prompts nil ; {nil,'subtle,'intense} + modus-%1$s-theme-completions 'moderate ; {nil,'moderate,'opinionated} + modus-%1$s-theme-diffs nil ; {nil,'desaturated,'fg-only} + modus-%1$s-theme-org-blocks 'grayscale ; {nil,'grayscale,'rainbow} + modus-%1$s-theme-headings ; Read further below in the manual for this one + '((1 . section) + (2 . line) + (t . rainbow-line-no-bold)) + modus-%1$s-theme-variable-pitch-headings nil + modus-%1$s-theme-scale-headings t + modus-%1$s-theme-scale-1 1.1 + modus-%1$s-theme-scale-2 1.15 + modus-%1$s-theme-scale-3 1.21 + modus-%1$s-theme-scale-4 1.27 + modus-%1$s-theme-scale-5 1.33) + (load-theme 'modus-%1$s t)) + theme)) + +(defun modus-themes-toggle () + "Toggle between `modus-operandi' and `modus-vivendi' themes." + (interactive) + (if (eq (car custom-enabled-themes) 'modus-operandi) + (progn + (disable-theme 'modus-operandi) + (modus-vivendi-theme-load)) + (disable-theme 'modus-vivendi) + (modus-operandi-theme-load))) +#+end_src + +* 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=. + +All customization options need to be evaluated before loading their +theme (see [[#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: + +Symbol names: + ++ =modus-operandi-theme-bold-constructs= ++ =modus-vivendi-theme-bold-constructs= + +Possible values: + +1. =nil= (default) +2. =t= + +Display several 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. + +The default is to only use a bold weight when it is required. + +Additionally, and while not necessary, to define the precise weight for +bold constructs, you can change the typographic intensity of the =bold= +face. The standard is a bold weight. It requires no further +intervention. Assuming though that your typeface of choice supports a +"semibold" weight, adding the following snippet to your init file should +suffice. + +#+begin_src emacs-lisp +(set-face-attribute 'bold nil :weight 'semibold) +#+end_src + +Note that if you are switching themes, you need to re-evaluate this +expression after the new theme is loaded. + +** 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: + +Symbol names: + ++ =modus-operandi-theme-slanted-constructs= ++ =modus-vivendi-theme-slanted-constructs= + +Possible values: + +1. =nil= (default) +2. =t= + +Choose to render more faces in slanted text (italics). This typically +affects documentation strings and code comments. + +The default is to not use italics unless it is absolutely necessary. + +** Option for faint code syntax highlighting (deprecated for ~0.14.0~) +:PROPERTIES: +:ALT_TITLE: Faint syntax +:DESCRIPTION: Toggle subtle coloration in code (deprecated for 0.14.0) +:CUSTOM_ID: h:741379fe-7203-4dad-a7f8-ab71f61b43e6 +:END: + +Symbol names: + ++ =modus-operandi-theme-faint-syntax= ++ =modus-vivendi-theme-faint-syntax= + +Possible values: + +1. =nil= (default) +2. =t= + +Use less saturated colors in programming modes for highlighting code +syntax. The default is to use saturated colors. + +This option essentially affects the font-lock faces, so it may also have +implications in other places that are hard-wired to rely directly on +them instead of specifying their own faces (which could inherit from +font-lock if that is the intent). The author is aware of =vc-dir= as a +case in point. + +** 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: + +This option supersedes the "faint syntax" one ahead of version =0.14.0= +([[#h:741379fe-7203-4dad-a7f8-ab71f61b43e6][Option for faint code syntax highlighting]]). + +Symbol names: + ++ =modus-operandi-theme-syntax= ++ =modus-vivendi-theme-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= + +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= applies 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 color palette and applies new color +combinations. Strings are green. Doc strings are magenta tinted. +Comments are gray. + +Option =alt-syntax-yellow-comments= combines =alt-syntax= 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: + +Symbol names: + ++ =modus-operandi-theme-no-mixed-fonts= ++ =modus-vivendi-theme-no-mixed-fonts= + +Possible values: + +1. =nil= (default) +2. =t= + +By default, the themes configure some spacing-sensitive faces, such as +Org tables and code blocks, to always inherit from the =fixed-pitch= face. +This is to ensure that those constructs remain monospaced when users opt +for something like the built-in =M-x variable-pitch-mode=. Otherwise the +layout would appear broken. 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=. + +** Option for no link underline (deprecated for ~0.14.0~) +:PROPERTIES: +:ALT_TITLE: Link underline +:DESCRIPTION: Toggle underlined text in links (deprecated for 0.14.0) +:CUSTOM_ID: h:a1a639e9-d247-414c-a0ad-08adadcbc6c1 +:END: + +Note: deprecated ahead of version =0.14.0= ([[#h:c119d7b2-fcd4-4e44-890e-5e25733d5e52][Option for links]]). + +Symbol names: + ++ =modus-operandi-theme-no-link-underline= ++ =modus-vivendi-theme-no-link-underline= + +Possible values: + +1. =nil= (default) +2. =t= + +Remove the underline effect from links, symbolic links, and buttons. +The default is to apply an underline. + +** Option for links +:PROPERTIES: +:ALT_TITLE: Link styles +:DESCRIPTION: Choose color intensity or no underline for links +:CUSTOM_ID: h:c119d7b2-fcd4-4e44-890e-5e25733d5e52 +:END: + +This option supersedes the "no link underline" one ahead of version +=0.14.0= ([[#h:a1a639e9-d247-414c-a0ad-08adadcbc6c1][Option for no link underline]]). + +Symbol names: + ++ =modus-operandi-theme-links= ++ =modus-vivendi-theme-links= + +Possible values: + +1. =nil= (default) +2. =faint= +3. =neutral-underline= +4. =faint-neutral-underline= +5. =no-underline= + +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 keeping +their text color the same as the default. + +** 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: + +Symbol names: + ++ =modus-operandi-theme-prompts= ++ =modus-vivendi-theme-prompts= + +Possible values: + +1. =nil= (default) +2. =subtle= +3. =intense= + +The symbols "subtle" and "intense" will apply a combination of accented +background and foreground to the minibuffer and other REPL prompts (like +=M-x shell= and =M-x eshell=). The difference between the two is that the +latter has a more pronounced/noticeable effect than the former. + +The default does not use any background for such prompts, while relying +exclusively on an accented foreground color. + +** Option for mode line presentation +:PROPERTIES: +:ALT_TITLE: Mode line +:DESCRIPTION: Choose among plain, three-dimension, or moody-compliant styles +:CUSTOM_ID: h:27943af6-d950-42d0-bc23-106e43f50a24 +:END: + +Symbol names: + ++ =modus-operandi-theme-mode-line= ++ =modus-vivendi-theme-mode-line= + +Possible values: + +1. =nil= (default) +2. =3d= +3. =moody= + +The default value (=nil=) 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. + +A =3d= symbol 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 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. + +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 +comes into effect 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 fallback color. +We find that a value of =45000= would 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 recommended you also 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: + +Symbol names: + ++ =modus-operandi-theme-completions= ++ =modus-vivendi-theme-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. + +The symbol =moderate= will apply 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 et al will appear slightly different +than their original looks, as they are toned down a bit. + +The symbol =opinionated= will apply 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 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 plain, subtle, or intense fringe visibility +:CUSTOM_ID: h:1983c3fc-74f6-44f3-b917-967c403bebae +:END: + +Symbol names: + ++ =modus-operandi-theme-fringes= ++ =modus-vivendi-theme-fringes= + +Possible values: + +1. =nil= (default) +2. =subtle= +3. =intense= + +The "subtle" symbol will apply a grayscale background that is visible, +yet close enough to the main background color. While the "intense" +symbol will use a more noticeable grayscale background. + +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=. + +** 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: + +Symbol names: + ++ =modus-operandi-theme-intense-hl-line= ++ =modus-vivendi-theme-intense-hl-line= + +Possible values: + +1. =nil= (default) +2. =t= + +Draw the current line of =hl-line-mode= or its global equivalent in a more +prominent background color. This would also affect several packages +that enable =hl-line-mode=, such as =elfeed= and =mu4e=. + +The default is to use a more subtle gray. + +** Option for parenthesis matching (show-paren-mode) +:PROPERTIES: +:ALT_TITLE: Matching parentheses +:DESCRIPTION: Toggle intense style for matching delimiters/parentheses +:CUSTOM_ID: h:e66a7e4d-a512-4bc7-9f86-fbbb5923bf37 +:END: + +Symbol names: + ++ =modus-operandi-theme-intense-paren-match= ++ =modus-vivendi-theme-intense-paren-match= + +Possible values: + +1. =nil= (default) +2. =t= + +Apply a more intense background to the matching parentheses (or +delimiters). This affects tools such as the built-in =show-paren-mode=. +The default is to use a subtle warm color for the background of those +overlays. + +** 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: + +Symbol names: + ++ =modus-operandi-theme-diffs= ++ =modus-vivendi-theme-diffs= + +Possible values: + +1. =nil= (default) +2. =desaturated= +2. =fg-only= + +By default the themes will apply richly colored backgrounds 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. + +A =desaturated= value tones down all relevant color values. It still +combines an accented background with an appropriate foreground, yet its +overall impression is very subtle. Refined changes are a bit more +intense to fulfil their intended function, though still less saturated +than default. + +While =fg-only= will remove all accented backgrounds and instead rely on +color-coded text to denote changes. For instance, added lines use an +intense 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. + +Concerning =magit=, an extra set of tweaks are introduced for the effect +of highlighting the current diff hunk, so as to remain consistent with +the overall experience of that mode. Expect changes that are consistent +with the overall intent of the aforementioned. + +** 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: + +Symbol names: + ++ =modus-operandi-theme-org-blocks= ++ =modus-vivendi-theme-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. + +A value of =grayscale= will apply 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 recognised by +=set-face-attribute=). + +While =rainbow= will instead use 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 (refer to the +theme's source code for the current association list). 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 properly: use =M-x org-mode= or +=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 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: + +This is defined as an alist and, therefore, uses a different approach +than other customization options documented in this manual. + +Symbol names: + ++ =modus-operandi-theme-headings= ++ =modus-vivendi-theme-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= + +To control faces per level from 1-8, use something like this (same for +=modus-vivendi-theme-headings=): + +#+begin_src emacs-lisp +(setq modus-operandi-theme-headings + '((1 . section) + (2 . line) + (3 . highlight) + (t . rainbow-no-bold))) +#+end_src + +The above uses the =section= value for heading levels 1, the =line= for +headings 2, =highlight= 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-operandi-theme-headings + '((t . rainbow-line-no-bold))) + +;; Default aesthetic for every heading +(setq modus-operandi-theme-headings + '((t . nil))) +#+end_src + +The default style for headings uses a fairly desaturated foreground +value in combination with a 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-operandi-theme-headings + '((1 . t) + (2 . line) + (t . rainbow-line-no-bold))) +#+end_src + +A description of all other possible styles: + ++ =no-bold= retains the default text color while removing the typographic + weight. + ++ =line= is the same as the default plus an overline over the heading. + ++ =line-no-bold= is the same as =line= without bold weight. + ++ =rainbow= uses a more colorful foreground in combination with bold + 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." + +** Option for scaled headings +:PROPERTIES: +:ALT_TITLE: Scaled headings +:DESCRIPTION: Toggle scaling of headings +:CUSTOM_ID: h:075eb022-37a6-41a4-a040-cc189f6bfa1f +:END: + +Symbol names: + ++ =modus-operandi-theme-scale-headings= ++ =modus-vivendi-theme-scale-headings= + +Possible values: + +1. =nil= (default) +2. =t= + +Make headings larger in height relative to the main text. This is +noticeable in modes like Org. The default is to use the same size for +headings and body copy. + +*** 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 toggles 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. + ++ If it is an integer, it is read as an absolute font height. The + number is basically the point size multiplied by ten. So if you want + it to be =18pt= you must pass =180=. Please understand that setting an + absolute value is discouraged, as it will break the layout when you + try to change font sizes with the built-in =text-scale-adjust= command + (see [[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations]]). + +Below are the variables in their default values, using the floating +point paradigm. The numbers are very conservative, but you are free to +change them to your 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-operandi-theme-scale-1 1.05 + modus-operandi-theme-scale-2 1.1 + modus-operandi-theme-scale-3 1.15 + modus-operandi-theme-scale-4 1.2 + modus-operandi-theme-scale-5 1.3) + +(setq modus-vivendi-theme-scale-1 1.05 + modus-vivendi-theme-scale-2 1.1 + modus-vivendi-theme-scale-3 1.15 + modus-vivendi-theme-scale-4 1.2 + modus-vivendi-theme-scale-5 1.3) +#+end_src + +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: +. + +** Option for variable-pitch font in headings +:PROPERTIES: +:ALT_TITLE: Headings' font +:DESCRIPTION: Toggle proportionately spaced fonts in headings +:CUSTOM_ID: h:97caca76-fa13-456c-aef1-a2aa165ea274 +:END: + +Symbol names: + ++ =modus-operandi-theme-variable-pitch-headings= ++ =modus-vivendi-theme-variable-pitch-headings= + +Possible values: + +1. =nil= (default) +2. =t= + +Choose to apply a proportionately spaced, else "variable-pitch", +typeface to headings (such as in Org mode). The default is to use the +main font family. + +[[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org (and others)]]. + +* Advanced customization (do-it-yourself) +:PROPERTIES: +:INDEX: cp +:CUSTOM_ID: h:f4651d55-8c07-46aa-b52b-bed1e53463bb +:END: + +Unlike the predefined customization options which follow a +straightforward 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 (see [[#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". + +** Full access to the themes' palette +:PROPERTIES: +:ALT_TITLE: Tweak colors (DIY) +:DESCRIPTION: Declare your own palette overrides +:CUSTOM_ID: h:1487c631-f4fe-490d-8d58-d72ffa3bd474 +:END: + +The variables are: + ++ =modus-operandi-theme-override-colors-alist= ++ =modus-vivendi-theme-override-colors-alist= + +Users can specify an association list that maps the names of color +variables to hexadecimal RGB values (in the form of =#RRGGBB=). This +means that it is possible to override the entire palette or subsets +thereof (see the source code for the actual names and values). + +Example: + +#+begin_src emacs-lisp +;; Redefine the values of those three variables for the given theme +(setq modus-vivendi-theme-override-colors-alist + '(("magenta" . "#ffaabb") + ("magenta-alt" . "#ee88ff") + ("magenta-alt-other" . "#bbaaff"))) +#+end_src + +If you want to be creative, you can define a minor mode that refashions +the themes on demand. The following is a minor mode that gets activated +on demand. We combine it with the function to switch between Modus +Operandi and Modus Vivendi (see [[#h:2a0895a6-3281-4e55-8aa1-8a737555821e][Toggle between the themes on demand]] for +a basic command, and/or [[*Configure options prior to loading][Configure options prior to loading]] for a more +comprehensive setup). + +#+begin_src emacs-lisp +(define-minor-mode modus-themes-alt-mode + "Override Modus themes' palette variables with custom values. + +This is intended as a proof-of-concept. It is, nonetheless, a +perfectly accessible alternative, conforming with the design +principles of the Modus themes. It still is not as good as the +default colors." + :init-value nil + :global t + (if modus-themes-alt-mode + (setq modus-operandi-theme-override-colors-alist + '(("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-vivendi-theme-override-colors-alist + '(("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-operandi-theme-override-colors-alist nil + modus-vivendi-theme-override-colors-alist nil))) + +(defun modus-themes-toggle (&optional arg) + "Toggle between `modus-operandi' and `modus-vivendi' themes. + +With optional \\[universal-argument] prefix, enable +`modus-themes-alt-mode' for the loaded theme." + (interactive "P") + (if arg + (modus-themes-alt-mode 1) + (modus-themes-alt-mode -1)) + (if (eq (car custom-enabled-themes) 'modus-operandi) + (progn + (disable-theme 'modus-operandi) + (load-theme 'modus-vivendi t)) + (disable-theme 'modus-vivendi) + (load-theme 'modus-operandi t))) +#+end_src + +** Font configurations for Org (and others) +:PROPERTIES: +:ALT_TITLE: Font configs (DIY) +:DESCRIPTION: Optimise for mixed typeface buffers +:CUSTOM_ID: h:defcf4fc-8fa8-4c29-b12e-7119582cc929 +:END: + +The themes are designed to cope well with mixed font settings ([[#h:115e6c23-ee35-4a16-8cef-e2fcbb08e28b][Option +for no font mixing]]). Currently this applies to =org-mode= and +=markdown-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 =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 (make sure to read +the documentation of =set-face-attribute=, with =M-x describe-function=): + +#+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 at =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, say, =15= 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). + +An alternative syntax for the =default= face, is to pass all typeface +parameters directly to a =font= property.[fn:: Has the benefit of +accepting =fontconfig= parameters (GNU/Linux), such as ="DejaVu Sans +Mono-11:hintstyle=hintslight:autohint=false"=. +https://www.freedesktop.org/software/fontconfig/fontconfig-user.html] +Note that here we use a standard point size: + +#+begin_src emacs-lisp +(set-face-attribute 'default nil :font "DejaVu Sans Mono-11") +#+end_src + +Again, remember to only ever specify an absolute height for the =default=. + +** Org user faces (DIY) +:PROPERTIES: +:DESCRIPTION: Extend styles for org-mode keywords and priorities +:CUSTOM_ID: h:89f0678d-c5c3-4a57-a526-668b2bb2d7ad +:END: + +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 would be futile to have the +themes try to guess what each user would want 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 aesthetics of the theme. + +Please bear in mind that the end result of those is not controlled by +the active theme but by how Org maps faces to its constructs. Editing +those while =org-mode= is active requires =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= would 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 +=M-x list-faces-display=. Also try =M-x describe-variable= and then specify +the name of each of those Org variables demonstrated above. Their +documentation strings will offer you further guidance. + +Furthermore, consider reading the "Notes for aspiring Emacs theme +developers", published on 2020-08-28 by me (Protesilaos Stavrou): +https://protesilaos.com/codelog/2020-08-28-notes-emacs-theme-devs/. + +* Face coverage +:PROPERTIES: +:CUSTOM_ID: h:a9c8f29d-7f72-4b54-b74b-ddefe15d6a19 +:END: + +Modus Operandi and Modus Vivendi try to provide as close to full face +coverage as possible. This is necessary to ensure a consistently +accessible reading experience across all possible 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: + +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 ++ binder ++ bm ++ bongo ++ boon ++ breakpoint (provided by the built-in =gdb-mi.el= library) ++ buffer-expose ++ calendar and diary ++ calfw ++ centaur-tabs ++ change-log and log-view (such as =vc-print-log= and =vc-print-root-log=) ++ cider ++ circe ++ color-rg ++ column-enforce-mode ++ company-mode* ++ company-posframe ++ compilation-mode ++ completions ++ counsel* ++ counsel-css ++ counsel-notmuch ++ counsel-org-capture-string ++ cov ++ cperl-mode ++ csv-mode ++ ctrlf ++ custom (=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 ++ diredfl ++ disk-usage ++ 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-visual-mark-mode ++ eww ++ 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. ++ 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 ++ magit ++ magit-imerge ++ make-mode ++ man ++ markdown-mode ++ markup-faces (=adoc-mode=) ++ mentor ++ messages ++ minibuffer-line ++ minimap ++ 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-treescope ++ origami ++ outline-mode ++ outline-minor-faces ++ package (=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 ++ proced ++ prodigy ++ racket-mode ++ rainbow-blocks ++ rainbow-identifiers ++ rainbow-delimiters ++ rcirc ++ regexp-builder (also known as =re-builder=) ++ rg (rg.el) ++ ripgrep ++ rmail ++ ruler-mode ++ sallet ++ selectrum ++ semantic ++ sesman ++ shell-script-mode ++ show-paren-mode ++ shr ++ side-notes ++ sieve-mode ++ skewer-mode ++ smart-mode-line ++ smartparens ++ smerge ++ spaceline ++ speedbar ++ spell-fu ++ stripes ++ suggest ++ switch-window ++ swiper ++ swoop ++ sx ++ symbol-overlay ++ syslog-mode ++ table (built-in table.el) ++ telephone-line ++ 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 (=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: + +These do not require any extra styles because they are configured to +inherit from some basic faces. Please confirm. + ++ edit-indirect ++ evil-owl ++ i3wm-config-mode ++ perl-mode ++ php-mode ++ rjsx-mode ++ swift-mode + +** Will NOT be supported +:PROPERTIES: +:CUSTOM_ID: h:6c6e8d94-6782-47fc-9eef-ad78671e9eea +:END: + +I have thus far identified a single package that does fit into the +overarching objective of this project: [[https://github.com/hlissner/emacs-solaire-mode][solaire]]. It basically tries to +cast a less intense background on the main file-visiting buffers, so +that secondary elements like sidebars can have the default (pure +white/black) background. + +I will only cover this package if it ever supports the inverse effect: +less intense colors (but still accessible) for ancillary interfaces +and the intended styles for the content you are actually working on. + +* 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 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 uses 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 =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 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: =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 mechanism (=shr=) may need explicit configuration to +respect the theme's colors instead of whatever specifications the +webpage provides. Consult =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 +=helm-grep.el= library (view a library with =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= (=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 (see [[#h:9c3cd842-14b7-44d7-84b2-a5c8bc3fc3b1][Contributing]]). + +* 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: + +The =modus-operandi= and =modus-vivendi= themes are built into Emacs. +Currently they are in the project's =master= branch, 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 available as an extension to 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: + +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 would be great if your feedback also 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: +:ALT_TITLE: Merge requests +:DESCRIPTION: Legal considerations for code patches +: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?] + +Changed a couple of themes that are part of the Emacs source code: + +./etc/themes/modus-operandi-theme.el +./etc/themes/modus-vivendi-theme.el +#+end_example + +* Acknowledgements +:PROPERTIES: +:CUSTOM_ID: h:95c3da23-217f-404e-b5f3-56c75760ebcf +:END: + +The Modus themes are a collective effort. Every contribution counts. + ++ Author/maintainer :: Protesilaos Stavrou. + ++ Contributions to code or documentation :: Anders Johansson, Basil + L. Contovounesios, Eli Zaretskii, Madhavan Krishnan, Markus Beppler, + Matthew Stevenson, Shreyas Ragavan, Stefan Kangas, Vincent Murphy. + ++ Ideas and user feedback :: Aaron Jensen, Adam Spiers, Alex Griffin, + Alex Peitsinis, Alexey Shmalko, Anders Johansson, André Alexandre + Gomes, Arif Rezai, Basil L. Contovounesios, Damien Cassou, Dario + Gjorgjevski, David Edmondson, Davor Rotim, Divan Santana, Gerry + Agbobada, Gianluca Recchia, Ilja Kocken, Iris Garcia, Len Trigg, + Manuel Uberti, Mark Burton, Markus Beppler, Michael Goldenberg, Murilo + Pereira, Nicolas De Jaeghere, Paul Poloskov, Pierre Téchoueyres, Roman + Rudakov, Ryan Phillips, Shreyas Ragavan, Simon Pugnet, Tassilo Horn, + Thibaut Verron, Trey Merkley, Togan Muftuoglu, Uri Sharf, Utkarsh + Singh, Vincent Foley. As well as users: Ben, Eugene, Fourchaux, + Fredrik, Moesasji, Nick, TheBlob42, bepolymathe, dinko, doolio, + jixiuf, okamsn, tycho garen. + ++ Packaging :: Dhavan Vaidya (Debian), Stefan Kangas (core Emacs), + Stefan Monnier (GNU Elpa). + ++ Inspiration for certain features :: Bozhidar Batsov (zenburn-theme), + Fabrice Niessen (leuven-theme). + +* Meta +:PROPERTIES: +:CUSTOM_ID: h:13752581-4378-478c-af17-165b6e76bc1b +:END: + +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) + +And here are the canonical sources for this project's documentation: + ++ Manual :: ++ Change Log :: ++ Screenshots :: + +* External projects (ports) +:PROPERTIES: +:CUSTOM_ID: h:21adb7c8-2208-41e8-803c-052e42e2c05d +:END: + +The present section documents projects that extend the scope of the +Modus themes. The following list will be updated whenever relevant +information is brought to my attention. If you already have or intend +to produce such a port, feel welcome [[https://protesilaos.com/contact][to contact me]]. + ++ Modus exporter :: This is [[https://github.com/polaris64/modus-exporter][an Elisp library written by Simon Pugnet]]. + Licensed under the terms of the GNU General Public License. It is + meant to capture the color values of the active Modus theme (Operandi + or Vivendi) and output it as a valid theme for some other application. + +* GNU Free Documentation License +:PROPERTIES: +:APPENDIX: t +:CUSTOM_ID: h:3077c3d2-7f90-4228-8f0a-73124f4026f6 +:END: + +#+INCLUDE: fdl-1.3.txt src txt -- 2.39.2