aboutsummaryrefslogtreecommitdiffstats
path: root/doc/misc
diff options
context:
space:
mode:
authorProtesilaos Stavrou2023-05-30 09:37:24 +0300
committerProtesilaos Stavrou2023-05-30 09:37:24 +0300
commitcb1ee63e2aea573d67e2d495d6b5937a15bc0368 (patch)
tree74b51ff2bb5a768689ed1a8c73f0c1b9d005b32a /doc/misc
parent31a80f61ec03bcbb79720c0dc640272aba160865 (diff)
downloademacs-cb1ee63e2aea573d67e2d495d6b5937a15bc0368.tar.gz
emacs-cb1ee63e2aea573d67e2d495d6b5937a15bc0368.zip
Update modus-themes to their version 4.2.0
* doc/misc/modus-themes.org: Update the manual. * etc/themes/modus-operandi-tritanopia-theme.el: * etc/themes/modus-vivendi-tritanopia-theme.el: Add new themes optimized for users with blue-yellow color deficiency (tritanopia). * etc/themes/modus-operandi-deuteranopia-theme.el: * etc/themes/modus-operandi-theme.el: * etc/themes/modus-operandi-tinted-theme.el: * etc/themes/modus-vivendi-deuteranopia-theme.el: * etc/themes/modus-vivendi-theme.el: * etc/themes/modus-vivendi-tinted-theme.el: Update theme files. * etc/themes/modus-themes.el: Update main file to the latest version. * etc/NEWS: Rephrase the announcement about the new Modus themes to also mention the tritanopia-optimized items. Detailed release notes here: <https://protesilaos.com/codelog/2023-05-30-modus-themes-4-2-0/>.
Diffstat (limited to 'doc/misc')
-rw-r--r--doc/misc/modus-themes.org400
1 files changed, 321 insertions, 79 deletions
diff --git a/doc/misc/modus-themes.org b/doc/misc/modus-themes.org
index 47d3e6c03e3..7809bd03918 100644
--- a/doc/misc/modus-themes.org
+++ b/doc/misc/modus-themes.org
@@ -4,9 +4,9 @@
4#+language: en 4#+language: en
5#+options: ':t toc:nil author:t email:t num:t 5#+options: ':t toc:nil author:t email:t num:t
6#+startup: content 6#+startup: content
7#+macro: stable-version 4.1.0 7#+macro: stable-version 4.2.0
8#+macro: release-date 2023-02-22 8#+macro: release-date 2023-05-30
9#+macro: development-version 4.2.0-dev 9#+macro: development-version 4.3.0-dev
10#+macro: file @@texinfo:@file{@@$1@@texinfo:}@@ 10#+macro: file @@texinfo:@file{@@$1@@texinfo:}@@
11#+macro: space @@texinfo:@: @@ 11#+macro: space @@texinfo:@: @@
12#+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@ 12#+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@
@@ -77,7 +77,7 @@ combinations of background and foreground values. For small sized
77text, this corresponds to the WCAG AAA standard, which specifies a 77text, this corresponds to the WCAG AAA standard, which specifies a
78minimum rate of distance in relative luminance of 7:1. 78minimum rate of distance in relative luminance of 7:1.
79 79
80The Modus themes consist of six themes, divided into three subgroups. 80The Modus themes consist of eight themes, divided into four subgroups.
81 81
82- Main themes :: ~modus-operandi~ is the project's main light theme, 82- Main themes :: ~modus-operandi~ is the project's main light theme,
83 while ~modus-vivendi~ is its dark counterpart. These two themes are 83 while ~modus-vivendi~ is its dark counterpart. These two themes are
@@ -101,15 +101,23 @@ The Modus themes consist of six themes, divided into three subgroups.
101 users with deueteranopia or deuteranomaly (mostly yellow and blue 101 users with deueteranopia or deuteranomaly (mostly yellow and blue
102 hues). 102 hues).
103 103
104- Tritanopia themes :: ~modus-operandi-tritanopia~ and its counterpart
105 ~modus-vivendi-tritanopia~ are optimized for users with blue-yellow
106 color deficiency. The idea is the same as with the deuteranopia
107 variants: color coding relies only on hues that are accessible to
108 people with tritanopia or tritanomaly, namely, shades of red and
109 cyan.
110
104To ensure that users have a consistently accessible experience, the 111To ensure that users have a consistently accessible experience, the
105themes strive to achieve as close to full face coverage as possible, 112themes strive to achieve as close to full face coverage as possible,
106while still targeting a curated list of well-maintained packages 113while still targeting a curated list of well-maintained packages
107([[#h:a9c8f29d-7f72-4b54-b74b-ddefe15d6a19][Face coverage]]). 114([[#h:a9c8f29d-7f72-4b54-b74b-ddefe15d6a19][Face coverage]]).
108 115
109The overarching objective of this project is to always offer accessible 116The overarching objective of this project is to always offer
110color combinations. There shall never be a compromise on this 117accessible color combinations. There shall never be a compromise on
111principle. If there arises an inescapable trade-off between readability 118this principle. If there arises an inescapable trade-off between
112and stylistic considerations, we will always opt for the former. 119usability and stylistic considerations, we will always opt for the
120former.
113 121
114Starting with version 0.12.0 and onwards, the themes are built into GNU 122Starting with version 0.12.0 and onwards, the themes are built into GNU
115Emacs. 123Emacs.
@@ -441,6 +449,8 @@ will lead to failures in loading the files. If either or both of those
441variables need to be changed, their values should be defined before the 449variables need to be changed, their values should be defined before the
442package declaration of the themes. 450package declaration of the themes.
443 451
452[[#h:aabcada6-810d-4eee-b34a-d2a9c301824d][Make the themes look like what the maintainer uses]]
453
444** Differences between loading and enabling 454** Differences between loading and enabling
445:properties: 455:properties:
446:custom_id: h:e68560b3-7fb0-42bc-a151-e015948f8a35 456:custom_id: h:e68560b3-7fb0-42bc-a151-e015948f8a35
@@ -1066,6 +1076,9 @@ palette variable is =THEME-NAME-palette-overrides=, thus yielding:
1066#+vindex: modus-operandi-tinted-palette-overrides 1076#+vindex: modus-operandi-tinted-palette-overrides
1067+ ~modus-operandi-tinted-palette-overrides~ 1077+ ~modus-operandi-tinted-palette-overrides~
1068 1078
1079#+vindex: modus-operandi-tritanopia-palette-overrides
1080+ ~modus-operandi-tritanopia-palette-overrides~
1081
1069#+vindex: modus-vivendi-palette-overrides 1082#+vindex: modus-vivendi-palette-overrides
1070+ ~modus-vivendi-palette-overrides~ 1083+ ~modus-vivendi-palette-overrides~
1071 1084
@@ -1075,6 +1088,9 @@ palette variable is =THEME-NAME-palette-overrides=, thus yielding:
1075#+vindex: modus-vivendi-tinted-palette-overrides 1088#+vindex: modus-vivendi-tinted-palette-overrides
1076+ ~modus-vivendi-tinted-palette-overrides~ 1089+ ~modus-vivendi-tinted-palette-overrides~
1077 1090
1091#+vindex: modus-vivendi-tritanopia-palette-overrides
1092+ ~modus-vivendi-tritanopia-palette-overrides~
1093
1078Theme-specific overrides take precedence over the shared ones. It is 1094Theme-specific overrides take precedence over the shared ones. It is
1079strongly advised that shared overrides do NOT alter color values, as 1095strongly advised that shared overrides do NOT alter color values, as
1080those will not be appropriate for both dark and light themes. Common 1096those will not be appropriate for both dark and light themes. Common
@@ -1123,7 +1139,7 @@ For example, the ~modus-operandi-palette~ is like this:
1123#+end_src 1139#+end_src
1124 1140
1125The ~modus-operandi-palette-overrides~ targets the entries that need 1141The ~modus-operandi-palette-overrides~ targets the entries that need
1126to be changed. For example, to make the main foreground colour a dark 1142to be changed. For example, to make the main foreground color a dark
1127gray instead of pure black, use a shade of red for comments, and apply 1143gray instead of pure black, use a shade of red for comments, and apply
1128a cyan hue to keywords: 1144a cyan hue to keywords:
1129 1145
@@ -1153,15 +1169,30 @@ Named colors can be previewed, such as with the command
1153For a video tutorial that users of all skill levels can approach, 1169For a video tutorial that users of all skill levels can approach,
1154watch: https://protesilaos.com/codelog/2022-12-17-modus-themes-v4-demo/. 1170watch: https://protesilaos.com/codelog/2022-12-17-modus-themes-v4-demo/.
1155 1171
1156*** Palette override presets 1172* Advanced customization
1173:properties:
1174:custom_id: h:f4651d55-8c07-46aa-b52b-bed1e53463bb
1175:end:
1176
1177Unlike the predefined customization options which follow a clear pattern
1178of allowing the user to quickly specify their preference, the themes
1179also provide a more flexible, albeit difficult, mechanism to control
1180things with precision ([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization Options]]).
1181
1182This section is of interest only to users who are prepared to maintain
1183their own local tweaks and who are willing to deal with any possible
1184incompatibilities between versioned releases of the themes. As such,
1185they are labeled as "do-it-yourself" or "DIY".
1186
1187** Palette override presets
1157:PROPERTIES: 1188:PROPERTIES:
1158:CUSTOM_ID: h:b0bc811c-227e-42ec-bf67-15e1f41eb7bc 1189:CUSTOM_ID: h:b0bc811c-227e-42ec-bf67-15e1f41eb7bc
1159:END: 1190:END:
1160 1191
1161This section shows how to refashion the themes by opting in to the 1192This section shows how to refashion the themes by opting in to the
1162stylistic presets we provide. Those presets override the default 1193stylistic presets we provide. Those presets override the default
1163color mappings to amplify or tone down the overall coloration of the 1194color mappings to amplify, tone down, or refashion the overall
1164them. 1195coloration of the themes.
1165 1196
1166To make almost all aspects of the themes less intense, use this: 1197To make almost all aspects of the themes less intense, use this:
1167 1198
@@ -1187,6 +1218,18 @@ The ~modus-themes-preset-overrides-intense~ makes many background
1187colors accented instead of gray and increases coloration in a number 1218colors accented instead of gray and increases coloration in a number
1188of places. Colors stand out more and are made easier to spot. 1219of places. Colors stand out more and are made easier to spot.
1189 1220
1221#+vindex: modus-themes-preset-overrides-cooler
1222#+vindex: modus-themes-preset-overrides-warmer
1223For some stylistic variation try the "cooler" and "warmer" presets:
1224
1225#+begin_src emacs-lisp
1226;; This:
1227(setq modus-themes-common-palette-overrides modus-themes-preset-overrides-cooler)
1228
1229;; Or:
1230(setq modus-themes-common-palette-overrides modus-themes-preset-overrides-warmer)
1231#+end_src
1232
1190Note that the user is not limited to those presets. The system of 1233Note that the user is not limited to those presets. The system of
1191overrides we provide makes it possible to tweak the value of each 1234overrides we provide makes it possible to tweak the value of each
1192individual named color and to change how values are assigned to 1235individual named color and to change how values are assigned to
@@ -1214,7 +1257,7 @@ the general idea (extra space for didactic purposes):
1214 ,@modus-themes-preset-overrides-intense)) 1257 ,@modus-themes-preset-overrides-intense))
1215#+end_src 1258#+end_src
1216 1259
1217*** Stylistic variants using palette overrides 1260** Stylistic variants using palette overrides
1218:PROPERTIES: 1261:PROPERTIES:
1219:CUSTOM_ID: h:df1199d8-eaba-47db-805d-6b568a577bf3 1262:CUSTOM_ID: h:df1199d8-eaba-47db-805d-6b568a577bf3
1220:END: 1263:END:
@@ -1226,7 +1269,7 @@ to take effect. To apply overrides at startup simply define them
1226before the call that loads the theme. Remember that we also provide 1269before the call that loads the theme. Remember that we also provide
1227presets that are easier to apply ([[#h:b0bc811c-227e-42ec-bf67-15e1f41eb7bc][Palette override presets]]). 1270presets that are easier to apply ([[#h:b0bc811c-227e-42ec-bf67-15e1f41eb7bc][Palette override presets]]).
1228 1271
1229**** Make the mode line borderless 1272*** Make the mode line borderless
1230:PROPERTIES: 1273:PROPERTIES:
1231:CUSTOM_ID: h:80ddba52-e188-411f-8cc0-480ebd75befe 1274:CUSTOM_ID: h:80ddba52-e188-411f-8cc0-480ebd75befe
1232:END: 1275:END:
@@ -1263,7 +1306,7 @@ set their color to that of the underlying background.
1263 (border-mode-line-inactive bg-mode-line-inactive))) 1306 (border-mode-line-inactive bg-mode-line-inactive)))
1264#+end_src 1307#+end_src
1265 1308
1266**** Make the active mode line colorful 1309*** Make the active mode line colorful
1267:PROPERTIES: 1310:PROPERTIES:
1268:CUSTOM_ID: h:e8d781be-eefc-4a81-ac4e-5ed156190df7 1311:CUSTOM_ID: h:e8d781be-eefc-4a81-ac4e-5ed156190df7
1269:END: 1312:END:
@@ -1307,7 +1350,7 @@ have a blue mode line for ~modus-operandi~ and a red one for
1307 (border-mode-line-active bg-red-subtle))) 1350 (border-mode-line-active bg-red-subtle)))
1308#+end_src 1351#+end_src
1309 1352
1310**** Make the tab bar more or less colorful 1353*** Make the tab bar more or less colorful
1311:PROPERTIES: 1354:PROPERTIES:
1312:CUSTOM_ID: h:096658d7-a0bd-4a99-b6dc-9b20a20cda37 1355:CUSTOM_ID: h:096658d7-a0bd-4a99-b6dc-9b20a20cda37
1313:END: 1356:END:
@@ -1359,7 +1402,7 @@ manual.
1359 (bg-tab-other bg-cyan-subtle))) 1402 (bg-tab-other bg-cyan-subtle)))
1360#+end_src 1403#+end_src
1361 1404
1362**** Make the fringe invisible or another color 1405*** Make the fringe invisible or another color
1363:PROPERTIES: 1406:PROPERTIES:
1364:CUSTOM_ID: h:c312dcac-36b6-4a1f-b1f5-ab1c9abe27b0 1407:CUSTOM_ID: h:c312dcac-36b6-4a1f-b1f5-ab1c9abe27b0
1365:END: 1408:END:
@@ -1393,7 +1436,7 @@ or continuation lines.
1393 '((fringe bg-blue-nuanced))) 1436 '((fringe bg-blue-nuanced)))
1394#+end_src 1437#+end_src
1395 1438
1396**** Make links use subtle or no underlines 1439*** Make links use subtle or no underlines
1397:PROPERTIES: 1440:PROPERTIES:
1398:CUSTOM_ID: h:6c1d1dea-5cbf-4d92-b7bb-570a7a23ffe9 1441:CUSTOM_ID: h:6c1d1dea-5cbf-4d92-b7bb-570a7a23ffe9
1399:END: 1442:END:
@@ -1417,7 +1460,7 @@ that underline mappings can read correctly.
1417 (underline-link-symbolic unspecified))) 1460 (underline-link-symbolic unspecified)))
1418#+end_src 1461#+end_src
1419 1462
1420**** Make prompts more or less colorful 1463*** Make prompts more or less colorful
1421:PROPERTIES: 1464:PROPERTIES:
1422:CUSTOM_ID: h:bd75b43a-0bf1-45e7-b8b4-20944ca8b7f8 1465:CUSTOM_ID: h:bd75b43a-0bf1-45e7-b8b4-20944ca8b7f8
1423:END: 1466:END:
@@ -1454,7 +1497,7 @@ block we show how to add or remove color from prompts.
1454 (bg-prompt bg-yellow-subtle))) ; try to replace "subtle" with "intense" 1497 (bg-prompt bg-yellow-subtle))) ; try to replace "subtle" with "intense"
1455#+end_src 1498#+end_src
1456 1499
1457**** Make completion matches more or less colorful 1500*** Make completion matches more or less colorful
1458:PROPERTIES: 1501:PROPERTIES:
1459:CUSTOM_ID: h:d959f789-0517-4636-8780-18123f936f91 1502:CUSTOM_ID: h:d959f789-0517-4636-8780-18123f936f91
1460:END: 1503:END:
@@ -1541,7 +1584,7 @@ colors to two:
1541 1584
1542The user can mix and match to their liking. 1585The user can mix and match to their liking.
1543 1586
1544**** Make comments yellow and strings green 1587*** Make comments yellow and strings green
1545:PROPERTIES: 1588:PROPERTIES:
1546:CUSTOM_ID: h:26f53daa-0065-48dc-88ab-6a718d16cd95 1589:CUSTOM_ID: h:26f53daa-0065-48dc-88ab-6a718d16cd95
1547:END: 1590:END:
@@ -1584,7 +1627,7 @@ reproduce the effect, but also how to tweak it to one's liking.
1584 (string yellow-cooler))) 1627 (string yellow-cooler)))
1585#+end_src 1628#+end_src
1586 1629
1587**** Make code syntax use the old alt-syntax style 1630*** Make code syntax use the old alt-syntax style
1588:PROPERTIES: 1631:PROPERTIES:
1589:CUSTOM_ID: h:c8767172-bf11-4c96-81dc-e736c464fc9c 1632:CUSTOM_ID: h:c8767172-bf11-4c96-81dc-e736c464fc9c
1590:END: 1633:END:
@@ -1669,7 +1712,7 @@ The user can always mix and match styles to their liking.
1669 1712
1670[[#h:943063da-7b27-4ba4-9afe-f8fe77652fd1][Make use of alternative styles for code syntax]]. 1713[[#h:943063da-7b27-4ba4-9afe-f8fe77652fd1][Make use of alternative styles for code syntax]].
1671 1714
1672**** Make use of alternative styles for code syntax 1715*** Make use of alternative styles for code syntax
1673:PROPERTIES: 1716:PROPERTIES:
1674:CUSTOM_ID: h:943063da-7b27-4ba4-9afe-f8fe77652fd1 1717:CUSTOM_ID: h:943063da-7b27-4ba4-9afe-f8fe77652fd1
1675:END: 1718:END:
@@ -1760,7 +1803,7 @@ theme palette.
1760 (variable cyan-warmer))) 1803 (variable cyan-warmer)))
1761#+end_src 1804#+end_src
1762 1805
1763**** Make matching parenthesis more or less intense 1806*** Make matching parenthesis more or less intense
1764:PROPERTIES: 1807:PROPERTIES:
1765:CUSTOM_ID: h:259cf8f5-48ec-4b13-8a69-5d6387094468 1808:CUSTOM_ID: h:259cf8f5-48ec-4b13-8a69-5d6387094468
1766:END: 1809:END:
@@ -1790,7 +1833,7 @@ to enable underlines for those highlights.
1790 (underline-paren-match fg-main))) 1833 (underline-paren-match fg-main)))
1791#+end_src 1834#+end_src
1792 1835
1793**** Make box buttons more or less gray 1836*** Make box buttons more or less gray
1794:PROPERTIES: 1837:PROPERTIES:
1795:CUSTOM_ID: h:4f6b6ca3-f5bb-4830-8312-baa232305360 1838:CUSTOM_ID: h:4f6b6ca3-f5bb-4830-8312-baa232305360
1796:END: 1839:END:
@@ -1818,7 +1861,7 @@ inactive ones.
1818 (fg-button-inactive "gray50"))) 1861 (fg-button-inactive "gray50")))
1819#+end_src 1862#+end_src
1820 1863
1821**** Make TODO and DONE more or less intense 1864*** Make TODO and DONE more or less intense
1822:PROPERTIES: 1865:PROPERTIES:
1823:CUSTOM_ID: h:b57bb50b-a863-4ea8-bb38-6de2275fa868 1866:CUSTOM_ID: h:b57bb50b-a863-4ea8-bb38-6de2275fa868
1824:END: 1867:END:
@@ -1858,7 +1901,7 @@ to subdue them.
1858 '((prose-done fg-dim))) 1901 '((prose-done fg-dim)))
1859#+end_src 1902#+end_src
1860 1903
1861**** Make headings more or less colorful 1904*** Make headings more or less colorful
1862:PROPERTIES: 1905:PROPERTIES:
1863:CUSTOM_ID: h:11297984-85ea-4678-abe9-a73aeab4676a 1906:CUSTOM_ID: h:11297984-85ea-4678-abe9-a73aeab4676a
1864:END: 1907:END:
@@ -1915,7 +1958,7 @@ match styles at will.
1915 (overline-heading-1 border))) 1958 (overline-heading-1 border)))
1916#+end_src 1959#+end_src
1917 1960
1918**** Make Org agenda more or less colorful 1961*** Make Org agenda more or less colorful
1919:PROPERTIES: 1962:PROPERTIES:
1920:CUSTOM_ID: h:a5af0452-a50f-481d-bf60-d8143f98105f 1963:CUSTOM_ID: h:a5af0452-a50f-481d-bf60-d8143f98105f
1921:END: 1964:END:
@@ -1980,7 +2023,25 @@ A third example that makes the agenda more blue:
1980 (date-weekend fg-dim))) 2023 (date-weekend fg-dim)))
1981#+end_src 2024#+end_src
1982 2025
1983**** Make inline code in prose use alternative styles 2026Yet another example that also affects =DONE= and =TODO= keywords:
2027
2028#+begin_src emacs-lisp
2029;; Change dates to a set of more subtle combinations. Deadlines are a
2030;; shade of magenta, scheduled dates are a shade of green that
2031;; complements that of the deadlines, weekday headings use the main
2032;; foreground color while weekends are a shade of gray. The DONE
2033;; keyword is a faint blue-gray while TODO is yellow.
2034(setq modus-themes-common-palette-overrides
2035 '((date-deadline magenta-warmer)
2036 (date-scheduled green-cooler)
2037 (date-weekday fg-main)
2038 (date-event fg-dim)
2039 (date-now blue)
2040 (prose-done fg-alt)
2041 (prose-todo yellow)))
2042#+end_src
2043
2044*** Make inline code in prose use alternative styles
1984:PROPERTIES: 2045:PROPERTIES:
1985:CUSTOM_ID: h:bb5b396f-5532-4d52-ab13-149ca24854f1 2046:CUSTOM_ID: h:bb5b396f-5532-4d52-ab13-149ca24854f1
1986:END: 2047:END:
@@ -2039,7 +2100,7 @@ do not show every possible permutation.
2039 (prose-verbatim red-warmer))) 2100 (prose-verbatim red-warmer)))
2040#+end_src 2101#+end_src
2041 2102
2042**** Make mail citations and headers more or less colorful 2103*** Make mail citations and headers more or less colorful
2043:PROPERTIES: 2104:PROPERTIES:
2044:CUSTOM_ID: h:7da7a4ad-5d3a-4f11-9796-5a1abed0f0c4 2105:CUSTOM_ID: h:7da7a4ad-5d3a-4f11-9796-5a1abed0f0c4
2045:END: 2106:END:
@@ -2108,7 +2169,7 @@ We thus have the following:
2108 (mail-other green))) 2169 (mail-other green)))
2109#+end_src 2170#+end_src
2110 2171
2111**** Make the region preserve text colors, plus other styles 2172*** Make the region preserve text colors, plus other styles
2112:PROPERTIES: 2173:PROPERTIES:
2113:CUSTOM_ID: h:c8605d37-66e1-42aa-986e-d7514c3af6fe 2174:CUSTOM_ID: h:c8605d37-66e1-42aa-986e-d7514c3af6fe
2114:END: 2175:END:
@@ -2148,7 +2209,7 @@ with an appropriate foreground value.
2148 (fg-region fg-main))) 2209 (fg-region fg-main)))
2149#+end_src 2210#+end_src
2150 2211
2151**** Make mouse highlights more or less colorful 2212*** Make mouse highlights more or less colorful
2152:PROPERTIES: 2213:PROPERTIES:
2153:CUSTOM_ID: h:b5cab69d-d7cb-451c-8ff9-1f545ceb6caf 2214:CUSTOM_ID: h:b5cab69d-d7cb-451c-8ff9-1f545ceb6caf
2154:END: 2215:END:
@@ -2177,7 +2238,7 @@ mapping that covers mouse hover effects and related highlights:
2177 '((bg-hover bg-green-subtle))) 2238 '((bg-hover bg-green-subtle)))
2178#+end_src 2239#+end_src
2179 2240
2180**** Make language underlines less colorful 2241*** Make language underlines less colorful
2181:PROPERTIES: 2242:PROPERTIES:
2182:CUSTOM_ID: h:03dbd5af-6bae-475e-85a2-cec189f69598 2243:CUSTOM_ID: h:03dbd5af-6bae-475e-85a2-cec189f69598
2183:END: 2244:END:
@@ -2210,7 +2271,7 @@ by code linters and prose spell checkers.
2210 (underline-note green-intense))) 2271 (underline-note green-intense)))
2211#+end_src 2272#+end_src
2212 2273
2213**** Make line numbers use alternative styles 2274*** Make line numbers use alternative styles
2214:PROPERTIES: 2275:PROPERTIES:
2215:CUSTOM_ID: h:b6466f51-cb58-4007-9ebe-53a27af655c7 2276:CUSTOM_ID: h:b6466f51-cb58-4007-9ebe-53a27af655c7
2216:END: 2277:END:
@@ -2252,7 +2313,7 @@ this section we show how to affect the ~display-line-numbers-mode~.
2252 (bg-line-number-active bg-cyan-intense))) 2313 (bg-line-number-active bg-cyan-intense)))
2253#+end_src 2314#+end_src
2254 2315
2255**** Make diffs use only a foreground 2316*** Make diffs use only a foreground
2256:PROPERTIES: 2317:PROPERTIES:
2257:CUSTOM_ID: h:b3761482-bcbf-4990-a41e-4866fb9dad15 2318:CUSTOM_ID: h:b3761482-bcbf-4990-a41e-4866fb9dad15
2258:END: 2319:END:
@@ -2268,7 +2329,7 @@ adjustments for them by overriding their palettes directly instead of
2268just using the "common" overrides. 2329just using the "common" overrides.
2269 2330
2270#+begin_src emacs-lisp 2331#+begin_src emacs-lisp
2271;; Diffs with only foreground colours. Word-wise ("refined") diffs 2332;; Diffs with only foreground colors. Word-wise ("refined") diffs
2272;; have a gray background to draw attention to themselves. 2333;; have a gray background to draw attention to themselves.
2273(setq modus-themes-common-palette-overrides 2334(setq modus-themes-common-palette-overrides
2274 '((bg-added unspecified) 2335 '((bg-added unspecified)
@@ -2316,7 +2377,7 @@ just using the "common" overrides.
2316 (fg-removed-intense yellow-intense))) 2377 (fg-removed-intense yellow-intense)))
2317#+end_src 2378#+end_src
2318 2379
2319**** Make deuteranopia diffs red and blue instead of yellow and blue 2380*** Make deuteranopia diffs red and blue instead of yellow and blue
2320:PROPERTIES: 2381:PROPERTIES:
2321:CUSTOM_ID: h:16389ea1-4cb6-4b18-9409-384324113541 2382:CUSTOM_ID: h:16389ea1-4cb6-4b18-9409-384324113541
2322:END: 2383:END:
@@ -2367,20 +2428,110 @@ respectively. This is achieved by overriding the "changed" and
2367 (fg-removed-intense "#ff9095"))) 2428 (fg-removed-intense "#ff9095")))
2368#+end_src 2429#+end_src
2369 2430
2370* Advanced customization 2431*** Make the themes look like what the maintainer uses
2371:properties: 2432:PROPERTIES:
2372:custom_id: h:f4651d55-8c07-46aa-b52b-bed1e53463bb 2433:CUSTOM_ID: h:aabcada6-810d-4eee-b34a-d2a9c301824d
2373:end: 2434:END:
2374 2435
2375Unlike the predefined customization options which follow a clear pattern 2436Based on what we have learnt from the previous sections of this
2376of allowing the user to quickly specify their preference, the themes 2437manual, here is what Protesilaos uses:
2377also provide a more flexible, albeit difficult, mechanism to control
2378things with precision ([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization Options]]).
2379 2438
2380This section is of interest only to users who are prepared to maintain 2439#+begin_src emacs-lisp
2381their own local tweaks and who are willing to deal with any possible 2440;; Always reload the theme for changes to take effect!
2382incompatibilities between versioned releases of the themes. As such, 2441
2383they are labeled as "do-it-yourself" or "DIY". 2442(setq modus-themes-custom-auto-reload nil
2443 modus-themes-to-toggle '(modus-operandi modus-vivendi)
2444 modus-themes-mixed-fonts t
2445 modus-themes-variable-pitch-ui nil
2446 modus-themes-italic-constructs t
2447 modus-themes-bold-constructs nil
2448 modus-themes-org-blocks nil
2449 modus-themes-completions '((t . (extrabold)))
2450 modus-themes-prompts nil
2451 modus-themes-headings
2452 '((agenda-structure . (variable-pitch light 2.2))
2453 (agenda-date . (variable-pitch regular 1.3))
2454 (t . (regular 1.15))))
2455
2456(setq modus-themes-common-palette-overrides
2457 '((cursor magenta-cooler)
2458 ;; Make the fringe invisible.
2459 (fringe unspecified)
2460 ;; Make line numbers less intense and add a shade of cyan
2461 ;; for the current line number.
2462 (fg-line-number-inactive "gray50")
2463 (fg-line-number-active cyan-cooler)
2464 (bg-line-number-inactive unspecified)
2465 (bg-line-number-active unspecified)
2466 ;; Make the current line of `hl-line-mode' a fine shade of
2467 ;; gray (though also see my `lin' package).
2468 (bg-hl-line bg-dim)
2469 ;; Make the region have a cyan-green background with no
2470 ;; specific foreground (use foreground of underlying text).
2471 ;; "bg-sage" refers to Salvia officinalis, else the common
2472 ;; sage.
2473 (bg-region bg-sage)
2474 (fg-region unspecified)
2475 ;; Make matching parentheses a shade of magenta. It
2476 ;; complements the region nicely.
2477 (bg-paren-match bg-magenta-intense)
2478 ;; Make email citations faint and neutral, reducing the
2479 ;; default four colors to two; make mail headers cyan-blue.
2480 (mail-cite-0 fg-dim)
2481 (mail-cite-1 blue-faint)
2482 (mail-cite-2 fg-dim)
2483 (mail-cite-3 blue-faint)
2484 (mail-part cyan-warmer)
2485 (mail-recipient blue-warmer)
2486 (mail-subject magenta-cooler)
2487 (mail-other cyan-warmer)
2488 ;; Change dates to a set of more subtle combinations.
2489 (date-deadline magenta-cooler)
2490 (date-scheduled magenta)
2491 (date-weekday fg-main)
2492 (date-event fg-dim)
2493 (date-now blue-faint)
2494 ;; Make tags (Org) less colorful and tables look the same as
2495 ;; the default foreground.
2496 (prose-done cyan-cooler)
2497 (prose-tag fg-dim)
2498 (prose-table fg-main)
2499 ;; Make headings less colorful (though I never use deeply
2500 ;; nested headings).
2501 (fg-heading-2 blue-faint)
2502 (fg-heading-3 magenta-faint)
2503 (fg-heading-4 blue-faint)
2504 (fg-heading-5 magenta-faint)
2505 (fg-heading-6 blue-faint)
2506 (fg-heading-7 magenta-faint)
2507 (fg-heading-8 blue-faint)
2508 ;; Make the active mode line a fine shade of lavender
2509 ;; (purple) and tone down the gray of the inactive mode
2510 ;; lines.
2511 (bg-mode-line-active bg-lavender)
2512 (border-mode-line-active bg-lavender)
2513
2514 (bg-mode-line-inactive bg-dim)
2515 (border-mode-line-inactive bg-inactive)
2516 ;; Make the prompts a shade of magenta, to fit in nicely with
2517 ;; the overall blue-cyan-purple style of the other overrides.
2518 ;; Add a nuanced background as well.
2519 (bg-prompt bg-magenta-nuanced)
2520 (fg-prompt magenta-cooler)
2521 ;; Tweak some more constructs for stylistic constistency.
2522 (name blue-warmer)
2523 (identifier magenta-faint)
2524 (keybind magenta-cooler)
2525 (accent-0 magenta-cooler)
2526 (accent-1 cyan-cooler)
2527 (accent-2 blue-warmer)
2528 (accent-3 red-cooler)))
2529
2530;; Make the active mode line have a pseudo 3D effect (this assumes
2531;; you are using the default mode line and not an extra package).
2532(custom-set-faces
2533 '(mode-line ((t :box (:style released-button)))))
2534#+end_src
2384 2535
2385** More accurate colors in terminal emulators 2536** More accurate colors in terminal emulators
2386:PROPERTIES: 2537:PROPERTIES:
@@ -2584,8 +2735,9 @@ for palette overrides. Else it reads only the default palette.
2584 2735
2585[[#h:34c7a691-19bb-4037-8d2f-67a07edab150][Option for palette overrides]]. 2736[[#h:34c7a691-19bb-4037-8d2f-67a07edab150][Option for palette overrides]].
2586 2737
2587With optional =THEME= as a symbol among ~modus-themes-items~, use the 2738With optional =THEME= as a symbol among ~modus-themes-items~ (alias
2588palette of that item. Else use the current Modus theme. 2739~modus-themes-collection~), use the palette of that item. Else use
2740the current Modus theme.
2589 2741
2590If =COLOR= is not present in the palette, this function returns the 2742If =COLOR= is not present in the palette, this function returns the
2591~unspecified~ symbol, which is safe when used as a face attribute's 2743~unspecified~ symbol, which is safe when used as a face attribute's
@@ -3479,6 +3631,90 @@ In this document, we cover ~modus-themes-after-load-theme-hook~ though
3479the user can replace it with ~after-enable-theme-hook~ should they 3631the user can replace it with ~after-enable-theme-hook~ should they
3480need to (provided they understand the implications). 3632need to (provided they understand the implications).
3481 3633
3634** Use more spacious margins or padding in Emacs frames
3635:PROPERTIES:
3636:CUSTOM_ID: h:43bcb5d0-e25f-470f-828c-662cee9e21f1
3637:END:
3638
3639By default, Emacs frames try to maximize the number of characters that
3640fit in the current visible portion of the buffer. Users may prefer to
3641have some extra padding instead. This can make Emacs frames look more
3642pleasant, but also make it easier to identify the currently active
3643window.
3644
3645The way to implement such padding is two-fold:
3646
36471. In the =early-init.el= file instruct Emacs to use a higher value
3648 for the ~internal-border-width~ of all frames, as well as for the
3649 ~right-divider-width~. The former concerns the outer boundaries of
3650 Emacs frames, while the latter pertains to dividers between Emacs
3651 windows.
3652
36532. Make the relevant faces invisible by changing the value of their
3654 relevant attributes to that of the current theme's main background.
3655
3656The parameters of Emacs frames are specified in the variables
3657~initial-frame-alist~ and ~default-frame-alist~. The "initial frame"
3658refers to the first frame that appears on Emacs startup. The
3659"default" refers to the fallback values that apply to all other frames
3660that Emacs creates (unless those are explicitly overridden by a
3661bespoke ~make-frame~ call).
3662
3663In detail, first we use the same values for the two frame alist variables:
3664
3665#+begin_src emacs-lisp
3666;; This must go in the early-init.el so that it applies to the initial
3667;; frame.
3668(dolist (var '(default-frame-alist initial-frame-alist))
3669 (add-to-list var '(right-divider-width . 20))
3670 (add-to-list var '(internal-border-width . 20)))
3671#+end_src
3672
3673What the ~dolist~ does is to call ~add-to-list~ for the two variables
3674we specify there. This economizes on typing.
3675
3676Then we define a function that makes the relevant faces invisible.
3677The reason we do this with a function is so we can hook it to the
3678"post load" phase of a theme, thus applying the new background value
3679(otherwise you keep the old background, which likely means that the
3680faces will no longer be invisible).
3681
3682#+begin_src emacs-lisp
3683(defun my-modus-themes-invisible-dividers ()
3684 "Make window dividers invisible.
3685Add this to the `modus-themes-post-load-hook'."
3686 (let ((bg (face-background 'default)))
3687 (custom-set-faces
3688 `(fringe ((t :background ,bg :foreground ,bg)))
3689 `(window-divider ((t :background ,bg :foreground ,bg)))
3690 `(window-divider-first-pixel ((t :background ,bg :foreground ,bg)))
3691 `(window-divider-last-pixel ((t :background ,bg :foreground ,bg))))))
3692
3693(add-hook 'modus-themes-post-load-hook #'my-modus-themes-invisible-dividers)
3694#+end_src
3695
3696The above will work only for themes that belong to the Modus family.
3697For users of Emacs version 29 or higher, there exists a theme-agnostic
3698hook that takes a function with one argument---that of the theme---and
3699calls in the the "post enable" phase of theme loading. Here is the
3700above snippet, with the necessary tweaks:
3701
3702#+begin_src emacs-lisp
3703(defun my-modus-themes-invisible-dividers (_theme)
3704 "Make window dividers for THEME invisible."
3705 (let ((bg (face-background 'default)))
3706 (custom-set-faces
3707 `(fringe ((t :background ,bg :foreground ,bg)))
3708 `(window-divider ((t :background ,bg :foreground ,bg)))
3709 `(window-divider-first-pixel ((t :background ,bg :foreground ,bg)))
3710 `(window-divider-last-pixel ((t :background ,bg :foreground ,bg))))))
3711
3712(add-hook 'enable-theme-functions #'my-modus-themes-invisible-dividers)
3713#+end_src
3714
3715Users of older versions of Emacs can read the entry herein about
3716defining their own theme-agnostic hook ([[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][A theme-agnostic hook for theme loading]]).
3717
3482** Custom hl-todo colors 3718** Custom hl-todo colors
3483:PROPERTIES: 3719:PROPERTIES:
3484:CUSTOM_ID: h:2ef83a21-2f0a-441e-9634-473feb940743 3720:CUSTOM_ID: h:2ef83a21-2f0a-441e-9634-473feb940743
@@ -3636,7 +3872,7 @@ have lots of extensions, so the "full support" may not be 100% true…
3636+ csv-mode 3872+ csv-mode
3637+ ctrlf 3873+ ctrlf
3638+ custom (what you get with {{{kbd(M-x customize)}}}) 3874+ custom (what you get with {{{kbd(M-x customize)}}})
3639- dashboard 3875+ dashboard
3640+ deadgrep 3876+ deadgrep
3641+ deft 3877+ deft
3642+ devdocs 3878+ devdocs
@@ -3651,6 +3887,7 @@ have lots of extensions, so the "full support" may not be 100% true…
3651+ dired-narrow 3887+ dired-narrow
3652+ dired-subtree 3888+ dired-subtree
3653+ diredfl 3889+ diredfl
3890+ disk-usage
3654+ display-fill-column-indicator-mode 3891+ display-fill-column-indicator-mode
3655+ doom-modeline 3892+ doom-modeline
3656+ ediff 3893+ ediff
@@ -3715,6 +3952,8 @@ have lots of extensions, so the "full support" may not be 100% true…
3715+ ivy* 3952+ ivy*
3716+ ivy-posframe 3953+ ivy-posframe
3717+ jira (org-jira) 3954+ jira (org-jira)
3955+ jit-spell
3956+ jinx
3718+ journalctl-mode 3957+ journalctl-mode
3719+ js2-mode 3958+ js2-mode
3720+ julia 3959+ julia
@@ -3733,7 +3972,6 @@ have lots of extensions, so the "full support" may not be 100% true…
3733+ minimap 3972+ minimap
3734+ mode-line 3973+ mode-line
3735+ mood-line 3974+ mood-line
3736+ moody
3737+ mpdel 3975+ mpdel
3738+ mu4e 3976+ mu4e
3739+ multiple-cursors 3977+ multiple-cursors
@@ -3780,6 +4018,7 @@ have lots of extensions, so the "full support" may not be 100% true…
3780+ rg (rg.el) 4018+ rg (rg.el)
3781+ ripgrep 4019+ ripgrep
3782+ rmail 4020+ rmail
4021+ rst-mode
3783+ ruler-mode 4022+ ruler-mode
3784+ sesman 4023+ sesman
3785+ shell-script-mode 4024+ shell-script-mode
@@ -3969,9 +4208,9 @@ length elsewhere in this manual:
3969 ;; Doom should not be implementing such hacks because themes 4208 ;; Doom should not be implementing such hacks because themes
3970 ;; cannot support them: 4209 ;; cannot support them:
3971 ;; <https://protesilaos.com/codelog/2022-08-04-doom-git-gutter-modus-themes/>. 4210 ;; <https://protesilaos.com/codelog/2022-08-04-doom-git-gutter-modus-themes/>.
3972 `(git-gutter-fr:added ((,c :foreground ,bg-added-intense))) 4211 `(git-gutter-fr:added ((,c :foreground ,bg-added-fringe)))
3973 `(git-gutter-fr:deleted ((,c :foreground ,bg-removed-intense))) 4212 `(git-gutter-fr:deleted ((,c :foreground ,bg-removed-fringe)))
3974 `(git-gutter-fr:modified ((,c :foreground ,bg-changed-intense)))))) 4213 `(git-gutter-fr:modified ((,c :foreground ,bg-changed-fringe))))))
3975 4214
3976(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) 4215(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces)
3977#+end_src 4216#+end_src
@@ -4941,9 +5180,10 @@ themes remains consistent.
4941 5180
4942The former criterion should be crystal clear as it pertains to the 5181The former criterion should be crystal clear as it pertains to the
4943scientific foundations of the themes: high legibility and taking care 5182scientific foundations of the themes: high legibility and taking care
4944of the needs of users with red-green color deficiency (deuteranopia) 5183of the needs of users with red-green/blue-yellow color deficiency
4945by avoiding red+green color coding paradigms and/or by providing 5184(deuteranopia and tritanopia) by avoiding red+green color coding
4946yellow+blue variants ([[#h:f0f3dbcb-602d-40cf-b918-8f929c441baf][Overview]]). 5185paradigms and/or by providing yellow+blue variants for deuteranopia
5186and red+cyan for tritanopia ([[#h:f0f3dbcb-602d-40cf-b918-8f929c441baf][Overview]]).
4947 5187
4948The latter criterion is the "je ne sais quoi" of the artistic aspect of 5188The latter criterion is the "je ne sais quoi" of the artistic aspect of
4949the themes, which is partially fleshed out in this manual. 5189the themes, which is partially fleshed out in this manual.
@@ -5099,13 +5339,14 @@ The Modus themes are a collective effort. Every bit of work matters.
5099+ Contributions to code or documentation :: Aleksei Gusev, Alex 5339+ Contributions to code or documentation :: Aleksei Gusev, Alex
5100 Griffin, Anders Johansson, Antonio Ruiz, Basil L.{{{space()}}} 5340 Griffin, Anders Johansson, Antonio Ruiz, Basil L.{{{space()}}}
5101 Contovounesios, Björn Lindström, Carlo Zancanaro, Christian Tietze, 5341 Contovounesios, Björn Lindström, Carlo Zancanaro, Christian Tietze,
5102 Daniel Mendler, Eli Zaretskii, Fritz Grabo, Illia Ostapyshyn, Kévin 5342 Daniel Mendler, David Edmondson, Eli Zaretskii, Fritz Grabo, Gautier
5103 Le Gouguec, Koen van Greevenbroek, Kostadin Ninev, Madhavan 5343 Ponsinet, Illia Ostapyshyn, Kévin Le Gouguec, Koen van Greevenbroek,
5104 Krishnan, Manuel Giraud, Markus Beppler, Matthew Stevenson, Mauro 5344 Kostadin Ninev, Madhavan Krishnan, Manuel Giraud, Markus Beppler,
5105 Aranda, Nicolas De Jaeghere, Paul David, Philip Kaludercic, Pierre 5345 Matthew Stevenson, Mauro Aranda, Nacho Barrientos, Nicolas De
5106 Téchoueyres, Rudolf Adamkovič, Sergey Nichiporchik, Stephen Gildea, 5346 Jaeghere, Paul David, Philip Kaludercic, Pierre Téchoueyres, Rudolf
5107 Shreyas Ragavan, Stefan Kangas, Utkarsh Singh, Vincent Murphy, 5347 Adamkovič, Sergey Nichiporchik, Shreyas Ragavan, Stefan Kangas,
5108 Xinglu Chen, Yuanchen Xie, okamsn. 5348 Stephen Gildea, Steve Downey, Tomasz Hołubowicz, Utkarsh Singh,
5349 Vincent Murphy, Xinglu Chen, Yuanchen Xie, okamsn.
5109 5350
5110+ Ideas and user feedback :: Aaron Jensen, Adam Porter, Adam Spiers, 5351+ Ideas and user feedback :: Aaron Jensen, Adam Porter, Adam Spiers,
5111 Adrian Manea, Aleksei Pirogov, Alex Griffin, Alex Koen, Alex 5352 Adrian Manea, Aleksei Pirogov, Alex Griffin, Alex Koen, Alex
@@ -5127,19 +5368,20 @@ The Modus themes are a collective effort. Every bit of work matters.
5127 Bestley, Mark Burton, Mark Simpson, Marko Kocic, Markus Beppler, 5368 Bestley, Mark Burton, Mark Simpson, Marko Kocic, Markus Beppler,
5128 Matt Armstrong, Matthias Fuchs, Mattias Engdegård, Mauro Aranda, 5369 Matt Armstrong, Matthias Fuchs, Mattias Engdegård, Mauro Aranda,
5129 Maxime Tréca, Michael Goldenberg, Morgan Smith, Morgan Willcock, 5370 Maxime Tréca, Michael Goldenberg, Morgan Smith, Morgan Willcock,
5130 Murilo Pereira, Nicky van Foreest, Nicolas De Jaeghere, Pablo 5371 Murilo Pereira, Nicky van Foreest, Nicolas De Jaeghere, Nicolas
5131 Stafforini, Paul Poloskov, Pengji Zhang, Pete Kazmier, Peter Wu, 5372 Semrau, Oliver Epper, Pablo Stafforini, Paul Poloskov, Pengji Zhang,
5132 Philip Kaludercic, Pierre Téchoueyres, Przemysław Kryger, Robert 5373 Pete Kazmier, Peter Wu, Philip Kaludercic, Pierre Téchoueyres,
5133 Hepple, Roman Rudakov, Russell Sim, Ryan Phillips, Rytis Paškauskas, 5374 Przemysław Kryger, Robert Hepple, Roman Rudakov, Russell Sim, Ryan
5134 Rudolf Adamkovič, Sam Kleinman, Samuel Culpepper, Saša Janiška, 5375 Phillips, Rytis Paškauskas, Rudolf Adamkovič, Sam Kleinman, Samuel
5135 Shreyas Ragavan, Simon Pugnet, Tassilo Horn, Thanos Apollo, Thibaut 5376 Culpepper, Saša Janiška, Shreyas Ragavan, Simon Pugnet, Steve
5136 Verron, Thomas Heartman, Togan Muftuoglu, Tony Zorman, Trey Merkley, 5377 Downey, Tassilo Horn, Thanos Apollo, Thibaut Verron, Thomas
5137 Tomasz Hołubowicz, Toon Claes, Uri Sharf, Utkarsh Singh, Vincent 5378 Heartman, Togan Muftuoglu, Tony Zorman, Trey Merkley, Tomasz
5138 Foley, Zoltan Kiraly. As well as users: Ben, CsBigDataHub1, Emacs 5379 Hołubowicz, Toon Claes, Uri Sharf, Utkarsh Singh, Vincent Foley,
5139 Contrib, Eugene, Fourchaux, Fredrik, Moesasji, Nick, Summer Emacs, 5380 Zoltan Kiraly. As well as users: Ben, CsBigDataHub1, Emacs Contrib,
5140 TheBlob42, TitusMu, Trey, bepolymathe, bit9tream, bangedorrunt, 5381 Eugene, Fourchaux, Fredrik, Moesasji, Nick, Summer Emacs, TheBlob42,
5141 derek-upham, doolio, fleimgruber, gitrj95, iSeeU, jixiuf, okamsn, 5382 TitusMu, Trey, bepolymathe, bit9tream, bangedorrunt, derek-upham,
5142 pRot0ta1p, soaringbird, tumashu, wakamenod. 5383 doolio, fleimgruber, gitrj95, iSeeU, jixiuf, okamsn, pRot0ta1p,
5384 soaringbird, tumashu, wakamenod.
5143 5385
5144+ Packaging :: Basil L.{{{space()}}} Contovounesios, Eli Zaretskii, 5386+ Packaging :: Basil L.{{{space()}}} Contovounesios, Eli Zaretskii,
5145 Glenn Morris, Mauro Aranda, Richard Stallman, Stefan Kangas (core 5387 Glenn Morris, Mauro Aranda, Richard Stallman, Stefan Kangas (core