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.
This commit is contained in:
Protesilaos Stavrou 2021-04-18 06:30:12 +03:00 committed by Stefan Kangas
parent 2822246b5d
commit dc9b0dc461
4 changed files with 1682 additions and 1160 deletions

View file

@ -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 @@ built on {{{export-date}}}.
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 FSFs Back-Cover Text is: “You have the freedom to copy and
modify this GNU manual.”
#+end_quote
* Overview
@ -141,7 +145,7 @@ The themes are now ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][
: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 @@ package configurations in their setup. We use this as an example:
: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 @@ Symbol: ~modus-themes-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 @@ Symbol: ~modus-themes-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 @@ Symbol: ~modus-themes-syntax~
Possible values:
1. =nil= (default)
1. ~nil~ (default)
2. ~faint~
3. ~yellow-comments~
4. ~green-strings~
@ -467,8 +472,8 @@ Symbol: ~modus-themes-no-mixed-fonts~
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 @@ This is to ensure that those constructs remain monospaced even when
users opt for a mode that remaps typeface families, such as the built-in
{{{kbd(M-x variable-pitch-mode)}}}. Otherwise the layout would appear
broken, due to how spacing is done. To disable this behaviour, set the
option to =t=.
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 @@ Symbol: ~modus-themes-links~
Possible values:
1. =nil= (default)
1. ~nil~ (default)
2. ~faint~
3. ~neutral-underline~
4. ~faint-neutral-underline~
@ -545,7 +550,7 @@ Symbol: ~modus-themes-prompts~
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 @@ Symbol: ~modus-themes-mode-line~
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 @@ that the inactive modelines remain visible, they apply a slightly more
prominent background to them than what their counterparts do (same
inactive background as with the default).
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 @@ is activated when Emacs determines that the background and foreground of
the given construct are too close to each other in terms of color
distance. In effect, users would need to experiment with the variable
~face-near-same-color-threshold~ to trigger the effect. We find that a
value of =45000= will suffice, contrary to the default =30000=. Do not set
the value too high, because that would have the adverse effect of always
overriding the default color (which has been carefully designed to be
highly accessible).
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 @@ Symbol: ~modus-themes-completions~
Possible values:
1. =nil= (default)
1. ~nil~ (default)
2. ~moderate~
3. ~opinionated~
@ -661,7 +675,7 @@ 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.
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 @@ 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~
some time with every one of the ~nil~ (default), ~moderate~, and ~opinionated~
possibilities.
** Option for fringe visibility
@ -692,7 +706,7 @@ Symbol: ~modus-themes-fringes~
Possible values:
1. =nil= (default)
1. ~nil~ (default)
2. ~subtle~
3. ~intense~
@ -716,7 +730,7 @@ Symbol: ~modus-themes-lang-checkers~
Possible values:
1. =nil= (default)
1. ~nil~ (default)
2. ~subtle-foreground~
3. ~intense-foreground~
4. ~straight-underline~
@ -755,25 +769,50 @@ refer to their documentation strings.
** Option for line highlighting (hl-line-mode)
:properties:
:alt_title: Line highlighting
:description: Toggle intense style for current line highlighting
: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 ~hl-line-mode~ and its
global equivalent.
The default is to use a subtle gray background for the current line when
~hl-line-mode~ is enabled.
With a non-nil value (=t=) use a more prominent background color instead.
The ~intense-background~ applies a more prominent gray to the background
of the current line.
This affects several packages that enable ~hl-line-mode~, such as =elfeed=
and =mu4e=.
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.
Similarly, the ~underline-accented~ renders the background of the current
line in a subtle colored background, while it also draws an accented
underline.
Option ~underline-only-neutral~ produces a neutral underline, but does not
use any background.
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 @@ Symbol: ~modus-themes-subtle-line-numbers~
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 @@ Similarly, the faces for ~display-line-numbers-major-tick~ and its
counterpart ~display-line-numbers-minor-tick~ use appropriate styles that
involve a bespoke background and foreground combination.
With a non-nil value (=t=), line numbers have no background of their own.
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 @@ Symbol: ~modus-themes-paren-match~
Possible values:
1. =nil= (default)
1. ~nil~ (default)
2. ~subtle-bold~
3. ~intense~
4. ~intense-bold~
@ -847,10 +886,12 @@ Symbol: ~modus-themes-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 @@ colors. It extends to the edge of the window.
Option ~bg-only-no-extend~ is a combination of the ~bg-only~ and ~no-extend~
options.
Option ~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 @@ Symbol: ~modus-themes-diffs~
Possible values:
1. =nil= (default)
1. ~nil~ (default)
2. ~desaturated~
3. ~fg-only~
4. ~bg-only~
@ -935,7 +981,7 @@ Symbol: ~modus-themes-org-blocks~
Possible values:
1. =nil= (default)
1. ~nil~ (default)
2. ~grayscale~
3. ~rainbow~
@ -960,6 +1006,9 @@ major-mode so that the colors are applied consistently throughout: use
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 @@ Symbol: ~modus-themes-org-habit~
Possible values:
1. =nil= (default)
1. ~nil~ (default)
2. ~simplified~
3. ~traffic-light~
@ -1014,11 +1063,10 @@ than other customization options documented in this manual.
Symbol: ~modus-themes-headings~
Possible values, which can be specified for each heading level (examples
further below):
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 @@ To set a uniform value for all heading levels, use this pattern:
'((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 @@ A description of all other possible styles beyond the default:
+ ~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 @@ Symbol: ~modus-themes-scale-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 @@ Symbol: ~modus-themes-variable-pitch-ui~
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 @@ and tab line.
The default is to use the same font as the rest of Emacs, which usually
is a monospaced family.
With a non-nil value (=t=) apply a proportionately spaced typeface. This
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 @@ Symbol: ~modus-themes-variable-pitch-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 @@ With that granted, let us expand the example to actually change the
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 @@ Getting a list of colors may have its applications, though what you are
most likely interested in is how to use those variables to configure
several faces at once. To do so we can rely on the built-in
~custom-set-faces~ function, which sets face specifications for the
special =user= theme. That "theme" gets applied on top of regular themes
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 @@ Thus:
[[#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 @@ the previous section. Adapt the above example like this:
...))
#+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 @@ with {{{kbd(M-x modus-themes-toggle)}}} will also use the overrides.
Given that this is a user-level customisation, one is free to implement
whatever color values they desire, even if the possible combinations
fall below the minimum 7:1 contrast ratio that governs the design of the
themes (the WCAG AAA legibility standard). Preferences aside, it is
advised to inspect the source code of ~modus-themes-operandi-colors~ and
~modus-themes-vivendi-colors~ to read the inline commentary: it explains
what the intended use of each palette subset is.
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 @@ reading the doc string of ~set-face-attribute~):
(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 @@ importance: it ensures that all fonts can scale gracefully when using
something like the ~text-scale-adjust~ command which only operates on the
base font size (i.e. the ~default~ face's absolute height).
[[#h:e6c5451f-6763-4be7-8fdb-b4706a422a4c][Note for EWW and Elfeed fonts (SHR fonts)]].
** Custom Org user faces (DIY)
:properties:
:custom_id: h:89f0678d-c5c3-4a57-a526-668b2bb2d7ad
@ -1871,6 +2059,68 @@ package:
(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 @@ have lots of extensions, so the "full support" may not be 100% true…
+ compilation-mode
+ completions
+ consult
+ corfu
+ counsel*
+ counsel-css
+ counsel-notmuch
@ -2018,8 +2269,9 @@ have lots of extensions, so the "full support" may not be 100% true…
+ eldoc-box
+ elfeed
+ elfeed-score
+ embark
+ emms
+ enhanced-ruby-mode
+ enh-ruby-mode (enhanced-ruby-mode)
+ epa
+ equake
+ erc
@ -2149,6 +2401,7 @@ have lots of extensions, so the "full support" may not be 100% true…
+ 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 @@ have lots of extensions, so the "full support" may not be 100% true…
+ 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 @@ have lots of extensions, so the "full support" may not be 100% true…
+ 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 @@ inherit from some basic faces. Please confirm.
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 @@ specifications the webpage provides.
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 @@ The Modus themes are a collective effort. Every bit of work matters.
+ 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 @@ And here are the canonical sources of this project's documentation:
#+texinfo: @include doclicense.texi
#+begin_export html
<pre>
GNU Free Documentation License
Version 1.3, 3 November 2008
@ -3270,6 +3582,7 @@ If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.
</pre>
#+end_export
#+html: <!--

View file

@ -4,7 +4,7 @@
;; Author: Protesilaos Stavrou <info@protesilaos.com>
;; URL: https://gitlab.com/protesilaos/modus-themes
;; Version: 1.2.3
;; Version: 1.3.2
;; Package-Requires: ((emacs "26.1"))
;; Keywords: faces, theme, accessibility
@ -52,6 +52,9 @@
(eval-and-compile
(unless (and (fboundp 'require-theme)
load-file-name
(equal (file-name-directory load-file-name)
(expand-file-name "themes/" data-directory))
(require-theme 'modus-themes t))
(require 'modus-themes)))

File diff suppressed because it is too large Load diff

View file

@ -4,7 +4,7 @@
;; Author: Protesilaos Stavrou <info@protesilaos.com>
;; URL: https://gitlab.com/protesilaos/modus-themes
;; Version: 1.2.3
;; Version: 1.3.2
;; Package-Requires: ((emacs "26.1"))
;; Keywords: faces, theme, accessibility
@ -52,6 +52,9 @@
(eval-and-compile
(unless (and (fboundp 'require-theme)
load-file-name
(equal (file-name-directory load-file-name)
(expand-file-name "themes/" data-directory))
(require-theme 'modus-themes t))
(require 'modus-themes)))