From e5fd00d268e60432097634ab3920a4917b206cd4 Mon Sep 17 00:00:00 2001 Message-Id: From: Protesilaos Stavrou Date: Sun, 18 Apr 2021 06:30:12 +0300 Subject: [PATCH] Update modus-themes to version 1.3.2 * doc/misc/modus-themes.org (COPYING): Reword to match the phrasing of other manuals that are distributed with Emacs. (Install from the archives) (Sample configuration for use-package) (Option for more bold constructs) (Option for more slanted constructs) (Option for syntax highlighting) (Option for no font mixing) (Option for links) (Option for command prompt styles) (Option for completion framework aesthetics) (Option for fringe visibility) (Option for language checkers) (Option for org-habit graph styles) (Option for line numbers (display-line-numbers-mode)) (Option for parenthesis matching (show-paren-mode)) (Option for diff buffer looks) (Option for scaled headings) (Option for variable-pitch font in UI elements) (Option for variable-pitch font in headings) (Case-by-case face specs using the themes' palette (DIY)) (Face specs at scale using the themes' palette (DIY)) (Font configurations for Org and others (DIY)) (Load theme depending on time of day): Minor markup changes for better texi output. (Option for mode line presentation): Document new possible values for 'modus-themes-mode-line'. (Option for line highlighting (hl-line-mode)): Document new 'modus-themes-hl-line' variable, which supersedes 'modus-themes-intense-hl-line'. (Option for active region): Document new possible values for 'modus-themes-region'. (Option for org-mode block styles): Cite variables that affect fontification. (Option for the headings' overall style): Include the option of a per-level nil value. (Remap face with local value (DIY)) (Override colors (DIY)): Add sections. (Full support for packages or face groups): Document newly supported packages (Note for dimmer.el) (Note for EWW and Elfeed fonts (SHR fonts)): Add notes. (Acknowledgements): Add names of new contributors. (GNU Free Documentation License): Add tags for html export. * etc/themes/modus-operandi-theme.el (File) * etc/themes/modus-vivendi-theme.el (File): Update to version 1.3.1 * etc/themes/modus-themes.el (modus-themes-operandi-colors) (modus-themes-vivendi-colors) (modus-theme-subtle-red) (modus-themes-subtle-red) (modus-theme-subtle-green) (modus-themes-subtle-green) (modus-theme-subtle-yellow) (modus-themes-subtle-yellow) (modus-theme-subtle-blue) (modus-themes-subtle-blue) (modus-theme-subtle-magenta) (modus-themes-subtle-magenta) (modus-theme-subtle-cyan) (modus-themes-subtle-cyan) (modus-theme-subtle-neutral) (modus-themes-subtle-neutral) (modus-theme-intense-red) (modus-themes-intense-red) (modus-theme-intense-green) (modus-themes-intense-green) (modus-theme-intense-yellow) (modus-themes-intense-yellow) (modus-theme-intense-blue) (modus-themes-intense-blue) (modus-theme-intense-magenta) (modus-themes-intense-magenta) (modus-theme-intense-cyan) (modus-themes-intense-cyan) (modus-theme-intense-neutral) (modus-themes-intense-neutral) (modus-theme-refine-red) (modus-themes-refine-red) (modus-theme-refine-green) (modus-themes-refine-green) (modus-theme-refine-yellow) (modus-themes-refine-yellow) (modus-theme-refine-blue) (modus-themes-refine-blue) (modus-theme-refine-magenta) (modus-themes-refine-magenta) (modus-theme-refine-cyan) (modus-themes-refine-cyan) (modus-theme-active-red) (modus-themes-active-red) (modus-theme-active-green) (modus-themes-active-green) (modus-theme-active-yellow) (modus-themes-active-yellow) (modus-theme-active-blue) (modus-themes-active-blue) (modus-theme-active-magenta) (modus-themes-active-magenta) (modus-theme-active-cyan) (modus-themes-active-cyan) (modus-theme-fringe-red) (modus-themes-fringe-red) (modus-theme-fringe-green) (modus-themes-fringe-green) (modus-theme-fringe-yellow) (modus-themes-fringe-yellow) (modus-theme-fringe-blue) (modus-themes-fringe-blue) (modus-theme-fringe-magenta) (modus-themes-fringe-magenta) (modus-theme-fringe-cyan) (modus-themes-fringe-cyan) (modus-theme-nuanced-red) (modus-theme-nuanced-green) (modus-theme-nuanced-yellow) (modus-theme-nuanced-blue) (modus-theme-nuanced-magenta) (modus-theme-nuanced-cyan) (modus-theme-special-cold) (modus-theme-special-mild) (modus-theme-special-warm) (modus-theme-special-calm) (modus-theme-diff-added) (modus-theme-diff-changed) (modus-theme-diff-removed) (modus-theme-diff-refine-added) (modus-theme-diff-refine-changed) (modus-theme-diff-refine-removed) (modus-theme-diff-focus-added) (modus-theme-diff-focus-changed) (modus-theme-diff-focus-removed) (modus-theme-diff-heading) (modus-theme-pseudo-header) (modus-theme-mark-alt) (modus-theme-mark-del) (modus-theme-mark-sel) (modus-theme-mark-symbol) (modus-theme-heading-1) (modus-theme-heading-2) (modus-theme-heading-3) (modus-theme-heading-4) (modus-theme-heading-5) (modus-theme-heading-6) (modus-theme-heading-7) (modus-theme-heading-8) (modus-theme-hl-line) (modus-theme-bold) (modus-theme-slant) (modus-theme-variable-pitch) (modus-theme-graph-red-0) (modus-theme-graph-red-1) (modus-theme-graph-green-0) (modus-theme-graph-green-1) (modus-theme-graph-yellow-0) (modus-theme-graph-yellow-1) (modus-theme-graph-blue-0) (modus-theme-graph-blue-1) (modus-theme-graph-magenta-0) (modus-theme-graph-magenta-1) (modus-theme-graph-cyan-0) (modus-theme-graph-cyan-1) (modus-theme-lang-note) (modus-theme-lang-warning) (modus-theme-lang-error): Rename all internal faces. (modus-themes-headings) (modus-themes-fringes) (modus-themes-lang-checkers) (modus-themes-org-blocks) (modus-themes-org-habit) (modus-themes-mode-line) (modus-themes-diffs) (modus-themes-completions) (modus-themes-prompts) (modus-themes-intense-hl-line) (modus-themes-hl-line) (modus-themes-paren-match) (modus-themes-syntax) (modus-themes-links) (modus-themes-region): Update defcustom. (modus-themes--fringe): (modus-themes--headings-choice): (modus-themes--prompt): (modus-themes--org-block-delim): (modus-themes--mode-line-attrs): (modus-themes--link): (modus-themes--region): (modus-themes--hl-line): Adjustments to internal functions. (modus-themes-faces): Update faces. (modus-themes-custom-variables): Update custom variables. --- doc/misc/modus-themes.org | 499 ++++-- etc/themes/modus-operandi-theme.el | 5 +- etc/themes/modus-themes.el | 2333 +++++++++++++++------------- etc/themes/modus-vivendi-theme.el | 5 +- 4 files changed, 1682 insertions(+), 1160 deletions(-) diff --git a/doc/misc/modus-themes.org b/doc/misc/modus-themes.org index 9764a3467f..001ed57218 100644 --- a/doc/misc/modus-themes.org +++ b/doc/misc/modus-themes.org @@ -4,9 +4,9 @@ #+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: stable-version 1.3.2 +#+macro: release-date 2021-04-18 +#+macro: development-version 1.4.0-dev #+macro: export-date (eval (format-time-string "%F %R %z" (current-time))) #+macro: file @@texinfo:@file{@@$1@@texinfo:}@@ #+macro: space @@texinfo:@: @@ @@ -46,11 +46,15 @@ * COPYING 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. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and +with the Back-Cover Texts as in (a) below. A copy of the license is +included in the section entitled “GNU Free Documentation License.” + +(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and +modify this GNU manual.” #+end_quote * Overview @@ -141,7 +145,7 @@ ** Install from the archives :custom_id: h:c4b10085-149f-43e2-bd4d-347f33aee054 :end: -The =modus-themes= package is available from the GNU ELPA archive, which +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 @@ -287,7 +291,8 @@ ** Sample configuration for use-package :init ;; Add all your customizations prior to loading the themes (setq modus-themes-slanted-constructs t - modus-themes-bold-constructs nil) + modus-themes-bold-constructs nil + modus-themes-region 'no-extend) ;; Load the theme files before enabling a theme (else you get an error). (modus-themes-load-themes) @@ -374,13 +379,13 @@ ** Option for more bold constructs Possible values: -1. =nil= (default) -2. =t= +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 +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. @@ -397,13 +402,13 @@ ** Option for more slanted constructs Possible values: -1. =nil= (default) -2. =t= +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. +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 @@ -418,7 +423,7 @@ ** Option for syntax highlighting Possible values: -1. =nil= (default) +1. ~nil~ (default) 2. ~faint~ 3. ~yellow-comments~ 4. ~green-strings~ @@ -467,8 +472,8 @@ ** Option for no font mixing Possible values: -1. =nil= (default) -2. =t= +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. @@ -476,14 +481,14 @@ ** Option for no font mixing 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=. +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)]]. +[[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. ** Option for links :properties: @@ -497,7 +502,7 @@ ** Option for links Possible values: -1. =nil= (default) +1. ~nil~ (default) 2. ~faint~ 3. ~neutral-underline~ 4. ~faint-neutral-underline~ @@ -545,7 +550,7 @@ ** Option for command prompt styles Possible values: -1. =nil= (default) +1. ~nil~ (default) 2. ~subtle-accented~ (~subtle~ exists for backward compatibility) 3. ~intense-accented~ (~intense~ exists for backward compatibility) 4. ~subtle-gray~ @@ -577,12 +582,15 @@ ** Option for mode line presentation Possible values: -1. =nil= (default) +1. ~nil~ (default) 2. ~3d~ 3. ~moody~ 4. ~borderless~ 5. ~borderless-3d~ 6. ~borderless-moody~ +7. ~accented~ +8. ~accented-3d~ +9. ~accented-moody~ The default produces a two-dimensional effect both for the active and inactive modelines. The differences between the two are limited to @@ -612,6 +620,11 @@ ** Option for mode line presentation prominent background to them than what their counterparts do (same inactive background as with the default). +Similarly, ~accented~, ~accented-3d~, and ~accented-moody~ correspond to the +default (~nil~), ~3d~, and ~moody~ styles respectively, except that the active +mode line uses a colored background instead of the standard shade of +gray. + 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 @@ -624,10 +637,11 @@ ** Option for mode line presentation 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). +value of =45000= will suffice, contrary to the default =30000=. Though for +the ~accented-moody~ value mentioned above, that should be raised up to +=70000=. Do not set it too high, because it has the adverse effect of +always overriding the default colors (which have been carefully designed +to be highly accessible). Furthermore, because Moody expects an underline and overline instead of a box style, it is advised you include this in your setup: @@ -648,7 +662,7 @@ ** Option for completion framework aesthetics Possible values: -1. =nil= (default) +1. ~nil~ (default) 2. ~moderate~ 3. ~opinionated~ @@ -661,7 +675,7 @@ ** Option for completion framework aesthetics 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. +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 @@ -677,7 +691,7 @@ ** Option for completion framework aesthetics 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~ +some time with every one of the ~nil~ (default), ~moderate~, and ~opinionated~ possibilities. ** Option for fringe visibility @@ -692,7 +706,7 @@ ** Option for fringe visibility Possible values: -1. =nil= (default) +1. ~nil~ (default) 2. ~subtle~ 3. ~intense~ @@ -716,7 +730,7 @@ ** Option for language checkers Possible values: -1. =nil= (default) +1. ~nil~ (default) 2. ~subtle-foreground~ 3. ~intense-foreground~ 4. ~straight-underline~ @@ -755,25 +769,50 @@ ** Option for language checkers ** Option for line highlighting (hl-line-mode) :properties: :alt_title: Line highlighting -:description: Toggle intense style for current line highlighting +:description: Choose style of current line (hl-line-mode) :custom_id: h:1dba1cfe-d079-4c13-a810-f768e8789177 :end: -#+vindex: modus-themes-intense-hl-line +#+vindex: modus-themes-hl-line -Symbol: ~modus-themes-intense-hl-line~ +Symbol: ~modus-themes-hl-line~ Possible values: -1. =nil= (default) -2. =t= +1. ~nil~ (default) +2. ~intense-background~ +3. ~accented-background~ +4. ~underline-neutral~ +5. ~underline-accented~ +6. ~underline-only-neutral~ +7. ~underline-only-accented~ + +The default is to use a subtle gray background for the current line when +~hl-line-mode~ is enabled. + +The ~intense-background~ applies a more prominent gray to the background +of the current line. + +With ~accented-background~ the default's subtle aesthetic is retained, but +the background has a more colored hint. + +The ~underline-neutral~ combines the default subtle neutral background +with a gray underline. -The default is to use a subtle gray background for ~hl-line-mode~ and its -global equivalent. +Similarly, the ~underline-accented~ renders the background of the current +line in a subtle colored background, while it also draws an accented +underline. -With a non-nil value (=t=) use a more prominent background color instead. +Option ~underline-only-neutral~ produces a neutral underline, but does not +use any background. -This affects several packages that enable ~hl-line-mode~, such as =elfeed= -and =mu4e=. +While ~underline-only-accented~ also uses just an underline, only this one +is colored. + +Consider setting the variable ~x-underline-at-descent-line~ to a non-nil +value for better results with underlines. + +This style affects several packages that enable ~hl-line-mode~, such as +=elfeed= and =mu4e=. ** Option for line numbers (display-line-numbers-mode) :properties: @@ -787,8 +826,8 @@ ** Option for line numbers (display-line-numbers-mode) Possible value: -1. =nil= (default) -2. =t= +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 @@ -799,7 +838,7 @@ ** Option for line numbers (display-line-numbers-mode) 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. +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. @@ -816,7 +855,7 @@ ** Option for parenthesis matching (show-paren-mode) Possible values: -1. =nil= (default) +1. ~nil~ (default) 2. ~subtle-bold~ 3. ~intense~ 4. ~intense-bold~ @@ -847,10 +886,12 @@ ** Option for active region Possible values: -1. =nil= (default) +1. ~nil~ (default) 2. ~no-extend~ 3. ~bg-only~ 4. ~bg-only-no-extend~ +5. ~accent~ +6. ~accent-no-extend~ Nil means to only use a prominent gray background with a neutral foreground. The foreground overrides all syntax highlighting. The @@ -866,6 +907,11 @@ ** Option for active region Option ~bg-only-no-extend~ is a combination of the ~bg-only~ and ~no-extend~ options. +Option ~accent~ is like the default, though it uses a more colorful +background, while ~accent-no-extend~ is the same except it draws the +region only up to the end of each line instead of extending to the edge +of the window. + ** Option for diff buffer looks :properties: :alt_title: Diffs @@ -878,7 +924,7 @@ ** Option for diff buffer looks Possible values: -1. =nil= (default) +1. ~nil~ (default) 2. ~desaturated~ 3. ~fg-only~ 4. ~bg-only~ @@ -935,7 +981,7 @@ ** Option for org-mode block styles Possible values: -1. =nil= (default) +1. ~nil~ (default) 2. ~grayscale~ 3. ~rainbow~ @@ -960,6 +1006,9 @@ ** Option for org-mode block styles Or start typing in each code block (inefficient at scale, but it still works). +The extent of Org block delimiter lines is controlled by the variable +~org-fontify-whole-block-delimiter-line~. + ** Option for org-habit graph styles :properties: :alt_title: Org agenda habits @@ -972,7 +1021,7 @@ ** Option for org-habit graph styles Possible values: -1. =nil= (default) +1. ~nil~ (default) 2. ~simplified~ 3. ~traffic-light~ @@ -1014,11 +1063,10 @@ ** Option for the headings' overall style Symbol: ~modus-themes-headings~ -Possible values, which can be specified for each heading level (examples -further below): +Possible values, which can be specified for each heading level N +(examples further below): -+ nil (default fallback option---covers all heading levels) -+ =t= (default style for a single heading, when the fallback differs) ++ ~nil~ (~t~ is also available for backward compatibility) + ~no-bold~ + ~line~ + ~line-no-bold~ @@ -1058,19 +1106,19 @@ ** Option for the headings' overall style '((t . section))) ;; Default aesthetic for every heading -(setq modus-themes-headings - '()) +(setq modus-themes-headings nil) #+end_src The default style for headings uses a fairly desaturated foreground -value in combination with bold typographic weight. To specify this +color 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: +option, just assign the value ~nil~ like this: #+begin_src emacs-lisp (setq modus-themes-headings - '((1 . t) + '((1 . nil) (2 . line) + (3) ; same as nil (t . rainbow-line-no-bold))) #+end_src @@ -1122,6 +1170,9 @@ ** Option for the headings' overall style + ~no-color-no-bold~ is like ~no-color~ but without the bold weight. +Remember to also inspect relevant variables that Org provides, such as: +~org-fontify-whole-heading-line~ and ~org-fontify-done-headline~. + ** Option for scaled headings :properties: :alt_title: Scaled headings @@ -1134,12 +1185,12 @@ ** Option for scaled headings Possible values: -1. =nil= (default) -2. =t= +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 +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 @@ -1217,8 +1268,8 @@ ** Option for variable-pitch font in UI elements Possible values: -1. =nil= (default) -2. =t= +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, @@ -1227,7 +1278,7 @@ ** Option for variable-pitch font in UI elements 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 +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]]. @@ -1244,13 +1295,13 @@ ** Option for variable-pitch font in headings Possible values: -1. =nil= (default) -2. =t= +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 +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]]. @@ -1357,7 +1408,7 @@ ** Case-by-case face specs using the themes' palette (DIY) 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= +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 @@ -1458,7 +1509,7 @@ ** Face specs at scale using the themes' palette (DIY) 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 +special ~user~ theme. That "theme" gets applied on top of regular themes like ~modus-operandi~ and ~modus-vivendi~. This is how it works: @@ -1502,7 +1553,7 @@ ** Face specs at scale using the themes' palette (DIY) [[#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 +{{{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). @@ -1524,6 +1575,68 @@ ** Face specs at scale using the themes' palette (DIY) ...)) #+end_src +** Remap face with local value (DIY) +:properties: +:custom_id: h:7a93cb6f-4eca-4d56-a85c-9dcd813d6b0f +:end: +#+cindex: Remapping faces + +There are cases where we need to change the buffer-local attributes of a +face. This might be because we have our own minor mode that re-uses a +face for a particular purpose, such as a line selection tool that +activates ~hl-line-mode~, but we wish to keep it distinct from other +buffers. This is where ~face-remap-add-relative~ can be applied and may +be combined with ~modus-themes-with-colors~ to deliver consistent results. + +[[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette (DIY)]]. + +In this example we will write a simple interactive function that adjusts +the background color of the ~region~ face. This is the sample code: + +#+begin_src emacs-lisp +(defvar my-rainbow-region-colors + (modus-themes-with-colors + `((red . ,red-subtle-bg) + (green . ,green-subtle-bg) + (yellow . ,yellow-subtle-bg) + (blue . ,blue-subtle-bg) + (magenta . ,magenta-subtle-bg) + (cyan . ,cyan-subtle-bg))) + "Sample list of color values for `my-rainbow-region'.") + +(defun my-rainbow-region (color) + "Remap buffer-local attribute of `region' using COLOR." + (interactive + (list + (completing-read "Pick a color: " my-rainbow-region-colors))) + (face-remap-add-relative + 'region + `( :background ,(alist-get (intern color) my-rainbow-region-colors) + :foreground ,(face-attribute 'default :foreground)))) +#+end_src + +When ~my-rainbow-region~ is called interactively, it prompts for a color +to use. The list of candidates is drawn from the car of each +association in ~my-rainbow-region-colors~ (so "red", "green", etc.). + +To extend this principle, we may write wrapper functions that pass a +color directly. Those can be useful in tandem with hooks. Consider +this example: + +#+begin_src emacs-lisp +(defun my-rainbow-region-magenta () + (my-rainbow-region 'magenta)) + +(add-hook 'diff-mode-hook #'my-rainbow-region-magenta) +#+end_src + +Whenever we enter a ~diff-mode~ buffer, we now get a magenta-colored +region. + +Perhaps you may wish to generalise those findings in to a set of +functions that also accept an arbitrary face. We shall leave the +experimentation up to you. + ** Override colors (DIY) :properties: :custom_id: h:307d95dd-8dbd-4ece-a543-10ae86f155a6 @@ -1627,16 +1740,89 @@ ** Override colors (DIY) 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. +themes (the WCAG AAA legibility standard). Alternatively, this can also +be done programmatically ([[#h:4589acdc-2505-41fc-9f5e-699cfc45ab00][Override color saturation]]). + +For manual interventions it is advised to inspect the source code of +~modus-themes-operandi-colors~ and ~modus-themes-vivendi-colors~ for the +inline commentary: it explains what the intended use of each palette +subset is. Furthermore, users may benefit from the ~modus-themes-contrast~ function that we provide: [[#h:02e25930-e71a-493d-828a-8907fc80f874][test color combinations]]. It measures the contrast ratio between two color values, so it can help in overriding the palette (or a subset thereof) without making the end result inaccessible. +** Override color saturation (DIY) +:properties: +:custom_id: h:4589acdc-2505-41fc-9f5e-699cfc45ab00 +:end: +#+cindex: Change a theme's color saturation + +In the previous section we documented how one can override color values +manually ([[#h:307d95dd-8dbd-4ece-a543-10ae86f155a6][Override colors]]). Here we use a programmatic approach which +leverages the built-in ~color-saturate-name~ function to adjust the +saturation of all color values used by the active Modus theme. Our goal +is to prepare a counterpart of the active theme's palette that holds +modified color values, adjusted for a percent change in saturation. A +positive number amplifies the effect, while a negative one will move +towards a grayscale spectrum. + +We start with a function that can be either called from Lisp or invoked +interactively. In the former scenario, we pass to it the rate of change +we want. While in the latter, a minibuffer prompt asks for a number to +apply the desired effect. In either case, we intend to assign anew the +value of ~modus-themes-operandi-color-overrides~ (light theme) and the +same for ~modus-themes-vivendi-color-overrides~ (dark theme). + +#+begin_src emacs-lisp +(defun my-modus-themes-saturate (percent) + "Saturate current Modus theme palette overrides by PERCENT." + (interactive + (list (read-number "Saturation by percent: "))) + (let* ((theme (modus-themes--current-theme)) + (palette (pcase theme + ('modus-operandi modus-themes-operandi-colors) + ('modus-vivendi modus-themes-vivendi-colors) + (_ (error "No Modus theme is active")))) + (overrides (pcase theme + ('modus-operandi 'modus-themes-operandi-color-overrides) + ('modus-vivendi 'modus-themes-vivendi-color-overrides) + (_ (error "No Modus theme is active"))))) + (let (name cons colors) + (dolist (cons palette) + (setq name (color-saturate-name (cdr cons) percent)) + (setq name (format "%s" name)) + (setq cons `(,(car cons) . ,name)) + (push cons colors)) + (set overrides colors)) + (pcase theme + ('modus-operandi (modus-themes-load-operandi)) + ('modus-vivendi (modus-themes-load-vivendi))))) + +;; sample Elisp calls (or call `my-modus-themes-saturate' interactively) +(my-modus-themes-saturate 50) +(my-modus-themes-saturate -75) +#+end_src + +Using the above has an immediate effect, as it reloads the active Modus +theme. + +To disable the effect, one must reset the aforementioned variables to +~nil~. Or specify a command for it, such as by taking inspiration from +the ~modus-themes-toggle~ we already provide: + +#+begin_src emacs-lisp +(defun my-modus-themes-revert-overrides () + "Reset palette overrides and reload active Modus theme." + (interactive) + (setq modus-themes-operandi-color-overrides nil + modus-themes-vivendi-color-overrides nil) + (pcase (modus-themes--current-theme) + ('modus-operandi (modus-themes-load-operandi)) + ('modus-vivendi (modus-themes-load-vivendi)))) +#+end_src + ** Font configurations for Org and others (DIY) :properties: :custom_id: h:defcf4fc-8fa8-4c29-b12e-7119582cc929 @@ -1677,9 +1863,9 @@ ** Font configurations for Org and others (DIY) (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 +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= +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 @@ -1689,6 +1875,8 @@ ** Font configurations for Org and others (DIY) something like the ~text-scale-adjust~ command which only operates on the base font size (i.e. the ~default~ face's absolute height). +[[#h:e6c5451f-6763-4be7-8fdb-b4706a422a4c][Note for EWW and Elfeed fonts (SHR fonts)]]. + ** Custom Org user faces (DIY) :properties: :custom_id: h:89f0678d-c5c3-4a57-a526-668b2bb2d7ad @@ -1871,6 +2059,68 @@ ** Load theme depending on time of day (circadian-setup)) #+end_src +** Backdrop for pdf-tools (DIY) +:properties: +:custom_id: h:ff69dfe1-29c0-447a-915c-b5ff7c5509cd +:end: +#+cindex: Remapping pdf-tools backdrop + +Most PDF files use a white background for their page, making it +impossible to discern the file's boundaries in the buffer while using +the Modus Operandi theme. To introduce a distinction between the +buffer's backdrop and the PDF page's background, the former must be +rendered as some shade of gray. Ideally, ~pdf-tools~ would provide a face +that the themes could support directly, though this does not seem to be +the case for the time being. We must thus employ the face remapping +technique that is documented elsewhere in this document to change the +buffer-local value of the ~default~ face. + +[[#h:7a93cb6f-4eca-4d56-a85c-9dcd813d6b0f][Remap face with local value (DIY)]]. + +To remap the buffer's backdrop, we start with a function like this one: + +#+begin_src emacs-lisp +(defun my-pdf-tools-backdrop () + (face-remap-add-relative + 'default + `(:background ,(modus-themes-color 'bg-alt)))) + +(add-hook 'pdf-tools-enabled-hook #'my-pdf-tools-backdrop) +#+end_src + +The idea is to assign that function to a hook that gets called when +~pdf-tools~ renders the document: ~pdf-tools-enabled-hook~. This is enough +when you only use one theme. However it has the downside of setting the +background color value only at render time. In other words, the face +remapping function does not get evaluated anew whenever the theme +changes, such as upon invoking {{{kbd(M-x modus-themes-toggle)}}}. + +To have our face remapping adapt gracefully while switching between the +Modus themes, we need to also account for the current theme and control +the activation of ~pdf-view-midnight-minor-mode~. To which end we arrive +at something like the following, which builds on the above example: + +#+begin_src emacs-lisp +(defun my-pdf-tools-backdrop () + (face-remap-add-relative + 'default + `(:background ,(modus-themes-color 'bg-alt)))) + +(defun my-pdf-tools-midnight-mode-toggle () + (when (derived-mode-p 'pdf-view-mode) + (if (eq (car custom-enabled-themes) 'modus-vivendi) + (pdf-view-midnight-minor-mode 1) + (pdf-view-midnight-minor-mode -1)) + (my-pdf-tools-backdrop))) + +(add-hook 'pdf-tools-enabled-hook #'my-pdf-tools-midnight-mode-toggle) +(add-hook 'modus-themes-after-load-theme-hook #'my-pdf-tools-midnight-mode-toggle) +#+end_src + +With those in place, PDFs have a distinct backdrop for their page, while +they automatically switch to their dark mode when ~modus-themes-toggle~ is +called from inside a buffer whose major-mode is ~pdf-view-mode~. + ** A theme-agnostic hook for theme loading (DIY) :properties: :custom_id: h:86f6906b-f090-46cc-9816-1fe8aeb38776 @@ -1976,6 +2226,7 @@ ** Full support for packages or face groups + compilation-mode + completions + consult ++ corfu + counsel* + counsel-css + counsel-notmuch @@ -2018,8 +2269,9 @@ ** Full support for packages or face groups + eldoc-box + elfeed + elfeed-score ++ embark + emms -+ enhanced-ruby-mode ++ enh-ruby-mode (enhanced-ruby-mode) + epa + equake + erc @@ -2149,6 +2401,7 @@ ** Full support for packages or face groups + outline-minor-faces + package (what you get with {{{kbd(M-x list-packages)}}}) + page-break-lines ++ pandoc-mode + paradox + paren-face + parrot @@ -2206,7 +2459,11 @@ ** Full support for packages or face groups + sx + symbol-overlay + syslog-mode ++ tab-bar-groups ++ tab-bar-mode ++ tab-line-mode + table (built-in table.el) ++ telega + telephone-line + terraform-mode + term @@ -2221,6 +2478,7 @@ ** Full support for packages or face groups + vc (built-in mode line status for version control) + vc-annotate (the out put of {{{kbd(C-x v g)}}}) + vdiff ++ vertico + vimish-fold + visible-mark + visual-regexp @@ -2274,6 +2532,42 @@ * Notes for individual packages This section covers information that may be of interest to users of individual packages. +** Note for dimmer.el +:properties: +:custom_id: h:8eb4b758-d318-4480-9ead-357a571beb93 +:end: + +The {{{file(dimmer.el)}}} library by Neil Okamoto can be configured to +automatically dim the colors of inactive Emacs windows. To guarantee +consistent results with the Modus themes, we suggest some tweaks to the +default styles, such as in this minimal setup: + +#+begin_src emacs-lisp +(use-package dimmer + :config + (setq dimmer-fraction 0.3) + (setq dimmer-adjustment-mode :foreground) + (setq dimmer-use-colorspace :rgb) + + (dimmer-mode 1)) +#+end_src + +Of the above, we strongly recommend the RGB color space because it is +the one that remains faithful to the hueness of the colors used by the +themes. Whereas the default CIELAB space has a tendency to distort +colors in addition to applying the dim effect, which can be somewhat +disorienting. + +The value of the ~dimmer-fraction~ has been selected empirically. Users +might prefer to tweak it further (increasing it makes the dim effect +more pronounced). + +Changing the ~dimmer-adjustment-mode~ is a matter of preference. Though +because the Modus themes use black and white as their base colors, any +other value for that variable will turn the main background gray. This +inadvertently leads to the opposite of the intended utility of this +package: it draws too much attention to unfocused windows. + ** Note for display-fill-column-indicator-mode :properties: :custom_id: h:2a602816-bc1b-45bf-9675-4cbbd7bf6cab @@ -2521,6 +2815,21 @@ ** Note on SHR colors Consult {{{kbd(C-h v shr-use-colors)}}}. + +** Note for EWW and Elfeed fonts (SHR fonts) +:properties: +:custom_id: h:e6c5451f-6763-4be7-8fdb-b4706a422a4c +:end: + +EWW and Elfeed rely on the Simple HTML Renderer to display their +content. The {{{file(shr.el)}}} library contains the variable ~shr-use-fonts~ +that controls whether the text in the buffer is set to a ~variable-pitch~ +typeface (proportionately spaced) or if just retains whatever the +default font family is. Its default value is non-nil, which means that +~variable-pitch~ is applied. + +[[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. + ** Note for Helm grep :properties: :custom_id: h:d28879a2-8e4b-4525-986e-14c0f873d229 @@ -2748,26 +3057,28 @@ * Acknowledgements + 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. + Ninev, Madhavan Krishnan, Markus Beppler, Matthew Stevenson, Mauro + Aranda, 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. + Davor Rotim, Divan Santana, Emanuele Michele Alberto Monterosso, + Farasha Euker, Gerry Agbobada, Gianluca Recchia, Gustavo Barros, + Hörmetjan Yiltiz, Ilja Kocken, Iris Garcia, Jeremy Friesen, John + Haman, Joshua O'Connor, Kevin Fleming, Kévin Le Gouguec, Kostadin + Ninev, Len Trigg, Manuel Uberti, Mark Burton, Markus Beppler, Mauro + Aranda, Michael Goldenberg, Morgan Smith, Murilo Pereira, Nicky van + Foreest, Nicolas De Jaeghere, Paul Poloskov, 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, Trey, + bepolymathe, doolio, fleimgruber, iSeeU, jixiuf, okamsn, pRot0ta1p. + Packaging :: Basil L.{{{space()}}} Contovounesios, Eli Zaretskii, Glenn Morris, Mauro Aranda, Richard Stallman, Stefan Kangas (core Emacs), @@ -2819,6 +3130,7 @@ * GNU Free Documentation License #+texinfo: @include doclicense.texi #+begin_export html +
 
                 GNU Free Documentation License
                  Version 1.3, 3 November 2008
@@ -3270,6 +3582,7 @@ * GNU Free Documentation License
 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: