dotemacs

My Emacs configuration
git clone git://git.entf.net/dotemacs
Log | Files | Refs | LICENSE

commit 3e10447f8945623d8192a6d3d04e4092624aa81a
parent 5e2d5101ef6d5133ae42834c4ccd890ae439c7ef
Author: Lukas Henkel <lh@entf.net>
Date:   Sat, 25 Nov 2023 12:29:02 +0100

Use modus-operandi theme

Diffstat:
Aelpa/modus-themes-4.3.0.signed | 3+++
Aelpa/modus-themes-4.3.0/.dir-locals.el | 4++++
Aelpa/modus-themes-4.3.0/CHANGELOG.org | 9405+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aelpa/modus-themes-4.3.0/README-elpa | 33+++++++++++++++++++++++++++++++++
Aelpa/modus-themes-4.3.0/README.md | 33+++++++++++++++++++++++++++++++++
Aelpa/modus-themes-4.3.0/dir | 19+++++++++++++++++++
Aelpa/modus-themes-4.3.0/doc/doclicense.texi | 505+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aelpa/modus-themes-4.3.0/doc/modus-themes.info | 6278+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aelpa/modus-themes-4.3.0/doc/modus-themes.org | 5906+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aelpa/modus-themes-4.3.0/modus-operandi-deuteranopia-theme.el | 486+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aelpa/modus-themes-4.3.0/modus-operandi-theme.el | 484+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aelpa/modus-themes-4.3.0/modus-operandi-tinted-theme.el | 483+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aelpa/modus-themes-4.3.0/modus-operandi-tritanopia-theme.el | 486+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aelpa/modus-themes-4.3.0/modus-themes-autoloads.el | 60++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aelpa/modus-themes-4.3.0/modus-themes-pkg.el | 2++
Aelpa/modus-themes-4.3.0/modus-themes.el | 4237+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aelpa/modus-themes-4.3.0/modus-themes.info | 6278+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aelpa/modus-themes-4.3.0/modus-vivendi-deuteranopia-theme.el | 485+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aelpa/modus-themes-4.3.0/modus-vivendi-theme.el | 484+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aelpa/modus-themes-4.3.0/modus-vivendi-tinted-theme.el | 483+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aelpa/modus-themes-4.3.0/modus-vivendi-tritanopia-theme.el | 486+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aelpa/modus-themes-4.3.0/theme-loaddefs.el | 63+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Minit.el | 5++++-
23 files changed, 36707 insertions(+), 1 deletion(-)

diff --git a/elpa/modus-themes-4.3.0.signed b/elpa/modus-themes-4.3.0.signed @@ -0,0 +1,2 @@ +Good signature from 066DAFCB81E42C40 GNU ELPA Signing Agent (2019) <elpasign@elpa.gnu.org> (trust undefined) created at 2023-09-19T23:10:01+0200 using RSA +Good signature from 645357D2883A0966 GNU ELPA Signing Agent (2023) <elpasign@elpa.gnu.org> (trust undefined) created at 2023-09-19T23:10:02+0200 using EDDSA +\ No newline at end of file diff --git a/elpa/modus-themes-4.3.0/.dir-locals.el b/elpa/modus-themes-4.3.0/.dir-locals.el @@ -0,0 +1,4 @@ +;;; Directory Local Variables +;;; For more information see (info "(emacs) Directory Variables") + +((emacs-lisp-mode . ((indent-tabs-mode . nil)))) diff --git a/elpa/modus-themes-4.3.0/CHANGELOG.org b/elpa/modus-themes-4.3.0/CHANGELOG.org @@ -0,0 +1,9405 @@ +#+TITLE: Change log of the Modus Themes for GNU Emacs +#+AUTHOR: Protesilaos Stavrou +#+EMAIL: info@protesilaos.com +#+OPTIONS: ':nil toc:nil num:nil author:nil email:nil + +This document contains the release notes that are included in each +tagged commit on the project's main git repository: +<https://git.sr.ht/~protesilaos/modus-themes>. + +The newest release is at the top. Since the notes are meant to be in +plain text format, I copy them verbatim. + +For further details, please consult these additional resources: + ++ Manual :: <https://protesilaos.com/emacs/modus-themes> ++ Screenshots :: <https://protesilaos.com/emacs/modus-themes-pictures> + +* 4.3.0 +:PROPERTIES: +:CUSTOM_ID: h:4783bc29-3055-426d-9acb-51e4d0741871 +:END: + +** All themes except the tritanopia ones have a new hover colour +:PROPERTIES: +:CUSTOM_ID: h:b92b176e-3e9a-420d-bbbe-3c3e38b47027 +:END: + +The previous colour was not sufficiently distinct from what each theme +defines for the =bg-completion= palette entry (preview a palette with +=M-x modus-themes-preview-colors= or =M-x modus-themes-preview-colors-current=). +This would make it hard to spot the difference while, for example, +using ~vertico-mode~ in tandem with ~vertico-mouse-mode~. + +Same principle for the difference between the mouse hover and lazy +isearch highlights (e.g. in Dired or Occur buffers). + +Changing the hue here follows the same principle that underpinned the +redesign of the grey backgrounds for version 4 of the project: +depending on hardware capabilities, colour reproduction may not be +optimal, so we need to be more considerate with the choice of colour +values, erring on the side of caution. + +The ~modus-operandi-tritanopia~ and ~modus-vivendi-tritanopia~ themes +are not affected by this initiative, as they already used highly distinct hues. + +Thanks to Daniel Mendler for bringing this matter to my attention and +for testing the proposed alternatives. This was done via a private +channel and the information is shared with permission. Daniel is the +developer of ~vertico~, among many other excellent packages: +<https://github.com/minad> + +** Japanese holidays have the expected style +:PROPERTIES: +:CUSTOM_ID: h:2de9cef6-c6f1-4c2e-97ce-46d8a7306bae +:END: + +Japanese calendars style Saturdays uniquely and the Modus themes now +do the same for those who use the ~japanese-holidays~ package. +Saturdays show up in a blue colour (which changes to cyan for the +~modus-operandi-tritanopia~, ~modus-vivendi-tritanopia~ themes). + +Each theme's palette has a new semantic colour mapping called +=date-holiday-other=, just in case we ever encounter another scenario +like this one (users can override any entry in the palette---consult +the manual for the technicalities). + +Thanks to Olaf Meeuwissen for bringing this package to my attention +and showing me how traditional Japanese calendars style Saturdays. +This was done in issue 311 on the GitLab mirror: +<https://gitlab.com/protesilaos/modus-themes/-/issues/311>. + +** Each theme has semantic colour mappings for terminal emulators +:PROPERTIES: +:CUSTOM_ID: h:f3ae786a-9e01-4363-ae98-898f2ad34f7b +:END: + +These are used by ~ansi-term~, ~vterm~, and the like. The idea is to +empower users to differentiate background and foreground values, +should they ever encounter a need to do so (when in doubt, do +nothing). + +By convention, terminal emulators use the same value for both +background and foreground, although this is not optimal with high +contrast themes because what works as a foreground does not +necessarily look nice as a background. + +The default values of the new mappings retain the prior state, just to +not break existing configurations. Consider this a tacit user option +for those who really need it. + +Thanks to Tony Zorman for reporting the problem that provided the +impetus for this change: +<https://lists.sr.ht/~protesilaos/modus-themes/%3C87fs4wforf.fsf%40hyperspace%3E>. + +** All theme definitions conform with the latest standard for metadata +:PROPERTIES: +:CUSTOM_ID: h:2af0114f-b96a-4e89-ad2f-850d53538efa +:END: + +Themes are expected to declare their background type and affinity, +such that the built-in command ~theme-choose-variant~ can do what it +describes (switch between related themes). I was already doing this, +though I had to make some adjustments. This is in response to Emacs +bug#65468: <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=65468>. +Thanks to Mauro Aranda for bringing the matter to my attention. + +** Proper colours for the inline preview of the ~corfu~ top candidate +:PROPERTIES: +:CUSTOM_ID: h:89d40a68-7573-4994-9ecc-fea40c823472 +:END: + +The ~corfu-candidate-overlay~ package is used in tandem with the +~corfu~ package to create an inline preview of the first matching +candidate. Thanks to Nicolas Semrau for bringing this matter to my +attention in issue 89 on the GitHub mirror: +<https://github.com/protesilaos/modus-themes/issues/89>. + +** Context indicators for the mode-line or header-line (breadcrumb.el) +:PROPERTIES: +:CUSTOM_ID: h:dc391e85-650f-444e-b909-849d659921fb +:END: + +I added support for the new ~breadcrumb~ package by João Távora. It +displays information about where we are in the given file, such as +under which Org heading or inside which function. The indicator can +be shown on the mode-line or the header-line. Either way, it will now +be legible and consistent with its surroundings. + +** The new family of nerd-icons is covered by the themes +:PROPERTIES: +:CUSTOM_ID: h:0409d429-5307-43d6-9bf4-fabc958c2540 +:END: + +This is a new set of packages: ~nerd-icons~, ~nerd-icons-completion, +~nerd-icons-dired~, ~nerd-icons-ibuffer~. A popular package that uses +the Nerd icons is ~doom-modeline~, which the themes support as well. + +** All icons look as intended again +:PROPERTIES: +:CUSTOM_ID: h:a01075c6-b931-4b35-bdbd-2d1223101560 +:END: + +Some faces from the ~all-the-icons~ package were not configured +because I accidentally changed their name from something like +~all-the-icons-red-alt~ to ~all-the-icons-red-warmer~. I did that +while renaming the colours defined in each theme's palette, to make +them more meaningful ("warmer red" can hint at something whereas "alt +red" is more abstract). + +** Corrected the documentation about custom Org faces +:PROPERTIES: +:CUSTOM_ID: h:5c254346-370e-4510-bcc7-70a1cca2c5a0 +:END: + +The Modus themes manual shows how to configure arbitrary TODO keywords +to inherit the style of an arbitrary face (get the list of faces +present in your Emacs with =M-x list-faces-display=). The previous +value I used was faulty. It now is as intended. Thanks to +soaringbird for reporting the issue on the mailing list: +<https://lists.sr.ht/~protesilaos/modus-themes/%3CNXPVkVk--3-9%40tuta.io%3E>. + +** The colours used by =avy= are better for users with tritanopia +:PROPERTIES: +:CUSTOM_ID: h:3605693e-bd6d-40a0-a1d4-199684c89081 +:END: + +I changed the sequence of colours displayed by commands such as +~avy-goto-char-timer~ such that each individual background does not +blend with the ones adjacent to it, while respecting the overall needs +of a tritanopia-friendly design. I also tweaked the colour values to +achieve the desired result. The backgrounds remain distinct from +their context but now also work harmoniously together. + +** The =bg-dim= palette entry is marginally brighter in all Modus operandi variants +:PROPERTIES: +:CUSTOM_ID: h:8a3cb4f1-e7f8-48f1-832c-27e64b126b2d +:END: + +After extensive testing and side-by-side comparisons, I have concluded +that the marginal increase in brightness improves the affected +interfaces. + +The =bg-dim= background is used, among others, in the header-line, the +popup of the ~company~ and ~corfu~ packages, as well as the Org source +blocks (when the user option ~modus-themes-org-blocks~ is configured +appropriately). + +** The "intense" palette override preset has new colours for tables and prose metadata +:PROPERTIES: +:CUSTOM_ID: h:3a990310-337c-457f-8f40-1af6d1b557f6 +:END: + +This concerns the ~modus-themes-preset-overrides-intense~ (refer to +its documentation on how to use it). The primary target of these +changes is Org mode and the overall effect is subtle. The previous +colours did not combine nicely with all structural elements. For +example, Org clocktables would obscure timestamps by being the same +colour as them, while the table formula would not stand out. These +styles did not fit into the concept of "intense" colours. + +** The "warmer" palette override preset has more legible strings +:PROPERTIES: +:CUSTOM_ID: h:64cbd701-1344-48cc-8bcf-fc9712438013 +:END: + +The ~modus-themes-preset-overrides-warmer~ uses a more prominent warm +green value for strings in programming modes. The effect is subtle, +though it fits in better with the overall aesthetic of these palette +overrides. + +** Org document keywords like =#+author= are optionally monospaced +:PROPERTIES: +:CUSTOM_ID: h:096b75ec-802c-43e4-81ed-6db92b45654c +:END: + +When the user option ~modus-themes-mixed-fonts~ is non-nil, all Org +document keywords will be rendered with the ~fixed-pitch~ face. This +ensures consistency between keywords such as =#+author= and "meta +lines" like =#+texinfo=. Thanks to user fluentpwn for the change: it +is one line and thus the author does not need to assign copyright to +the Free Software Foundation. + +** Git commit summary lines have a more precise style +:PROPERTIES: +:CUSTOM_ID: h:2aecd902-3a0b-4544-98f4-dbb42cbad672 +:END: + +This concerns the first line in a Git commit message, as seen while +working with the ~magit~ package. Same principle for the ~log-edit~ +buffer used by the built-in VC framework. Before, I was hardcoding a +blue colour value, whereas now I apply the ~success~ face. The +~success~ face is designed to contrast with the ~warning~ face that is +used to show overlong summaries. Furthermore, the added indirection +makes it possible to particularise the colour value, which I do for +the tritanopia themes that cannot use blue. + +** Miscellaneous +:PROPERTIES: +:CUSTOM_ID: h:7391fd7d-6e70-4419-a8d6-f34d9ae075b1 +:END: + +- Removed explicit support for the built-in ~css-mode~. Its default + faces are decent. They inherit from standard font-lock faces that + the themes already cover. + +- Recalibrated wordwise ("refined") diffs for deuteranopia. The + ~modus-operandi-deuteranopia~ and ~modus-vivendi-deuteranopia~ have + a little bit more intense colour values applied to wordwise, else + "refined", diffs. These concern removed lines. The effect is + visible while using ~magit~ or the built-in ~diff-mode~. + +- Backported emacs.git commit =4cf33b6bd02b868ebbf112da7926d7c3c64517ce=. + It removed the space from the front matter of the =modus-themes.org= + file (i.e. the manual) because the Org export did not produce the + right results, per Emacs bug#64548. Thanks to Stephen Berman for + reporting the issue and making the requisite change. + +- Added support for the `erts-mode`. Thanks to Kevin Fleming for + informing me about this built-in mode. This was done in issue 85 on + the GitHub mirror: <https://github.com/protesilaos/modus-themes/issues/85>. + +- Fixed a typo in the ~modus-themes-preset-overrides-intense~ doc + string. Thanks to Nicolas Semrau for bringing this matter to my + attention. It was done in issue 90 on the GitHub mirror: + <https://github.com/protesilaos/modus-themes/issues/90>. + +- Made all commands that prompt for a theme (~modus-themes-select~, + ~modus-themes-preview-colors~) apply the =theme= category to the + available candidates. This allows the user to target said category + to affect the relevant functions. For example, to set completion + styles with ~completion-category-overrides~ or to define a custom + annotation function with the ~marginalia~ package. + +- Added support for new ~appt-notification~ face (Emacs 30). Change + upstream by me. + +* 4.2.0 +:PROPERTIES: +:CUSTOM_ID: h:29370d83-23c4-415b-afbf-ad85d4296c86 +:END: + +** I won a Google award for the Modus themes +:PROPERTIES: +:CUSTOM_ID: h:1ffc8660-511d-4fa8-aff4-11da8246a186 +:END: + +Report here: <https://protesilaos.com/codelog/2023-05-25-emacs-google-award/>. + +This is not a "change" per se, but it is worth documenting here. It +shows how important accessibility can be in empowering people to use +their computer and, in our case, to exercise their software freedoms. + +The Modus themes tend to one aspect of accessibility. They do not +exhaust the topic, though they should at least raise awareness about +the significance of tending to the usability needs of everyone. The +effort I put into documenting the themes (and my other packages) +should be understood in this light as a means of helping people enjoy +their software freedom by learning how to use and extend the program +in question. + +** New tritanopia-optimised themes +:PROPERTIES: +:CUSTOM_ID: h:b92706b0-9d53-4015-8916-9db3c0c87068 +:END: + +I have created a pair of light and dark themes that are intended for +people with blue-yellow colour deficiency (tritanopia). These are +~modus-operandi-tritanopia~ (light) and ~modus-vivendi-tritanopia~ +(dark). Screenshots of all the Modus themes are available on my +website: <https://protesilaos.com/emacs/modus-themes-pictures>. + +The entire collection is now described in the manual as follows: + +#+begin_quote +The Modus themes consist of eight themes, divided into four subgroups. + +- Main themes :: ~modus-operandi~ is the project's main light theme, + while ~modus-vivendi~ is its dark counterpart. These two themes are + part of the project since its inception. They are designed to cover + a broad range of needs and are, in the opinion of the author, the + reference for what a highly legible "default" theme should look + like. + +- Tinted themes :: ~modus-operandi-tinted~ and ~modus-vivendi-tinted~ + are variants of the two main themes. They slightly tone down the + intensity of the background and provide a bit more color variety. + ~modus-operandi-tinted~ has a set of base tones that are shades of + light ochre (earthly colors), while ~modus-vivendi-tinted~ gives a + night sky impression. + +- Deuteranopia themes :: ~modus-operandi-deuteranopia~ and its + companion ~modus-vivendi-deuteranopia~ are optimized for users with + red-green color deficiency. This means that they do not use red and + green hues for color-coding purposes, such as for diff removed and + added lines. Instead, they implement colors that are discernible by + users with deueteranopia or deuteranomaly (mostly yellow and blue + hues). + +- Tritanopia themes :: ~modus-operandi-tritanopia~ and its counterpart + ~modus-vivendi-tritanopia~ are optimized for users with blue-yellow + color deficiency. The idea is the same as with the deuteranopia + variants: color coding relies only on hues that are accessible to + people with tritanopia or tritanomaly, namely, shades of red and + cyan. +#+end_quote + +** Recalibrated the "graph" colours in all themes +:PROPERTIES: +:CUSTOM_ID: h:60bb2797-2db6-4d47-9d27-7d1f32291707 +:END: + +The new palette subset improves the contrast of all the relevant +colours when presented side-by-side. These are most notably used by +the ~org-habit~ consistency graph, which is displayed in the Org +agenda. The deuteranopia and tritanopia themes have their own bespoke +colours for this purpose, due to their specific requirements for +colour coding (e.g. they cannot use green). + +** Faces or face groups +:PROPERTIES: +:CUSTOM_ID: h:4b68159e-d998-4781-b202-74a3dcc8ae8e +:END: + +- Introduced a subtle 3D effect for clickable buttons, replacing the + previous 2D design. I realised the flat style creates ambiguity + between the button and the text fields. This happens, for example, + with =M-x customize-variable= for ~org-capture-templates~ which has + lots of button and text field combinations. The added sense of + depth helps with the usability of these buttons because it makes + them unambiguous. Personally, I prefer the 2D approach, but here we + have a trade-off between usability and aesthetics. According to + what I state in the manual: + + #+begin_quote + If there arises an inescapable trade-off between usability and + stylistic considerations, we will always opt for the former. + #+end_quote + +- Refashioned the ~whitespace-mode~ to be much more subtle and added + the concomitant semantic colour mappings. + + The previous style involved the use of a dim grey background for + each invisible character. While this is was good to spot invisible + characters quickly, it was a major hindrance for users who want to + run ~whitespace-mode~ at all times (e.g. for the Python programming + language which is space-sensitive). + + We thus remove the backgrounds by default but provide the option to + reinstate them via palette overrides (as documented at length in the + manual). To this end, we have two new semantic colour mappings for + ordinary space, its invisible characters, as well as space errors. + + Thanks to Christian Tietze and Oliver Epper for their feedback in + issue 80 on the GitHub mirror: + <https://github.com/protesilaos/modus-themes/issues/80>. + +- Applied a more subtle background for faces ~menu-bar-mode~, + ~tool-bar-mode~, ~scroll-bar-mode~. They do not need to stand out + so much because the toolkit already takes care of that. Also, we do + not want to dillute the semantic value of either ~bg-tab-bar~ or + ~fringe~ palette colour mappings that I was wrongly using before in + this context. Note that those faces may not apply, depending on the + underlying tool kit. For example, I encounter them with the Lucid + build of Emacs, though not with the GTK one. + +- Fix the critical typo of 'widget-buton', which prevented the actual + ~widget-button~ face from being affected by the themes. Thanks to + Steve Downey for pointing it out in issue 73 on the GitHub mirror: + <https://github.com/protesilaos/modus-themes/issues/73>. + +- Added support for the ~disk-usage~ package. It is made to look like + Dired, to the extent possible. Thanks to Nacho Barrientos for the + patch: <https://lists.sr.ht/~protesilaos/modus-themes/patches/39822>. + The change is small and does not require copyright assignment to the + Free Software Foundation. + +- Made the ~eglot-diagnostic-tag-unnecessary-face~ look like a + warning. By default it inherits the ~shadow~ face, which makes it + counter-intuitive as it dims the text instead of bringing it to our + attention. The intent of ~eglot-diagnostic-tag-unnecessary-face~ is + to highlight unused symbols, so this is better presented as a + warning. + + Thanks to Augusto Stoffel for bringing this matter to my attention. + This was done via a private channel and the information is shared + with permission. + +- Changed the ~smerge-markers~ to inherit from ~diff-header~ instead + of ~diff-heading~. Thanks to Steve Downey for the contribution. + This was done in pull request 74 on the GitHub mirror: + <https://github.com/protesilaos/modus-themes/pull/74>. The change + is small and does not require copyright assignment to the Free + Software Foundation. + +- Added support for the ~jinx~ package. This was originally done by + Tomasz Hołubowicz in pull request 71 on the GitHub mirror: + <https://github.com/protesilaos/modus-themes/pull/71>. The change + is small and does not require copyright assignment to the Free + Software Foundation. I then modified it to make the underlines look + like warnings instead of errors. This is because of how the package + works: it automatically highlights misspellings in the visible + portion of the buffer. There are cases where this results in a very + intense presentation, which can be distracting. We want to reduce + the overall intensity and not draw too much attention to those + highlights. + +- Extended coverage of Org to the new ~org-agenda-calendar-daterange~ + face (part of Org version 9.7). Thanks to Gautier Ponsinet for the + patch, which I received via a private channel. The change is small + and does not require copyright assignment to the Free Software + Foundation. In addition to this, I introduced a new semantic colour + mapping in the themes' palette called ~date-range~. This can be + used with the palette overrides, which are documented at length in + the manual (there are lots of copy-pastable examples as well). + +- Supported all of the new faces of the built-in ~proced~ package. + These are part of Emacs 29 and make the ~proced~ buffers more + colourful, subject to the user option ~proced-enable-color-flag~. + As always, the themes strive to avoid exaggerations, meaning that I + apply colour with restraint: not all faces need to stand out. + +- Included the ~rst-mode~ in the list of explicitly supported + packages, making its heading look like those of Org, Markdown, etc. + Thanks to David Edmondson for the patch: + <https://lists.sr.ht/~protesilaos/modus-themes/patches/40625>. I + believe David has already assigned copyright to the Free Software + Foundation, though this patch is small anyway. + +- Covered all the new faces of the built-in ~flymake~ package. These + concern the inline feedback messages (Emacs 30) as well as those + that appear in the echo area (Emacs 29). The former are subject to + the user option ~flymake-show-diagnostics-at-end-of-line~. + +- Reduced the intensity of the ~which-key~ prefix descriptions. Those + are the keymaps that displayed by ~which-key~ to hint that typing + the given key will open a new ~which-key~ page with more keys. + +- Configured new ~vundo-saved~ and ~vundo-last-saved~ faces of the + ~vundo~ package. They are designed to be easy to read, without + going over-the-top. Thanks to Nicolas Semrau for bringing this + matter to my attention in issue 79 on the GitHub mirror: + <https://github.com/protesilaos/modus-themes/issues/79>. + +- Removed the deprecated ~consult-preview-cursor~ face and made the + requisite adjustments to the ~consult~ faces. This was done in + commit =267b0c9= of the Consult Git repository. Discussed here: + <https://github.com/minad/consult/issues/764#issuecomment-1537491625>. + +- Instructed the ~shr-selected-link~ face of the built-in ~shr~ + package to use a "mark selection" style instead of the semantically + incorrect "intense red" it had before. This change is helpful for + those who override the palette of their Modus theme of choice, while + it also allows us to have varied colours depending on the + requirements of each theme (e.g. deuteranopia/tritanopia compared to + the defaults). + +- Did the same as above, mutatis mutandis, for the faces + ~transient-disabled-suffix~, ~web-mode-error-face~, + ~erc-dangerous-host-face~, ~aw-minibuffer-leading-char-face~, + ~binder-sidebar-highlight~, ~binder-sidebar-missing~, + ~image-dired-thumb-flagged~, ~image-dired-thumb-mark~, + ~info-menu-star~, ~rainbow-delimiters-mismatched-face~, + ~evil-ex-substitute-matches~, ~iedit-occurrence~, + ~iedit-read-only-occurrence~, ~pgtk-im-0~, ~dired-narrow-blink~. + +- Enhanced the ~image-dired~ mark faces with a box border, as the use + of a background alone can be obscured by the underlying image + thumbnail, depending on its figures/colours. + +- Removed the backgrounds from the ~powerline-evil~ faces and + simplified their overral presentation in the interest of + maintainability. The old styles were hard to predict and test. + There could easily be conflicts, such as if the user would override + the colours of the mode line. + +- Ensured that ~diary~ and ~holiday~ colours are distinct and legible, + without being too intense. + +** Changes to the manual or other documentation +:PROPERTIES: +:CUSTOM_ID: h:d3c12dd0-4231-420b-a212-b6bd571c5c34 +:END: + +- Updated the doc string of the primary customisation group defined by + the themes to reflect the support for the case of tritanopia. + +- Included links to the web page of the manual and the one with the + sample pictures in the customisation groups. Those links appear in + the various Custom UI buffers. + +- Introduced an annotation function for all commands that involve + minibuffer completion. The annotations display the one-line + description of each theme, making it easier for a user to pick their + preferred choice (e.g. when using the ~modus-themes-select~ + command). + +- Defined semantic colour mappings for "marks". These are used by + ~dired~, ~trashed~, ~proced~, and others. These is no change to the + default appearance of what users are already familiar with, though + it is now possible to override those styles. + +- Complemented the subset of semantic colour mappings for + errors/warnings with "prominent" variants. Those employ a + background and foreground combination. They are used in all sorts + of contexts, such as for fringe errors (~flymake~, ~flycheck~, ...), + ~query-replace~, ~isearch-fail~, and others. + +- Wrote sample code on how to add "padding" to the Emacs frame and the + space between the Emacs windows. This makes for a presentation that + some users find easier to work with. + +- Corrected the sample code for ~git-gutter~ to use the appropriate + symbols from the theme palette. Thanks to Christian Tietze for the + patch: <https://lists.sr.ht/~protesilaos/modus-themes/patches/40354>. + The change is small and does not require copyright assignment to the + Free Software Foundation. + +- Removed ~moody~ from the list of packages explicitly supported by + the themes. We stopped supporting it since version 4 that removed + the relevant user option for the mode line. The idea is that the + mode line is better handled by the user without interference from + the theme, due to the number of options available (and how brittle + those can be when interacting with unpredictable face definitions). + Thanks to Nicolas De Jaeghere for reminding me to remove ~moody~ + from the manual: + <https://lists.sr.ht/~protesilaos/modus-themes/%3Cypi9jzyclqxy.fsf%40gmail.com%3E#%3C87jzybdgg1.fsf@dejaeghe.re%3E>. + +** Miscellaneous +:PROPERTIES: +:CUSTOM_ID: h:7240990a-2b4d-442c-a15c-84c8d8b26622 +:END: + +- Added two new preset palette overrides to make the overall + presentation "warmer" or "cooler". Those are called + ~modus-themes-preset-overrides-warmer~ and + ~modus-themes-preset-overrides-cooler~, respectively. The manual + explains how those presets can be used. I suggest the user does not + add such overrides if they intend to load any of the deuteranopia or + tritanopia themes, due to the specific requirements of their design. + +- Refined the deuteranopia yellows for warnings, errors, and comments. + These otherwise slight adjustments make it considerably easier to + tell apart distinct elements that may be positioned close together. + +- Tweaked the deuteranopia semantic colour mappings for emails. The + subject line use a more appropriate colour value, while level 3 + quotes stand out a bit more than they did before, without being + needlessly intense. + +- Arranged for the ~modus-themes-load-theme~ function return the value + of the =THEME= argument it accepts. The intent is to allow other + functions that call this one to capture the return value for their + purposes (such as with a ~let~ binding). Thank to Oliver Epper for + the feedback in issue 78 on the GitHub mirror: + <https://github.com/protesilaos/modus-themes/issues/78>. + +* 4.1.0 +:PROPERTIES: +:CUSTOM_ID: h:d028f117-8a74-4c0c-b838-9f6bf2b43c19 +:END: + +** Recursive semantic colour mapping +:PROPERTIES: +:CUSTOM_ID: h:262e2f5f-4db0-4549-a5ba-4e57cd2edc6a +:END: + +Version 4 of the Modus themes changed how all colour-related +customisations are done. Instead of multiple user options with +hard-coded stylistic presets, users have access to a comprehensive +system of "named colours" and "semantic colour mappings". The former +is an association between a name, like =blue-warmer=, and a colour +value such as =#3548cf=. While semantic colour mappings are +associations between syntactic/interface constructs and named colours, +such as what value level 2 headings have. + +When overriding the palette users can now define semantic colour +mappings whose value is another such mapping. This recursion +simplifies how multiple overrides are defined. + +The manual offers extensive guidance on the topic of palette +overrides. There are many sections that include code samples that are +ready for use. + +The addition of recursive semantic colour mappings solves a problem +reported by Imran Khan on the mailing list where they were trying to +do what made sense (recursion) but the old code did not permit as +much: +<https://lists.sr.ht/~protesilaos/modus-themes/%3Cb7ca4702162fd575593f8ded28d9a888.contact%40imrankhan.live%3E>. + +I was aware of that constraint from before the release of version +4.0.0 but was hesitant to implement recursion prior to getting some +feedback on the new palette overriding feature. + +Also thanks to Christian Tietze for participating in that discussion +on the mailing list. + +** Extract an arbitrary colour from a given theme's palette +:PROPERTIES: +:CUSTOM_ID: h:6ba1437f-e55f-4c3a-9c03-b0035293b4a2 +:END: + +I formalised the function ~modus-themes-get-color-value~ and +documented it at length. It accepts a =COLOR= argument, which +represents an entry in the palette (named colour or semantic colour +value), as well as optional =OVERRIDES= and =THEME= arguments. When +=OVERRIDES= is non-nil, ~modus-themes-get-color-value~ will read from +the overrides, otherwise it will only consult the default palette +value. The =THEME= argument specifies which theme's palette to use. +In the absence of =THEME=, the current one is used. + +I already had the "get colour" functionality internally, but was +inspired to make it public after checking Sacha Chua's blog post +"Making highlight-sexp follow modus-themes-toggle": +<https://sachachua.com/blog/2023/01/making-highlight-sexp-follow-modus-themes-toggle/>. +Sacha was using a private function from the themes, which would have +been problematic if I would ever move things around. + +Remember to read the documentation of ~modus-themes-list-colors~. +That command shows a preview of the named colours. When called with a +prefix argument (=C-u= by default), it shows a preview of the semantic +colour mappings. + +** Option to disable other themes while loading Modus +:PROPERTIES: +:CUSTOM_ID: h:5af072da-38f6-44d0-9342-e799f0196006 +:END: + +In the past, we used to disable all other themes while loading a Modus +theme. I revised this for version 4 because I learnt that some users +use "themes" as bundles of arbitrary configurations. + +With the addition of the ~modus-themes-disable-other-themes~ user +option, which is non-nil by default, I am restoring the old behaviour: +when loading a Modus theme all other themes are disabled. + +This happens when the theme is loaded with the commands +~modus-themes-toggle~ and ~modus-themes-select~, or via Lisp with the +function ~modus-themes-load-theme~. + +Users who need to run multiple themes can set this option to a nil +value. (Personally, I use minor modes for such stylistic bundles and +never have to worry about ~(mapc #'disable-theme custom-enabled-themes)~.) + +Thanks to Tony Zorman for the feedback on the mailing list, which led +me to the introduction of this user option: +<https://lists.sr.ht/~protesilaos/modus-themes/%3C874jtew0gp.fsf%40hyperspace%3E#%3C87bkne84d2.fsf@hyperspace%3E>. + +** Renamed the named colours for bg-{added,changed,removed}-intense +:PROPERTIES: +:CUSTOM_ID: h:d43ef5cb-10dd-4c33-9429-2289a5fb2506 +:END: + +They are now called ~bg-added-fringe~, ~bg-changed-fringe~, +~bg-removed-fringe~. Please update any palette overrides to reflect +this renaming. + +** Documented how to override diffs for more optional combinations +:PROPERTIES: +:CUSTOM_ID: h:220d4361-7245-4632-998e-c0e2ee3b5f7d +:END: + +The manual includes details (with copy-pastable code) on how to +achieve foreground-only diffs and/or how to have red+blue diffs +instead of the default red+green or the deuteranopia yellow+blue. + +Thanks to Andrew Tropin for requesting this feature. We used to +provide this style in earlier versions of the themes, but now it is +much more flexible. Andrew's request was done via a private channel +and the information is shared with permission. + +[ Since we are here, also thanks to Andrew for keeping the Guix + package of the Modus themes up to date. ] + +** Stylistic changes +:PROPERTIES: +:CUSTOM_ID: h:fdcff629-22c1-4203-9104-4f732c59f731 +:END: + +- Guaranteed consistency between all of the line-related faces of the + ~consult~ package. We use the ~shadow~ face in all interfaces where + line numbers are contextual information (Occur, Grep,...). With + Consult, this was not the case for commands like ~consult-line~. + + Thanks to Daniel Mendler (also known as @minad) for bringing this + matter to my attention: + <https://lists.sr.ht/~protesilaos/ef-themes/%3Cb03413a6-cb77-615d-145d-db4eb710bfca%40daniel-mendler.de%3E>. + +- Refined all diff colours for fringes and reduced the saturation for + added lines in ~modus-operandi-deuteranopia~, ~modus-vivendi-deuteranopia-theme~. + Thanks to Andrew Tropin for showing me some usability issues with + the previous styles. This was done via a private channel and the + information is shared with permission. + +- Instructed the ~dashboard~ icons to retain their underlying colour. + The default value of the ~dashboard-items-face~ made all icons use + the same colour, detracting from their distinctiveness. Thanks to + Thanos Apollo for bringing this matter to my attention. It was done + via a private channel and the information is shared with permission. + +- Amplified the intensity of the =#+begin_src= text when the user + option opts for ~(setq modus-themes-org-blocks 'gray-background)~. + The text is now easier to discern. That user option makes the + inside of the block have a gray background and the begin/end lines + to have a more intense gray, giving off a "blocky" impression. + +- Made the ~compilation-warning~ face also inherit the + ~modus-themes-bold~ face. This means that it responds to the value + of the user option ~modus-themes-bold-constructs~, the same way the + other compilation-related mode line faces do. Thanks to Manuel + Giraud for informing me about the inconsistency in + ~compilation-warning~. This was done via a private channel and the + information is shared with permission. + +- Calibrated the hueness of the "nuanced" backgrounds in the + ~modus-operandi-tinted~ and ~modus-vivendi-tinted~ themes. These + tweaks are necessary to retain thematic consistency. + +- Reset ~mu4e-header-highlight-face~ to its intended style. I made a + mistake before: I did not want the ~highlight~ face to be used in + this case as it is too intense. Sorry! + +- Toned down the highlight line of the ~ctrlf~ and ~swiper~ packages. + I mistakenly used the ~highlight~ before, which is too intense for + the purposes of an ancillary background colour. + +- Applied "nuanced" backgrounds to the tinted Org blocks. This fixes + an error of mine where I amplified the background colouration of Org + blocks. This concerns the case where the user option + ~modus-themes-org-blocks~ has a =tinted-background= value. Thanks + to Mark Bestley for informing me about this in issue 60 on the + GitHub mirror: + <https://github.com/protesilaos/modus-themes/issues/60#issuecomment-1374530488>. + +- Removed the hardcoding of the ~italic~ style in three faces, opting + instead to make them subject to the user option ~modus-themes-italic-constructs~. + The faces are ~marginalia-documentation~, ~markup-attribute-face~, + and ~org-agenda-calendar-sexp~. + +- Tweaked the Org agenda deadline and today schedule to use a bold + weight only when the user option ~modus-themes-bold-constructs~ is + set to a non-nil value. Thanks to Marko Kocic for reporting an + issue that brought this matter to my attention: + + - <https://lists.sr.ht/~protesilaos/modus-themes/%3C35588839.256749.1673272214728%40office.mailbox.org%3E> + - <https://lists.sr.ht/~protesilaos/modus-themes/%3C874jszvk5g.fsf%40protesilaos.com%3E> + - <https://lists.sr.ht/~protesilaos/modus-themes/%3C87ilhfu101.fsf%40protesilaos.com%3E> + +- Enforced the main foreground colour in the faces =highlight= and + =secondary-selection=. This should have always been there to avoid + awkward colour combinations. I realised it was missing after + corresponding with Edgar Vincent on a relevant topic: + <https://lists.sr.ht/~protesilaos/modus-themes/%3C878ri95h1q.fsf%40posteo.net%3E#%3C87ilhc7usc.fsf@posteo.net%3E>. + +- Made the ~eglot-mode-line~ face conditionally bold, by subjecting it + to the user option ~modus-themes-bold-constructs~. + +- Ensure that the background of the ~company~ package's popup is the + same as that of the ~corfu~ package. This is a subtle neutral + value. + +- Fixed the hue of the ~org-habit~ "ready" faces. It should be green + and I made a mistake here. The ~modus-operandi-deuteranopia~ and + ~modus-vivendi-deuteranopia~ themes do change the underlying hues + though, as green is not suitable for them. + +- Simplified the ~keycast~ faces so that (i) they do not use a =:box= + attribute that can look awkward in some cases and (ii) the name of + the given command is not colourised to avoid exaggerations with the + use of colour. + +- Made the ~powerline-active1~ face inherit from ~mode-line~ instead + of ~mode-line-active~. The latter only exists in newer versions of + Emacs and we do not want to make the themes break in older versions. + Thanks to TitusMu for identifying this and reporting it in issue 64 on + the GitHub mirror: <https://github.com/protesilaos/modus-themes/issues/64>. + +- Decoupled all ~ediff~ faces from their ~diff-mode~ counterparts. + Ediff does not depend on ~diff-mode~, so we want to make each set of + faces stand on its own. Thanks to Bernd Rellermeyer for pointing + out this implicit dependency in issue 68 on the GitHub mirror: + <https://github.com/protesilaos/modus-themes/issues/68>. + +** Miscellaneous +:PROPERTIES: +:CUSTOM_ID: h:14d1f1b0-00e0-4275-a06c-9e34daf6411a +:END: + +- Improved the clarity and robustness of the code that does the work + of ~modus-themes-list-colors~. + +- Refined the colour value of the =blue-warmer= named colour for all + the light themes. It is a tiny bit darker than before. + +- Introduced a ~t~ fallback value for the user option + ~modus-themes-completions~. It makes it easier to apply the same + styles for the selection line and matching characters. + +- Documented how to not extend the active region background. + +- Explained how to make tabs more or less colourful by using palette + overrides. + +- Removed obsolete and redundant statements from the documentation the + user option ~modus-themes-completions~. There was (i) an outdated + reference to the =background= value, which is no longer supported, + and (ii) a statement about the standard Completions' buffer that was + not useful. Thanks to Rudolf Adamkovič for informing me about this: + <https://lists.sr.ht/~protesilaos/modus-themes/%3Cm2tu1211qz.fsf%40me.com%3E>. + +- Rephrase the statement ="*Completions* buffer"= in the documentation + in the interest of clarity. Thanks to Rudolf Adamkovič for the + suggestion: + <https://lists.sr.ht/~protesilaos/modus-themes/%3Cm2tu1211qz.fsf%40me.com%3E#%3Cm2eds43htz.fsf@me.com%3E>. + +- Updated the sample configuration of the themes with ~use-package~ in + the interest of simplicity. Thanks to Sergey Nichiporchik for the + contribution. Sergey's contribution is within the ~15 line limit + and thus does not require copyright assignment to the Free Software + Foundation. + + This was done in merge request 59 on the GitLab mirror: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/59>. + + The prepatory discussion took place in issue 310 on the same mirror: + <https://gitlab.com/protesilaos/modus-themes/-/issues/310>. + + Weeks later I further simplified the relevant samples for the sake + of uniformity with the generic package setup. Thanks to Zoltan + Kiraly for informing me about the fact that the ~:bind~ keyword + delays the load of the package until the given command is invoked: + <https://github.com/protesilaos/modus-themes/pull/67>. + + Streamlining the configuration makes it easier for me to propose one + set of basic configurations without the need to know what a + configuration macro is doing behind the scenes. + +- Fixed an example colour in the documentation. Thanks to Russell Sim + for spotting the error of me using =bg-blue= instead of + =bg-blue-intense=: + <https://lists.sr.ht/~protesilaos/modus-themes/%3Cyger0wa9gsn.fsf%40simopolis.xyz%3E>. + +- Defined the missing =modus-themes-nuanced-{red,green,yellow,blue,magenta,cyan}= faces. + Those are used internally to avoid repetition, though users can also + rely on them for their personal configurations (same for all other + Modus faces). + +- Improved the documentation on how to have a borderless mode line + style by using the palette overrides. + +- Updated the manual's entry on the ~pdf-tools~ backdrop to make it + use the new conventions that have been in place since version 4 of + the themes. Thanks to Utkarsh Singh for the patches: + <https://lists.sr.ht/~protesilaos/modus-themes/patches/37902>. + +- Add an explicit notice that the version of the themes that is built + into Emacs must use the ~require-theme~ function instead of the + familiar ~require~. Built-in themes are not considered "code", due + to old conventions, and are not part of the ~load-path~ that + ~require~ reads from. This is not up to the theme to decide. + Interested users must simply know about this important technicality. + Thanks to Koen van Greevenbroek for reporting the problem that + helped me identify this issue: + <https://lists.sr.ht/~protesilaos/modus-themes/%3C31038fd76868fa3d07c9a429dfed8fd6ac374bb8.camel%40posteo.net%3E>. + +- Clarified the wording of the ~modus-themes-with-colors~ setup for + custom faces. It explains when this macro should be called. Thanks + to user bangedorrunt for the feedback in issue 59 on the GitHub + mirror: <https://github.com/protesilaos/modus-themes/issues/59>. + +* 4.0.0 +:PROPERTIES: +:CUSTOM_ID: h:cd353ccc-daf5-4ee5-885a-b3f21be92b66 +:END: + +This is the biggest release in the history of the project. +Previously, a new version would consist of about 100 commits to the +Git repository. This one includes 400+ of them in the span of one +month. The out-of-the-box looks of the themes are largely the same as +before, though I have made a lot of internal changes that affect how +the themes are instantiated and customised. + +As part of this development cycle, I produced publications informing +users of the upcoming changes, while demonstrating the new feature of +overriding the colour palette and its semantic mappings. + +- 2022-12-03 Emacs: breaking changes coming to 'modus-themes' version 4 :: <https://protesilaos.com/codelog/2022-12-03-modus-themes-v4-development/> +- 2022-12-07 Emacs: change colour values and mappings in Modus themes version 4 :: <https://protesilaos.com/codelog/2022-12-07-modus-themes-4-colour-values-mappings/> +- 2022-12-17 Emacs: modus-themes version 4 demo [video] :: <https://protesilaos.com/codelog/2022-12-17-modus-themes-v4-demo/> +- 2022-12-28 Emacs: note for MELPA or Git users of the Modus themes ahead of version 4 :: <https://protesilaos.com/codelog/2022-12-28-note-modus-themes-4-melpa/> + +I did this in the hope of preparing users for the refactored Modus +themes, though I understand that not everyone has had the chance to +consult those entries. The general idea is that *old custom code will +not work* and most user options are either removed or confined to a +more precise scope. + +Custom code will not work because the named colours of the palettes +have changed. Many user options are made redundant by the new +overrides' system. Specifically, if an option pertains to +colouration, it is now done via overrides instead of the old method of +me hardcoding styles (e.g. for stuff like "rainbow" headings). + +More details below. This is a long entry. Please take your time to +study it before upgrading to the new version of the themes. + +** There now are six Modus themes for more legibility needs +:PROPERTIES: +:CUSTOM_ID: h:f305dd08-a713-4369-a16d-af9403ab6c22 +:END: + +Quoting from the manual's "Overview" section: + +#+begin_quote +The Modus themes consist of six themes, divided into three subgroups. + +- Main themes :: ~modus-operandi~ is the project's main light theme, + while ~modus-vivendi~ is its dark counterpart. These two themes are + part of the project since its inception. They are designed to cover + a broad range of needs and are, in the opinion of the author, the + reference for what a highly legible "default" theme should look + like. + +- Tinted themes :: ~modus-operandi-tinted~ and ~modus-vivendi-tinted~ + are variants of the two main themes. They slightly tone down the + intensity of the background and provide a bit more color variety. + ~modus-operandi-tinted~ has a set of base tones that are shades of + light ochre (earthly colors), while ~modus-vivendi-tinted~ gives a + night sky impression. + +- Deuteranopia themes :: ~modus-operandi-deuteranopia~ and its + companion ~modus-vivendi-deuteranopia~ are optimized for users with + red-green color deficiency. This means that they do not use red and + green hues for color-coding purposes, such as for diff removed and + added lines. Instead, they implement colors that are discernible by + users with deueteranopia or deuteranomaly (mostly yellow and blue + hues). +#+end_quote + +All six themes will be included in Emacs 30 (~modus-operandi~ and +~modus-vivendi~ are in Emacs since August 2020). I asked about it on +the emacs-devel mailing list and received the approval of Eli +Zaretskii, one of the Emacs maintainers. The full thread: +<https://lists.gnu.org/archive/html/emacs-devel/2022-12/msg00834.html>. + +*** New command to select one of the Modus themes +:PROPERTIES: +:CUSTOM_ID: h:e4f011c4-46d3-4e4f-ad3e-9a609ef8bd5e +:END: + +The ~modus-themes-select~ command uses minibuffer completion to load +one of the six themes in the collection. Loading a Modus theme +disables all other Modus themes. + +NOTE that Emacs can load multiple themes, which typically produces +undesirable results and undoes the work of the designer. Use the +~disable-theme~ command if you are trying other themes beside the +Modus collection. + +*** New user option to specify themes to toggle +:PROPERTIES: +:CUSTOM_ID: h:c4efdaca-505b-4724-81b4-4a5340cbcaba +:END: + +The ~modus-themes-to-toggle~ is a variable that affects the command +~modus-themes-toggle~. By default, the toggling happens between the +~modus-operandi~ and ~modus-vivendi~ themes, as was always the case. +Though with the addition of new themes, it is possible to change this +to something like: + +#+begin_src emacs-lisp +(setq modus-themes-to-toggle '(modus-operandi-deuteranopia modus-vivendi-deuteranopia)) +#+end_src + +If ~modus-themes-to-toggle~ does not specify two Modus themes, the +~modus-themes-toggle~ command will prompt with completion for a theme +among the collection (this is practically the same as the aforementioned +~modus-themes-select~ command). + +** Colour palettes and their overrides are much more powerful +:PROPERTIES: +:CUSTOM_ID: h:c20673d3-d992-4827-bd24-80329962dc8e +:END: + +In previous versions, there were options to override colour values. +Those were difficult to use as they (i) required expertise on picking +the correct values and (ii) it was not clear which colour was used +where. + +The new version broadens the colour palette to include *named colours* +and *semantic colour mappings*. Named colours are associations +between a symbol and a colour value, such as =(blue-warmer "#354fcf")=. +While semantic colour mappings apply those named colours to specific +constructs such as =(heading-2 yellow-faint)= for all level 2 headings. + +What this means is that overrides can now be targeted at semantic +mappings as well to refashion practically every aspect of the themes. +The manual provides lots of examples that can be copied and used +directly. For example, it is possible to change the sequence of +colours in headings so that, say, there is a colour-coding that +denotes depth. Links to relevant entries are included in this +document. + +The ~modus-themes-common-palette-overrides~ user option contains +entries that are shared between all the themes. While there also +exist theme-specific options such as ~modus-operandi-palette-overrides~. + +For technical insight into the palette overrides, consult the manual: +<https://protesilaos.com/emacs/modus-themes#h:34c7a691-19bb-4037-8d2f-67a07edab150>. + +For practical examples check "Stylistic variants using palette +overrides" and its subsections: +<https://protesilaos.com/emacs/modus-themes#h:df1199d8-eaba-47db-805d-6b568a577bf3>. + +** Preset overrides for faint or intense colouration +:PROPERTIES: +:CUSTOM_ID: h:5ba76bb2-9ca8-4202-aca3-31aaca239d94 +:END: + +The palette overrides are comprehensive and can be tweaked in a +detailed way. Still, users may prefer to use the presets for a +"faint" or "intense" style. These presets showcase the new feature by +styling elements that were previously not subject to configuration. +They also provide the convenience of a common set of stylistic +patterns. + +Read the "Palette override presets" section in the manual for how to +use and/or extend those: +<https://protesilaos.com/emacs/modus-themes#h:b0bc811c-227e-42ec-bf67-15e1f41eb7bc>. + +** Named colours are more meaningful +:PROPERTIES: +:CUSTOM_ID: h:94e59644-8ef8-4a46-9666-a241ba04b21a +:END: + +In the past, the variants of the main accent colours were named like: + +- =red= +- =red-alt= +- =red-alt-other= + +The improved naming scheme changes those to: + +- =red= +- =red-warmer= +- =red-cooler= + +Semantically, the "warmer" variants have more yellow or red while the +"cooler" ones have greater contribution of cyan or blue. As such, the +user can expect =green-warmer= to be an olive green and =green-cooler= +to be that of the pine (though olive trees can have blue-green +colouration and pine trees can be "warmer", but I digress). + +Named colours can be previewed with the commands +~modus-themes-list-colors~ (alias ~modus-themes-preview-colors~) and +~modus-themes-list-colors-current~ (alias +~modus-themes-preview-colors-current~). + +Those commands accept a =C-u= prefix argument, in which case they show +the semantic colour mappings. + +** Rationalisation of the colour palette +:PROPERTIES: +:CUSTOM_ID: h:cb378214-54a1-4b5b-a801-aa206b94ae38 +:END: + +In previous versions, there were a lot of named colours that were +added ad-hoc, such as =fg-special-cold= and =bg-special-calm-faint=. +There was no clear design pattern behind them, nor was it obvious +where those colours should be used. Furthermore, there were colours +that were reserved for the various permutations of user options. + +This was too complex for users who wanted/needed to refashion aspects +of the themes. It was also difficult to maintain. + +The new palettes are more streamlined and their application is more +predictable. This only matters to users who tweak the themes: it +makes their life easier, although it does render inapplicable any +previous custom code. + +** Deprecation of user options +:PROPERTIES: +:CUSTOM_ID: h:fcaa0f80-7e78-44b1-ab04-90acb0046139 +:END: + +The following subsections explain the topics in further detail. The +general idea for this change is that palette overrides provide a more +powerful, more flexible, and less complex alternative. The code base +is considerably smaller. + +With overrides, I can now provide support to cases such as: + +- Users who need different sets of greys as their monitor has + inadequate colour reproduction (this is much more common than you + think). +- Users who want to make individual elements stand out, such as to + turn the delimiters of Org source blocks (the =#+begin_src= and + =#+end_src= lines) into, say, a shade of red. +- Users who want to tone down the =TODO= and =DONE= keywords while + making headings more colourful. Or the inverse, or any combination + in-between the extremes. +- Users who want Org property drawers to be more colourful but inline + code to be faint. + +You get the idea... All these and many more are now possible. +Whereas in the past I would either have to tell people that it is not +possible or hardcode a stylistic alternative via user options, thus +further complicating the code base. + +Catering to all those use-cases is important due to the maximalist +scope of the Modus themes: I cannot tell people to use another theme, +because here is where they come for their legibility needs. This is +consistent with my experience that accessibility is not a +one-size-fits-all and that the most accessible design is that which is +flexible, ceteris paribus. + +*** ~modus-themes-intense-mouseovers~ +:PROPERTIES: +:CUSTOM_ID: h:7f4a658a-613b-4ab9-bc05-d9aa6179830b +:END: + +This user option would amplify the background colour of mouse hover +effects (technically, the ~highlight~ and ~mode-line-highlight~ +faces). It always used a blue colour. + +The same effect can now be achieved via overrides, except it is now +possible to use any background colour or level of intensity that is +provided by the themes' palette. The manual provides concrete +examples: <https://protesilaos.com/emacs/modus-themes#h:b5cab69d-d7cb-451c-8ff9-1f545ceb6caf>. + +*** ~modus-themes-org-agenda~ +:PROPERTIES: +:CUSTOM_ID: h:778abb81-4bcb-4a5c-85eb-eec9f417a443 +:END: + +This was a complex user option that was hard to test, document, and +maintain. Most aspects of the Org agenda can be affected via +overrides, as demonstrated in the manual: +<https://protesilaos.com/emacs/modus-themes#h:a5af0452-a50f-481d-bf60-d8143f98105f>. + +*** ~modus-themes-fringes~ +:PROPERTIES: +:CUSTOM_ID: h:b1ee38d7-45a0-474b-8c97-774f61462cc6 +:END: + +This user option provided two shades of grey and the option for an +invisible background for the Emacs fringe. The same and better can be +done via overrides, as shown in the manual: +<https://protesilaos.com/emacs/modus-themes#h:c312dcac-36b6-4a1f-b1f5-ab1c9abe27b0>. + +*** ~modus-themes-lang-checkers~ +:PROPERTIES: +:CUSTOM_ID: h:ad06917b-a078-48c8-97e8-1182e085a15c +:END: + +This was another complex user option that offered several stylistic +variants of dubious value. The main problem it had is that linter +highlights are often applied automatically, so any super intense style +becomes unusable. Same when a file has lots of warnings/errors. + +The semantic colour mappings I provide for this case are limited to +underlines, which I think is the most usable/legible design. The +manual provides concrete examples on how to tweak those: +<https://protesilaos.com/emacs/modus-themes#h:03dbd5af-6bae-475e-85a2-cec189f69598>. + +*** ~modus-themes-mode-line~ +:PROPERTIES: +:CUSTOM_ID: h:1b82b764-97f5-406a-8440-bae415c7d294 +:END: + +Yet another very complex user option that I removed in the interest of +maintainability. All its stylistic permutations (and more) for +colours are possible via overrides: + +- Make the mode line borderless :: <https://protesilaos.com/emacs/modus-themes#h:80ddba52-e188-411f-8cc0-480ebd75befe> +- Make the active mode line colorful :: <https://protesilaos.com/emacs/modus-themes#h:e8d781be-eefc-4a81-ac4e-5ed156190df7> + +It is also possible to add padding to the mode line, though I explain +why this was always a dirty hack: +<https://protesilaos.com/emacs/modus-themes#h:5a0c58cc-f97f-429c-be08-927b9fbb0a9c>. + +*** ~modus-themes-diffs~ +:PROPERTIES: +:CUSTOM_ID: h:dd2879a4-37c1-4ded-bc7e-24a217248961 +:END: + +I have redesigned all diff-related colours to improve their usability. +They are less intense than before, but still stand out clearly. I am +purposefully not documenting how to use overrides here as I want users +to give this redesign a try. We can always document and refine things +at a later point. + +*** ~modus-themes-subtle-line-numbers~ +:PROPERTIES: +:CUSTOM_ID: h:bcce1b94-a223-4324-b0a6-940e389819a8 +:END: + +This was a simple, but ultimately very limited option. We can do much +better with overrides because we can tweak every aspect of this +interface without making the code more complex. The manual shows how +to do it in style: +<https://protesilaos.com/emacs/modus-themes#h:b6466f51-cb58-4007-9ebe-53a27af655c7>. + +*** ~modus-themes-markup~ +:PROPERTIES: +:CUSTOM_ID: h:5eedfd24-9480-4b76-8b64-e625d3220a8d +:END: + +This was a poorly named user option that only affected inline code +elements in prose. The new semantic colour mappings provide more +points of entry and thus make it easier to tweak things to one's +liking (including tables, property drawers, source block delimiters +(the =#+begin_src= and =#+end_src= lines)), and more. The manual +shows how: +<https://protesilaos.com/emacs/modus-themes#h:bb5b396f-5532-4d52-ab13-149ca24854f1>. + +*** ~modus-themes-paren-match~ +:PROPERTIES: +:CUSTOM_ID: h:8dbe54c3-5bfc-424c-8952-f68015f6c6c4 +:END: + +The colouration of matching parentheses of the ~show-paren-mode~ can +still be affected via overrides: +<https://protesilaos.com/emacs/modus-themes#h:259cf8f5-48ec-4b13-8a69-5d6387094468>. + +*** ~modus-themes-syntax~ +:PROPERTIES: +:CUSTOM_ID: h:22910131-87bf-4c03-bbf4-aac3010b570a +:END: + +This was a user option that controlled the colouration of programming +modes. We can reproduce it with overrides, except we now also have +the freedom to adapt things further: + +- Make comments yellow and strings green :: <https://protesilaos.com/emacs/modus-themes#h:26f53daa-0065-48dc-88ab-6a718d16cd95> +- Make code syntax use the old alt-syntax style :: <https://protesilaos.com/emacs/modus-themes#h:c8767172-bf11-4c96-81dc-e736c464fc9c> +- Make use of alternative styles for code syntax :: <https://protesilaos.com/emacs/modus-themes#h:943063da-7b27-4ba4-9afe-f8fe77652fd1> + +*** ~modus-themes-links~ +:PROPERTIES: +:CUSTOM_ID: h:68d41ee9-d277-45f9-a6cd-543dac9282c8 +:END: + +The colouration of links can now be affected via palette overrides, as +documented in the manual: +<https://protesilaos.com/emacs/modus-themes#h:6c1d1dea-5cbf-4d92-b7bb-570a7a23ffe9>. + +*** ~modus-themes-region~ +:PROPERTIES: +:CUSTOM_ID: h:b97b78df-9ed9-4173-8de2-303851231e06 +:END: + +Overrides can be used to affect the region's colouration and/or to +prevent the active region highlight from changing the underlying text +colour. As always, the manual covers the details: +<https://protesilaos.com/emacs/modus-themes#h:c8605d37-66e1-42aa-986e-d7514c3af6fe>. + +*** ~modus-themes-deuteranopia~ +:PROPERTIES: +:CUSTOM_ID: h:e5fee2a1-2ace-4b4b-9aea-554d2b4a7c2d +:END: + +Instead of this rather limited option, users are advised to use the +new bespoke themes: ~modus-operandi-deuteranopia~ and +~modus-vivendi-deuteranopia~. They are designed to cater to the needs +of people with red-green colour deficiency. + +*** ~modus-themes-mail-citations~ +:PROPERTIES: +:CUSTOM_ID: h:bb8a81c5-d0c1-4150-bf7a-254d1684d95e +:END: + +All parts of an email composition buffer (per the standard +=message.el= library) are configurable via palette overrides. Not +just citation lines, but also message headers. The manual shows +several stylistic alternatives: +<https://protesilaos.com/emacs/modus-themes#h:7da7a4ad-5d3a-4f11-9796-5a1abed0f0c4>. + +Note that apart from this change, I also redesigned several faces that +affect emails. This was done in the interest of consistency and to +avoid some exaggerations. + +*** ~modus-themes-tabs-accented~ +:PROPERTIES: +:CUSTOM_ID: h:1574b5bc-d615-4053-9bbf-79396745519b +:END: + +I do not provide documentation on how to reproduce this style because +I think it was not widely used. It is possible to do it with +overrides. If anyone needs it, they are invited to contact me about +it. + +*** ~modus-themes-box-buttons~ +:PROPERTIES: +:CUSTOM_ID: h:19c81a75-a65e-49cb-83e5-c44167821865 +:END: + +All "graphical" buttons use a proportionately spaced font +(~variable-pitch~) by default as it helps with legibility. The +colours of those buttons can be changed by overriding the relevant +entries: +<https://protesilaos.com/emacs/modus-themes#h:4f6b6ca3-f5bb-4830-8312-baa232305360>. + +[ Use my ~fontaine~ package to affect fonts via faces and to apply + presets for various contexts. ] + +** Changes to remaining user options +:PROPERTIES: +:CUSTOM_ID: h:c93db0f4-1032-411a-881e-0c5fd23480cf +:END: + +*** The ~modus-themes-headings~ also affects the Org agenda +:PROPERTIES: +:CUSTOM_ID: h:c2f088b6-dc84-4285-9ece-c877be6b274f +:END: + +This user option applies to heading level 0 through 8 and also to the +agenda date and structure constructs. Here is a complete example: + +#+begin_src emacs-lisp +(setq modus-themes-headings ; read the manual's entry of the doc string + '((0 . (variable-pitch light 1.9)) + (1 . (variable-pitch light 1.8)) + (2 . (variable-pitch regular 1.7)) + (3 . (variable-pitch regular 1.6)) + (4 . (variable-pitch regular 1.5)) + (5 . (variable-pitch 1.4)) ; absence of weight means `bold' + (6 . (variable-pitch 1.3)) + (7 . (variable-pitch 1.2)) + (agenda-date . (semilight 1.5)) + (agenda-structure . (variable-pitch light 1.9)) + (t . (variable-pitch 1.1)))) +#+end_src + +*** The ~modus-themes-headings~ no longer affects colours +:PROPERTIES: +:CUSTOM_ID: h:bb0bac60-ad22-4699-9579-881431972294 +:END: + +All colour-related changes can be done via palette overrides. This +gives the user maximum flexibility on the choice of applied colours +(e.g. to have alternating contrasting foregrounds or shades of the +same hue). The manual shows several examples: +<https://protesilaos.com/emacs/modus-themes#h:11297984-85ea-4678-abe9-a73aeab4676a>. + +*** The ~modus-themes-completions~ is simpler +:PROPERTIES: +:CUSTOM_ID: h:0b29c525-7def-4149-a26b-70ca5e021a27 +:END: + +It no longer covers =popup= entries as distinct from =selection=. +This is because I revised all the applicable colours and faces to +consolidate styles. + +The =matches= and =selection= keys now read the same list of values. + +All changes to colours are done through palette overrides, as +demonstrated in the manual (again, far more flexible): +<https://protesilaos.com/emacs/modus-themes#h:d959f789-0517-4636-8780-18123f936f91>. + +*** The ~modus-themes-prompts~ is simpler +:PROPERTIES: +:CUSTOM_ID: h:7e5b9fea-b696-4e8a-bebe-a7fbb0eb460a +:END: + +This user option now only affects the typographic features of prompts. +It can read any font weight, as explained in its documentation. +Colours are influenced by semantic colour mappings in the palette and +can be overridden accordingly. The manual shows several styles: +<https://protesilaos.com/emacs/modus-themes#h:bd75b43a-0bf1-45e7-b8b4-20944ca8b7f8>. + +*** Auto-reload theme when configuring via Custom +:PROPERTIES: +:CUSTOM_ID: h:b26a2a1f-ee1e-4001-a3d0-4d4d7cb4fd5f +:END: + +The user option ~modus-themes-custom-auto-reload~ supersedes the old +~modus-themes-inhibit-reload~. It is now set to a non-~nil~ value by +default. + +We do this as a convenience for users who tweak theme settings via the +Custom UI and who do not know that all modifications to user options +require a theme re-load for changes to take effect. Read more in the +manual: +<https://protesilaos.com/emacs/modus-themes#h:9001527a-4e2c-43e0-98e8-3ef72d770639>. + +** Deprecation of public functions +:PROPERTIES: +:CUSTOM_ID: h:8167bf46-7a43-4b46-b2ed-a66e5d73bb96 +:END: + +The ~modus-themes-color~ and ~modus-themes-color-alts~ are deprecated. +Users are invited to concentrate on the ~modus-themes-with-colors~ +macro. The manual provides several examples on that front. + +The ~modus-themes-load-themes~ is no longer necessary due to the +refactoring of the code base. + +The ~modus-themes-load-operandi~ and ~modus-themes-load-vivendi~ are +superseded by the general ~modus-themes-load-theme~. It accepts the +symbol of a Modus theme as its argument. + +The command ~modus-themes-report-bug~ is no more. Just send an email +to the mailing list or to me privately. Find the information with +=M-x describe-package= and then specify =modus-themes=. +Alternatively, check my website: <https://protesilaos.com/contact>. + +** Removed support for some packages +:PROPERTIES: +:CUSTOM_ID: h:34ffc5ed-574d-44f1-8a27-c2e6bb8c69e0 +:END: + +These are the most notable packages that are no longer supported: + +- ~dired+~ +- ~lsp-mode~ +- ~helm~ +- ~treemacs~ + +The reason is that they are very hard to use for me as an outsider. +They provide lots of features, which means that I cannot easily +identify faces in their context unless I become an expert in the +relevant functionality. + +Other removed packages: + +- ~artbollocks-mode~. Use ~writegood-mode~. +- ~apropos~. Its default faces are fine. +- ~awesome-tray~. +- ~bbdb~ and ~ebdb~. They are hard to set up, but their faces are + usable. +- ~calfw~. Hard to set up and also seems to no longer be maintained. +- ~easy-jekyll~ +- ~dir-treeview~ +- ~eros~ +- ~eshell-git-prompt~ +- ~eshell-prompt-extras~ +- ~eshell-syntax-highlighting~ +- ~evil-goggles~ +- ~evil-snipe~ +- ~evil-visual-mark-mode~ +- ~fountain-mode~. I need someone who uses it to help me test it. +- ~macrostep~ +- ~mentor~ +- ~mini-modeline~ +- ~mmm-mode~. I need someone who uses it to help me test it. +- ~org-table-sticky-header~. +- ~phi-grep~ +- ~pomidor~ +- ~rainbow-blocks~. Use Adam Porter's (aka alphapapa) =prism.el=. +- ~semantic~ +- ~smartparens~ +- ~spaceline~ +- ~sx~ +- ~telephone-line~ +- ~tomatinho~ +- ~winum~ +- ~xterm-color~. + +** Thanks for their feedback on the development of version 4 +:PROPERTIES: +:CUSTOM_ID: h:bdaa3eaf-67e8-4de8-b8d5-7b11fa28dbcd +:END: + +In alphabetical order: + +- Aleksei Pirogov :: Noticed that there were no semantic colour + mappings for the ~rainbow-delimiters~ (and related), thus reminding + me to make the requisite arrangements. Aleksei also spotted a + regression during the development of the "faint" overrides' preset. + These were done on the GitHub mirror: + + - <https://github.com/protesilaos/modus-themes/issues/54> + - <https://github.com/protesilaos/modus-themes/issues/55> + +- Anders Johansson :: Pointed out some irregularities with the use of + ~make-obsolete~ in the =version-4= development branch. I should be + using ~make-obsolete-variable~ in some cases: + <https://lists.sr.ht/~protesilaos/modus-themes/%3CCAKJdtO-dzvR%3D2BaSd5qPzwDE%3D%2BaJSR6js7ii1O6KD7oFOB7gDw%40mail.gmail.com%3E> + +- Charlotte Van Petegem :: Reminded me to document how to reproduce + the old "alt-syntax" style by using palette overrides: + <https://lists.sr.ht/~protesilaos/modus-themes/%3C877cy917jw.fsf%40vanpetegem.me%3E> + +- Christian Tietze :: Spotted a bug in how shared palette overrides + would not be read in certain scenaria. Also suggested tweaks to the + documentation, which reminded me of tasks that still had to be done: + + - <https://lists.sr.ht/~protesilaos/modus-themes/%3Cm1cz81rq9m.fsf%40christiantietze.de%3E> + - <https://lists.sr.ht/~protesilaos/modus-themes/%3Cm1fscxrr0s.fsf%40christiantietze.de%3E> + - <https://lists.sr.ht/~protesilaos/modus-themes/%3Cm1ilhtrs09.fsf%40christiantietze.de%3E> + +- Daniel Mendler (aka @minad on GitHub) :: Contacted me to comment on + the general redesign. From the discussion I learnt that preset + overrides would be useful. This information is shared with + permission, as it was done via a private channel. + +- James Ferguson :: Commented on the colours of the tab-bar and thus + inspired me to define relevant semantic colour mappings: + <https://lists.sr.ht/~protesilaos/modus-themes/%3CCAMtGdSnrKDGdagT7vGC9DnBZnOvkbM%3D4Nxwn3ts2tdO8YmUnxw%40mail.gmail.com%3E> + +- Philip Kaludercic :: Opined that the ~modus-themes-inhibit-reload~ + should not be deprecated in the interest of usability. As noted + above, its functionality is preserved and now enabled by default in + ~modus-themes-custom-auto-reload~. Through the discussion we also + arrived at the concept of shared palette overrides instead of only + having theme-specific ones: + + - <https://lists.sr.ht/~protesilaos/modus-themes/%3C87h6y3gyxx.fsf%40posteo.net%3E> + - <https://lists.sr.ht/~protesilaos/modus-themes/%3C87wn6qgjkx.fsf%40posteo.net%3E> + +- Tony Zorman :: Noted that there was no clear upgrade path to + version 4. This helped me explain some of the technicalities of + packaging and of the themes' redesign, but also to update the + manual: + <https://lists.sr.ht/~protesilaos/modus-themes/%3C874jtew0gp.fsf%40hyperspace%3E>. + +- a1ks :: Reported a bug caused by the typo of an extra backtick. + This was done on the GitHub mirror: + <https://github.com/protesilaos/modus-themes/issues/53>. + +- soaringbind :: Identified some omissions in the code where I forgot + to update certain Avy and Org faces. This continued in a second + thread about the use of some obsolete faces: + + - <https://lists.sr.ht/~protesilaos/modus-themes/%3CNKXY2k1--3-9%40tuta.io%3E> + - <https://lists.sr.ht/~protesilaos/modus-themes/%3CNKd3jM_--3-9%40tuta.io%3E> + +- tumashu :: Experimented with the overrides and thus helped me + identify an area where the documentation could be improved. This + was done on the GitHub mirror: + + - <https://github.com/protesilaos/modus-themes/issues/56> + - <https://github.com/protesilaos/modus-themes/issues/57> + +- wakamenod :: Encountered a bug that was caused by a mistake of mine + that affected how themes are instantiated. This was done on the + GitHub mirror: <https://github.com/protesilaos/modus-themes/issues/50>. + +** The largest release to date +:PROPERTIES: +:CUSTOM_ID: h:54a6bcd1-6ba0-42ed-8fdd-b83ee3efee73 +:END: + +There are many more changes that I did not describe. This already +lengthy document is me covering just the headline features. The gist +is that I spent the last month refactoring and testing the themes to +ensure they can cope with the needs of users for years to come. + +I understand that the palette overrides are a new way of doing things +and that some users may be inconvenienced over the short-term as they +update their configurations. I strongly believe that this system is +better and the Modus themes can now cover all the legibility needs of +users, while also catering to their aesthetic preferences. + ++ Package name (GNU ELPA): ~modus-themes~ ++ Official manual: <https://protesilaos.com/emacs/modus-themes> ++ Change log: <https://protesilaos.com/emacs/modus-themes-changelog> ++ Colour palette: <https://protesilaos.com/emacs/modus-themes-colors> ++ Sample pictures: <https://protesilaos.com/emacs/modus-themes-pictures> ++ Git repo on SourceHut: <https://git.sr.ht/~protesilaos/modus-themes> + - Mirrors: + + GitHub: <https://github.com/protesilaos/modus-themes> + + GitLab: <https://gitlab.com/protesilaos/modus-themes> ++ Mailing list: <https://lists.sr.ht/~protesilaos/modus-themes> ++ Backronym: My Old Display Unexpectedly Sharpened ... themes + +* 3.0.0 +:PROPERTIES: +:CUSTOM_ID: h:6829db8d-52c5-43a8-a026-f213dcfaced9 +:END: + +#+begin_src text +Modus themes version 3.0.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2022-10-28 + + +The version that will ship with Emacs 29 +======================================== + +The 'modus-operandi' and 'modus-vivendi' themes (package name is +'modus-themes') have been a part of Emacs since August 2020. Emacs 28 +ships with version 1.6.0 of the themes. Emacs 29 will include version +3.0.0. + +There is no clean upgrade path from the old version of the themes to +the current one. Users are advised to review their configurations and +consult with the detailed manual of the themes. + +I am available to answer any questions, either via my personal email +or on the official sources of the themes. Find the full list here: +<https://protesilaos.com/emacs>. + + +Minor breaking changes +====================== + +I have changed the default value of the following user options: + +1. 'modus-themes-hl-line' +2. 'modus-themes-completions' +3. 'modus-themes-fringes' + +In the case of the first two, the background of the highlighted line +is made to look a bit more intense. + +For the fringes, this tweak makes them visible, using a subtle grey +colour. By default, "fringe" is an 8-pixel-wide area to the left and +right side of an Emacs window. + +The intent of these changes is to make the out-of-the-box experience +consistent with the accessibility considerations of the Modus themes. +Specifically because some users may not realise that the themes are +highly customisable. + +To revert to the old defaults, users must include this (or equivalent) +in their init file: + + (setq modus-themes-completions nil + modus-themes-hl-line nil + modus-themes-fringes nil) + +As always, changes to theme user options take effect upon a reload of +the theme. + +This was announced on my website: +<https://protesilaos.com/codelog/2022-10-23-breaking-modus-themes-3-0-0-notice/>. + + +Support for new faces or changes to existing ones +================================================= + +,* Refined the 'telega' faces for inline code and preformatted + elements. The faces are 'telega-entity-type-code' and + 'telega-entity-type-pre', respectively. This change makes them + subject to the style specified in the user option + 'modus-themes-markup'. + + Thanks to Pablo Stafforini for showing me screenshots of how they + look, as I am not a telega/telegram user and cannot do this myself. + Done as part of issue 170 on the GitLab mirror: + <https://gitlab.com/protesilaos/modus-themes/-/issues/170#note_1143975582>. + +,* Removed all attributes from the 'textsec-suspicious' face. By + default, it applies a background, but does not affect the + foreground. The result is thus inaccessible in many cases + (e.g. blue links against a red background). There is no need for + such a background though, as the warnings are accompanied by the + relevant emoji: ⚠️. + + To support this face, we need it to affect the foreground as well. + +,* Deleted some 'consult' "preview" faces in the interest of + consistency. This is to match the current style of the project: + <https://github.com/minad/consult/commit/1343e39fefcf8a28a7a415aa4b0a8ff7094370bf>. + +,* Expanded support of the built-in 'diff-mode' faces to include the + 'diff-changed-unspecified'. It is made to look the same as + 'diff-changed', i.e. yellow-tinted. There is a good chance that a + user will never see this face in action (I only encountered it + once). + +,* Reworked all the 'highlight-regexp' faces (like 'hi-yellow') to use + bespoke colour values. + + These faces need to have a background that is consistent with their + semantics. Furthermore, they need to use the 'inverse-video' + attribute which, in turn, affects the combinations of colour we can + apply. Our accented backgrounds are designed to contrast well with + our nominal main foreground values, whereas this case demands + coloured backgrounds that contrast nicely with what would normally + be the main background colour. As such, we cannot apply our + ordinary entries from each theme's palette. It would be inefficient + to expand the palette of each theme just for this edge case. + + Thanks to Kevin Kainan Li for the feedback on the mailing list, where + they informed me that the previous design was too dark/mute (and I + agreed with that assessment) and provided feedback on my samples: + <https://lists.sr.ht/~protesilaos/modus-themes/%3CCAMTq2Vp3Nnzv-i9wJdq4-OJ4X_QfWXySpUtAieBy0dgKLEOSBg%40mail.gmail.com%3E>. + +,* Recoloured the 'modus-themes-completion-match-1' to use a shade of + blue instead of cyan. This contributes to the distinctiveness of + those matches relative to 'modus-themes-completion-match-0' and the + other groups. These faces are used in completion User Interfaces, + such as 'vertico', 'corfu', 'orderless'. They are subject to the + user option 'modus-themes-completions'. + +,* Added support for the 'olivetti-fringe' face. Its background is the + same as the main background, meaning that the fringes are invisible + when 'olivetti-mode' is enabled. Thanks to Matthias Fuchs for + producing a report that helped me track this problem. It was done + in issue 46 on the GitHub mirror: + <https://github.com/protesilaos/modus-themes/issues/46>. + + +Miscellaneous +============= + +,* Added the new Emacs 29 theme properties to 'modus-operandi' and + 'modus-vivendi'. These make the themes work with the new built-in + command 'toggle-theme'. Thanks to Philip Kaludercic for the patch + and for the work on this in emacs.git: + <https://lists.gnu.org/archive/html/bug-gnu-emacs/2022-10/msg00886.html>. + +,* Refrained from deprecating the 'modus-themes-toggle' command in + favour of the new generic 'toggle-theme'. + + The 'toggle-theme' is not functionally equivalent to the command + 'modus-themes-toggle' due to the optional arguments it accepts. + With 'toggle-theme' we are prompted to confirm loading the theme, + due to how unsafe themes can be... Further, we are asked to add the + loaded theme to the list of "safe" themes. This only applies to the + packaged version of the 'modus-themes', not the items that are built + into Emacs. + + These prompts are consistent with how 'load-theme' works, but not + with what the user of 'modus-themes-toggle' has come to expect. + + Users who do not like to maintain a 'custom-file' (like me) are thus + penalised each time they invoke the command. + + The 'modus-themes-toggle' will only be deprecated if there is, say, + a user option in Emacs that disables those prompts each time a theme + is loaded. Basically, we need an arrangement that just toggles + themes without questions. + + Thanks to Rudolf Adamkovič for suggesting the idea and to Philip + Kaludercic for the 'toggle-theme' (and related functionality): + <https://lists.sr.ht/~protesilaos/modus-themes/%3C877d116lh4.fsf%40posteo.net%3E#%3Cm2lepgrd8l.fsf@me.com%3E>. + +,* Corrected the one-line description of the 'modus-vivendi' theme, + which was describing itself as a "light" theme. + +,* Ensured that the manual and all doc strings in the code use American + English, per the convention of emacs.git (my CHANGELOG still uses + what I prefer). Thanks to Stefan Kangas for contributing to this + effort with a patch that properly renders 'non-nil' in the texinfo + output as 'non-@code{nil}'. + +,* Made other minor tweaks and refinements. +#+end_src + +* 2.7.0 +:PROPERTIES: +:CUSTOM_ID: h:4d86106c-1df5-4f5f-bc6c-f14f5d13403b +:END: + +#+begin_src text +Modus themes version 2.7.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2022-10-01 + + +Support for packages or faces +============================= + +,* Reinstated support for 'centaur-tabs'. I had removed it in commit + 2235ce5 (done on 2022-08-02) for version 2.5.0 of the modus-themes. + At the time I wrote: + + centaur-tabs has a bug where it cannot read the value of a face if it + uses the standard ':inherit' attribute. I have sent a patch to fix it, + but have received no response since February: + <https://github.com/ema2159/centaur-tabs/pull/179>. + + Relevant reports: + + - <https://github.com/protesilaos/modus-themes/issues/30> + - <https://gitlab.com/protesilaos/modus-themes/-/issues/288> + - <https://github.com/protesilaos/modus-themes/issues/15> + + I am happy to reinstate support for centaur-tabs as soon as the package + gets the maintenance it needs. + + My patch/pull-request is now merged and the package is actively + maintained once again. Hence the decision to bring back support for + it, as promised. + +,* Applied styles for the 'icon-button' face of Emacs 29. + + +,* Styled the 'log-edit-headers-separator' face of Emacs 29 (it was + introduced upstream by a patch of mine). + +,* Made the 'gnus-summary-low-unread' face inherit from the 'italic' + face like the rest of that subgroup of faces. This helps + differentiate it from the 'gnus-summary-high-unread' face. Thanks + to Mark Simpson for pointing out the possibility of conflating those + two faces: <https://lists.sr.ht/~protesilaos/modus-themes/%3Cm2r0zszc2z.fsf@gmail.com%3E>. + +,* Covered the 'read-multiple-choice-face' by adding a noticeable + background colour to it. The default attributes it has, which look + like other key bindings (bold and blue) plus an underline are + technically okay, though the context of this face is in the echo + area which is one line tall. Moreover, the highlighted keys are + inlined with other text. These make it difficult to spot the + highlights without some extra spacing. I use the addition of a + background in Org's export dispatcher interface which also has some + unique requirements (the 'org-dispatcher-highlight' face). The + principle is to have theme-wide consistency (e.g. "all key bindings + must look the same") EXCEPT when the specifics require a different + set of styles in the interest of usability. + +,* Extended the coverage of the 'auctex' package's faces to include the + 'font-latex-underline-face'. Thanks to Luis Miguel Castañeda for + reporting a typo I made which caused an error: + <https://lists.sr.ht/~protesilaos/modus-themes/%3C7h7d2oudpb.fsf@imaginarymagnitude.net%3E> + +,* Added support for 'crontab-mode'. Thanks to Antonio Ruiz for the + patch: <https://lists.sr.ht/~protesilaos/modus-themes/patches/35080>. It + is below the ~15 line threshold and thus requires no copyright + assignment to the Free Software Foundation. + +,* Extended support for the 'company' package's 'company-scrollbar-bg' + and 'company-scrollbar-fg' faces. + +,* Added support for the 'spell-fu' package. Thanks to Antonio Ruiz + for the patch: <https://lists.sr.ht/~protesilaos/modus-themes/%3C87fshnq7uv.fsf%40purelymail.com%3E>. + Same as further above for Antonio's copyright status. + +,* Moved the 'selectrum-prescient' faces to the 'prescient' group, to + be consistent with changes in the respective upstream packages. + Thanks to okamsn for the contribution, which was done in pull + request 41 on the GitHub mirror: <https://github.com/protesilaos/modus-themes/pull/41>. + The user okamsn has assigned copyright assignment to the Free + Software Foundation, although this patch is within the allowed + limits. + + +Change to 'fill-column-indicator' +================================= + +Made the 'fill-column-indicator' face more noticeable. It is what the +'display-fill-column-indicator-mode' uses to draw a line on where the +'fill-column' is. + +This change is in response to private messages I received as well as +this, at parts impolite and toxic, thread that I refrained from +participating in: +<https://lists.gnu.org/archive/html/help-gnu-emacs/2022-08/msg00255.html>. + +[ I do not follow that mailing list, by the way. All my projects have + multiple communication channels and I always reply in a timely + fashion. Social media, fora about Emacs, generic mailing lists, + etc. are not among those channels. + <https://protesilaos.com/codelog/2022-07-24-report-issues-official-channels/>. ] + +The core idea is that the previous design was (1) considered +"invisible" and (2) it prevented the customisation of the user option +'display-fill-column-indicator-character'. + +I am addressing point 1, but point 2 puts us in an awkward spot as we +would then not be allowed to use a background and a height value. Not +doing so produces a dashed line by default, with the dashes further +apart the greater the line-spacing is (especially in, say, Org +headings that can have a greater height than paragraph text). It +looks broken and I keep getting requests to fix what is not the +themes' fault. So no, the themes will remain opinionated in this +regard by ignoring 'display-fill-column-indicator-character' through +the styling they apply to make the line contiguous. + +For context, also read Emacs bug#57424 and please don't take my words +in a private message out of context. If I need to state my opinion in +a public setting, I know how to do it. +<https://debbugs.gnu.org/cgi/bugreport.cgi?bug=57424>. + + +Refinement to modus-vivendi 'bg-diff-focus-removed' colour +========================================================== + +Made the default removed diff background slightly more luminant. The +colour is seen in diff-mode, ediff, and the Magit focused diff hunk. + +When the user option 'modus-themes-diffs' is set to either 'bg-only' or +'desaturated', this colour is used to highlight word-wise ("refined") +changes. The increased luminance lets it stand out more compared to the +more subtle backdrop. + +Thanks to Kévin Le Gouguec for bringing this issue to my attention and +for discussing it with me: +<https://lists.sr.ht/~protesilaos/modus-themes/%3C87bks4i9tg.fsf@gmail.com%3E> + + +Note about 'goto-address-mode' +============================== + +Quote from the manual: + + The built-in 'goto-address-mode' uses heuristics to identify URLs and + email addresses in the current buffer. It then applies a face to them + to change their style. Some packages, such as 'notmuch', use this + minor-mode automatically. + + The faces are not declared with 'defface', meaning that it is better + that the theme does not modify them. The user is thus encouraged to + consider including (or equivalent) this in their setup: + + (setq goto-address-url-face 'link + goto-address-url-mouse-face 'highlight + goto-address-mail-face 'link + goto-address-mail-mouse-face 'highlight) + + My personal preference is to set 'goto-address-mail-face' to nil, as + it otherwise adds too much visual noise to the buffer (email addresses + stand out more, due to the use of the uncommon '@' character but also + because they are often enclosed in angled brackets). + + +Changes to the manual +===================== + +,* Fixed a few typos and ensured that spelling using American English + as that is what emacs.git requires. + +,* Added the missing ':config' keywords from the example configuration + of the 'circadian' package. Thanks to Koen van Greevenbroek for the + patch: <https://lists.sr.ht/~protesilaos/modus-themes/%3C8735cb6zm3.fsf%40posteo.net%3E>. +#+end_src + +* 2.6.0 +:PROPERTIES: +:CUSTOM_ID: h:fc108f65-3e0b-4e28-8030-86c797cb2b25 +:END: + +#+begin_src text +Modus themes version 2.6.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2022-08-19 + + +Changes to supported faces or face groups +========================================= + +,* Made the 'font-lock-warning-face' adapt to comments. This changes the + face from a yellow to a red hue when the user adds a value to + 'modus-themes-syntax' which includes 'yellow-comments' property. + Before, this face was indistinguishable from yellow comments due to a + regression in version 2.5.0 of the themes. Thanks to Augusto Stoffel + and Manuel Uberti for their feedback on the mailing list: + <https://lists.sr.ht/~protesilaos/modus-themes/%3C87r11k1c22.fsf%40gmail.com%3E>. + +,* Applied a consistent foreground color (a not-so-intense yellow hue) to + the 'org-checkbox' and 'markdown-gfm-checkbox-face'. The change comes + from the discussion on the mailing list where it became apparent that + a bit of colour is needed for such constructs: + <https://lists.sr.ht/~protesilaos/modus-themes/%3Cm2fsi9cja4.fsf%40me.com%3E>. + + Thanks to Rudolf Adamkovič, Christian Tietze, and Karthik Chikmagalur + for their participation. + +,* Added support for the 'mu4e-related-face'. Thanks to Simon Pugnet for + the feedback on the mailing list: + <https://lists.sr.ht/~protesilaos/modus-themes/%3C87edxhvqwp.fsf@polaris64.net%3E>. + +,* Included support for the 'consult-preview-insertion' face. There are + two reasons for adding this: + + 1. It decouples it from the 'region' face, which means that the user + option 'modus-themes-region' no longer has an unintended effect on + it. + + 2. It makes it look consistent with the 'rectangle-preview' face (see + it in action with C-x SPC, move point down a few lines, type C-t + and then insert some text). I feel these sort of previews need to + look the same, though I don't have a strong attachment to the style + now in use. + + +Removed support for the 'solaire' package +========================================= + +The 'solaire-mode' package dims the background of what it considers +ancillary "UI" buffers, such as the minibuffer and Dired buffers. The +Modus themes used to support Solaire on the premise that the user was +(i) opting in to it, (ii) understood why certain buffers were more gray, +and (iii) knew what other adjustments had to be made to prevent broken +visuals (e.g. the default style of the 'modus-themes-completions' uses a +subtle gray background for the selection, which with Solaire becomes +practically invisible). + +However, the assumption that users opt in to this feature does not +always hold true. There are cases where it is enabled by default such +as in the popular Doom Emacs configuration. Thus, the unsuspecting user +who loads 'modus-operandi' or 'modus-vivendi' without the requisite +customizations is getting a sub-par experience; an experience that we +did not intend and cannot genuinely fix. + +[ Relevant reading about "The case of git-gutter, the modus-themes, and + Doom Emacs": + <https://protesilaos.com/codelog/2022-08-04-doom-git-gutter-modus-themes/> ] + +Because the Modus themes are meant to work everywhere, we cannot make an +exception for Doom Emacs and/or Solaire users. Furthermore, we shall +not introduce hacks, such as by adding a check in all relevant faces to +be adjusted based on Solaire or whatever other package. Hacks of this +sort are unsustainable and penalize the entire userbase. Besides, the +themes are built into Emacs and we must keep their standard high. + +The fundamental constraint with Solaire is that Emacs does not have a +real distinction between "content" and "UI" buffers. For themes to work +with Solaire, they need to be designed around that package. Such is an +arrangement that compromises on our accessibility standards and/or +hinders our efforts to provide the best possible experience while using +the Modus themes. + +As such, 'solaire-mode' is not---and will not be---supported by the +Modus themes (or any other of my themes, for that matter). Users who +want it must style the faces manually. Below is some sample code, based +on what we cover at length in the manual: + + (defun my-modus-themes-custom-faces () + (modus-themes-with-colors + (custom-set-faces + `(solaire-default-face ((,class :inherit default :background ,bg-alt :foreground ,fg-dim))) + `(solaire-line-number-face ((,class :inherit solaire-default-face :foreground ,fg-unfocused))) + `(solaire-hl-line-face ((,class :background ,bg-active))) + `(solaire-org-hide-face ((,class :background ,bg-alt :foreground ,bg-alt)))))) + + (add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) + + +Changes to the manual +===================== + +,* Added a missing parenthesis to a sample code block. Thanks to Paul + David for the contribution in pull request 39 on the GitHub mirror: + <https://github.com/protesilaos/modus-themes/pull/39>. + +,* Clarified the wording of individual statements pertaining to the need + of reloading a theme for changes to user options to become effective. +#+end_src + +* 2.5.0 +:PROPERTIES: +:CUSTOM_ID: h:32438044-6eee-4909-8e5a-860ce1457049 +:END: + +#+begin_src text +Modus themes version 2.5.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2022-08-03 + +This entry documents the changes made to the project since the +publication of version 2.4.0 on 2022-06-01. It spans more than 60 +commits to an already stable project. + +The 'modus-operandi' and 'modus-vivendi' themes are built into Emacs-28 +(latest stable release) or later, and are available on GNU ELPA as well +as other archives. Emacs-28 ships version 1.6.0, while the current +'master' branch (i.e. Emacs-29) and, by extension, GNU ELPA include the +latest tagged release. The packaged version is available as +'modus-themes'. + +Read the manual inside Emacs by evaluating: + + (info "(modus-themes) Top") + +Or visit: <https://protesilaos.com/emacs/modus-themes> (the website only +documents the latest version). + + +Enhancement to the user option 'modus-themes-headings' +====================================================== + +The user option 'modus-themes-headings' now reads a level 0 heading in +addition to numbers 1--8. Heading 0 accepts the same list of properties +as all other levels (please consult the doc string of the user option or +the corresponding entry in the manual). Currently only the value of the +Org #+title is affected (face is 'org-document-title'), but we may cover +more faces if needed. + +Sample configuration: + + ;; The `modus-themes-headings' is an alist with lots of possible + ;; combinations, including per-heading-level tweaks: read the + ;; manual or its doc string. + (setq modus-themes-headings + '((0 . (variable-pitch light (height 2.2))) + (1 . (rainbow variable-pitch light (height 1.6))) + (2 . (rainbow variable-pitch light (height 1.4))) + (3 . (rainbow variable-pitch regular (height 1.3))) + (4 . (rainbow regular (height 1.2))) + (5 . (rainbow (height 1.1))) + (t . (variable-pitch extrabold))) + +Given this change, I am also tweaking the default foreground value of +the 'org-document-title'. It is a bit more saturated than before, but +remains close to the spirit of the previous one. + +Thanks to Rudolf Adamkovič for proposing the idea on the mailing list: +<https://lists.sr.ht/~protesilaos/modus-themes/%3Cm2y1x5tewl.fsf@me.com%3E>. + + +Stylistic tweak to the user option 'modus-themes-syntax' +======================================================== + +Prevented the 'alt-syntax' property from desaturating the effect of the +'yellow-comments' property when the two would be combined. Such as: + + (setq modus-themes-syntax '(alt-syntax yellow-comments)) + +The previous design was incorrect because it was always using the faint +variant of the yellow comments, as if the user had specified: + + (setq modus-themes-syntax '(alt-syntax faint yellow-comments)) + +[ Read the doc string of 'modus-themes-syntax' or the manual for an + explanation of all properties and their combinations. ] + + +Review of the Isearch (and related) colours +=========================================== + +Emacs' standard search has a face for the currently matched query and +all its inactive matches. The faces are 'isearch' and 'lazy-highlight', +respectively. Before, we were using a green background by default for +the 'isearch' face and a cyan background for the 'lazy-highlight'. This +was a choice that was made in the early days of the project when the +palette was not yet fully realised. + +Green and cyan do not always contrast well side-by-side (subject to +hardware capabilities and environmental lighting), so the 'isearch' face +also had an added bold weight. This was not my preference, but it was +necessary under the circumstances. The previous combinations were also +not ideal when the user option 'modus-themes-deuteranopia' was set to a +non-nil value: the blue background which was used instead of the green +one could be conflated with the subtle teal of the 'lazy-highlight' +under certain circumstances, such as poor colour reproduction at the +monitor level or in terminal emulators with limited colour support. + +The new colours (intense yellow for active matches and subtle cyan for +lazy ones) are complementary, meaning that they are naturally easy to +tell apart. + +[ Read "Colour theory and techniques used in the Modus themes": + <https://protesilaos.com/codelog/2022-04-21-modus-themes-colour-theory/> ] + +These specific hues are also well-suited for users with red-green colour +deficiency: yellow stays as-is, while the cyan colour becomes a bit more +grey though remains distinct. As such, we do not need to run the helper +function 'modus-themes--deuteran' to set the style based on the value of +'modus-themes-deuteranopia'. + +The new colours do not clash with the style of the relevant 'match' face +(used by 'M-x occur', 'M-x grep', and related), nor with the various +permutations of the 'region' face (subject to the user option +'modus-themes-region'). + +Finally, the bold weight has been removed from the 'isearch' face. It +was always a kludge. Also, it would make paragraphs rendered in the +'variable-pitch' face (or proportional fonts in general) jump around as +the user would move between the matches, because bold letters occupy +more space than their regular weight counterparts so they affect the +length of the line. This problem was reported by Augusto Stoffel on the +mailing list: <https://lists.sr.ht/~protesilaos/modus-themes/%3C87sfnbswe9.fsf@gmail.com%3E>. + + +Rewrote parts of the colour preview commands +============================================ + +The 'modus-themes-list-colors', 'modus-themes-list-colors-current' are +commands that produce a buffer which shows previews of every entry in +the palette. Their code has been simplified and they now produce a +warning when the display terminal has limited colour support. +Furthermore, they read any overrides as specified in the user options +'modus-themes-operandi-color-overrides', 'modus-themes-vivendi-color-overrides'. + + +The "summertime" re-spin of colour overrides +============================================ + +The manual now includes a complete hand-crafted example of a pair of +themes that override the default palette. This is done as a technology +demonstration. It is not considered an "official" extension of the +Modus themes and will never be part of the code base as it does not +conform with our lofty accessibility standards. However, I took great +care in picking the colour overrides in the hope that users will (i) +have a usable theme, should they opt for it, and (ii) they recognise the +potential of our colour-overriding feature. + +Screenshots and related information: +<https://protesilaos.com/codelog/2022-07-26-modus-themes-color-override-demo/>. + +Thanks to user “Summer Emacs” for (i) suggesting the name “summertime”, +(ii) testing variants of this in her setup, and (iii) sending me +feedback on possible tweaks and refinements. All errors are my own. + +The idea for this project came from an exchange where Summer discovered +an old theme of mine (from my pre-Emacs days) and asked if I had +anything like it for Emacs. Voilà! + +[ This information is shared with permission. ] + +As for whether I have more plans... "Perhaps!" ;) + + +Removed support for certain packages or face groups +=================================================== + +I periodically install and use the packages we support to see if they +have any updates we need to cover but also to confirm that they work. +Usually, the user does not learn about this work, as I don't need to +make any changes or will make some minor tweaks. When I think that the +package is not in a good shape, I remove it from the list of explicitly +supported packages, meaning that the modus-themes no longer cover the +faces it defines. The removal of any package is done on a case-by-case +basis. If you disagree with this decision, please inform me about and I +shall reconsider. + +,* centaur-tabs :: Those of you who have been reading these release notes + are aware of a bug in centaur-tabs which basically prevents us from + using the standard ':inherit' attribute to style the centaur-tabs + faces. I have sent a patch to fix it, but have received no response + since February: <https://github.com/ema2159/centaur-tabs/pull/179>. + To me, this gives the package the "unmaintained" status, though I am + happy to revert the change as soon as it gets the maintenance it + needs. + + Relevant reports (and I got many others in my private inbox): + + - <https://github.com/protesilaos/modus-themes/issues/30> + - <https://gitlab.com/protesilaos/modus-themes/-/issues/288> + - <https://github.com/protesilaos/modus-themes/issues/15> + +,* cursor-flash :: its default face should be visible enough. + +,* dynamic-ruler :: The package does not build on my Emacs 29. Also, its + default faces are usable even without our recolouring. + +,* emacs-dashboard :: Its default faces inherit from basic faces that we + already support. + +,* frog-menu :: I have not seen this package being used anywhere. I + suspect it is because it has not found a niche between transient, + hydra, and embark. + +,* mct :: A few months ago I announced that its development is + discontinued. Either use vertico or switch to what Emacs provides as + a built-in option: <https://protesilaos.com/codelog/2022-04-14-emacs-discontinue-mct/>. + +,* org-treescope :: The package points to a GitHub repo, which is + archived. The current source is on GitLab, but the package is not + updated accordingly. This makes me believe it is not actively + maintained and am thus removing it from the list. + +,* paradox :: When I tried paradox, it took over my C-c g binding which I + have for Magit. As an Emacs user, I consider this an unacceptable + transgression. Looking at paradox's git repo, the project is not + maintained. If things change, I am happy to reinstate support for it. + +,* vc-annotate (built-in) :: It has not been working properly for a long + time now. Colours are unset and are not re-applied when switching + between the 'modus-operandi' and 'modus-vivendi' themes. + + Furthermore, the way 'vc-annotate-color-map' intersects with + 'vc-annotate-background-mode' puts us in an awkward spot: when the + mode is non-nil, the mapped values are used as backgrounds WITHOUT + giving us the chance to make the appropriate adjustments to the + foreground (so we end up with inaccessible colour combinations). This + means that we must fix a problem which is not ours by overriding the + user option of the background altogether. A theme outright disabling + user options is bad form. + + Even documenting a user-level set of configurations will not suffice, + as the results are unreliable. I tried the code which I copy further + below to test annotation with/without background, plus the change in + values when switching between modus-operandi and modus-vivendi. + Again, colours are not updated properly (I know the buffer of 'M-x + vc-annotate' needs to be generated again), as 'modus-operandi' may + retain the values set by 'modus-vivendi' or vice-versa. + + Ultimately, I feel 'vc-annotate' needs to be refactored to use + ordinary faces in ordinary ways. Or, at least, not try to outsmart + the user/theme about the choice of colours. + + Thanks to Philip Kaludercic for starting the thread about the + 'vc-annotate-background-mode' which reminded me about this problem: + <https://lists.sr.ht/~protesilaos/modus-themes/%3C875ylfxkgi.fsf@posteo.net%3E>. + + The code I alluded to: + + (setq vc-annotate-background-mode nil) + + (defun my-modus-themes-vc-annotate () + ;; Actual values are for demo purposes + (modus-themes-with-colors + (if vc-annotate-background-mode + (setq vc-annotate-background bg-alt + vc-annotate-color-map + `((20 . ,red-intense-bg) + (40 . ,red-subtle-bg) + (60 . ,red-refine-bg) + (80 . ,yellow-intense-bg) + (100 . ,yellow-subtle-bg) + (120 . ,yellow-refine-bg) + (140 . ,magenta-intense-bg) + (160 . ,magenta-subtle-bg) + (180 . ,magenta-refine-bg) + (200 . ,cyan-intense-bg) + (220 . ,cyan-subtle-bg) + (240 . ,cyan-refine-bg) + (260 . ,green-intense-bg) + (280 . ,green-subtle-bg) + (300 . ,green-refine-bg) + (320 . ,blue-intense-bg) + (340 . ,blue-subtle-bg) + (360 . ,blue-refine-bg))) + (setq vc-annotate-background nil + vc-annotate-color-map + `((20 . ,red) + (40 . ,magenta) + (60 . ,magenta-alt) + (80 . ,red-alt) + (100 . ,yellow) + (120 . ,yellow-alt) + (140 . ,fg-special-warm) + (160 . ,fg-special-mild) + (180 . ,green) + (200 . ,green-alt) + (220 . ,cyan-alt-other) + (240 . ,cyan-alt) + (260 . ,cyan) + (280 . ,fg-special-cold) + (300 . ,blue) + (320 . ,blue-alt) + (340 . ,blue-alt-other) + (360 . ,magenta-alt-other)))))) + + (add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-vc-annotate) + + +Revised supported faces or face groups +====================================== + +,* Enhanced the default background colour of the current date in the Org + agenda. This is a subtle change, all things considered, which makes + it easier to discern where the highlight is while it remains close to + the spirit of the previous design. The idea is to not add too much + saturation here, because the buffer is already "busy" with lots of + highlights. Thanks to Daniel Mendler for the feedback on the mailing + list: <https://lists.sr.ht/~protesilaos/modus-themes/%3C3d8b1096-a7db-1e08-fefe-d39bed4a7ea3@daniel-mendler.de%3E>. + +,* Restyled the 'M-x man' and 'M-x woman' faces to have a bit more + saturation. A while ago I desaturated the 'Man-overstrike' and + 'woman-bold' faces on the premise that the added bold weight would be + sufficient. However, the bold weight may sometimes not draw the + desired attention, such as at small point sizes or with certain font + configurations. As such, the added intensity in colour is necessary. + +,* Changed the Selectrum quick key faces ('selectrum-quick-keys-match' + and 'selectrum-quick-keys-highlight') to have the same style as Avy, + Vertico's own "quick keys", and related. For a technical analysis, + read "Modus themes: case study on Avy faces and colour combinations": + <https://protesilaos.com/codelog/2022-04-20-modus-themes-case-study-avy/>. + +,* Made internal adjustments so that 'M-x list-packages' inherits from + the standard 'success', 'warning', and 'error' faces instead of adding + its own face attributes. In practice, the user will notice a change + for new packages in the listing if 'modus-themes-deuteranopia' is + non-nil. + +,* Introduced the same inheritance rules as above for the 'syslog' + package (mutatis mutandis). + +,* Increased the saturation of the 'package-status-available' face, which + is shown in the 'M-x list-packages' buffer. The overall effect is + subtle, though sufficiently noticeable. + +,* Revised the faces of the 'deft' package to make it look consistent + with the rest of the theme's relevant interfaces (to the extent + possible as Deft uses a non-standard presentation). + +,* Aligned the 'speedbar-highlight-face' with the user option + 'modus-themes-intense-mouseovers'. + +,* Refined the 'highlight-thing' face (see package of the same name). + This makes it stand out more and it also aligns it with the standard + 'match' face, which is pertinent here. + +,* Amplified the saturation of the 'dired-git-info' face. Makes it + easier to differentiate the Git commit text from the Dired listing, + without drawing too much attention to itself. + +,* Adjusted the hue of the 'easy-jekyll-help-face' from teal to blue. + This makes it look more like the standard 'help-key-binding' face, + although 'easy-jekyll' does not align with upstream Emacs in this + regard. + +,* Intensified the background of 'rectangle-preview' to work even in + cases where a grey background is already on display. This face is + used for the 'string-rectangle' command (e.g. C-x SPC to draw a + rectangle and C-t to insert text in its stead---works as a simple + "multiple cursors" on a straight line). + + +Support for new faces or face groups +==================================== + +,* chart (built-in) +,* denote +,* edmacro-label (Emacs 29) +,* info+ +,* leerzeichen + +A comment on 'info+'. As is the case with PACKAGE+ packages from the +Emacs Wiki, info+ defines lots of faces that hardcode colour values +instead of inheriting from basic faces. It does so for no good reason +and the results will likely not look decent in any theme. Furthermore, +these faces colourise too much even when the colour values can be +appropriately combined (ceteris paribus), making the buffer harder to +read. + +The support I add for info+ is consistent with the design principles of +the modus-themes, one of which is to avoid exaggerations as those +indirectly affect legibility. As such, some of the changes I introduce +here outright remove colouration, while others align the various +constructs with the overall aesthetic of the themes. + +Note that, by default, info+ adds clickable buttons to glossary terms. +This produces awkward combinations such as by buttonising the "string" +component inside of what actually is a function's argument. So you +have, say, FORMAT-[STRING] where "[]" represents the button: the FORMAT +gets one face and the [STRING] another, even though they are part of a +single argument. To me this looks broken and is counter-productive, +though it is not up to the theme to decide how packages fontify the +various constructs. At any rate, button styles at the theme level are +controlled by the user option 'modus-themes-box-buttons'. + +Thanks to Jonas Collberg for the feedback in issue 33 over at the GitHub +mirror: <https://github.com/protesilaos/modus-themes/issues/33>. + + +Miscellaneous +============= + +,* Named the mailing list address as the =Maintainer:= of Denote. + Together with the other package headers, they help the user find our + primary sources and/or communication channels. This change conforms + with work being done upstream in package.el by Philip Kaludercic. I + was informed about it here: + <https://lists.sr.ht/~protesilaos/general-issues/%3C875ykl84yi.fsf%40posteo.net%3E>. + +,* Addressed byte compilation warnings in doc strings pertaining to the + use of literal quotes. Thanks to Matt Armstrong and Rudolf Adamkovič + for the feedback on the mailing list: + <https://lists.sr.ht/~protesilaos/modus-themes/%3C87bktlvgyy.fsf@rfc20.org%3E>. + +,* Fixed the ':link' value in the declaration of the user options + 'modus-themes-operandi-color-overrides', 'modus-themes-vivendi-color-overrides'. + It once again directs to the correct heading in the manual. + +,* Documented all the aforementioned, where necessary. + +,* Mentioned my 'fontaine' and 'lin' packages in the relevant sections of + the manual. The former helps set fonts and switch between font + presents. The latter is a stylistic variant of hl-line (its + documentation explains its raison d'être). +#+end_src + +* 2.4.0 +:PROPERTIES: +:CUSTOM_ID: h:ee0dcce9-3481-4533-8ded-a9a1f5269a41 +:END: + +#+begin_src text +Modus themes version 2.4.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2022-06-01 + +This entry documents the changes made to the project since the +publication of version 2.3.0 on 2022-04-01. It spans more than 60 +commits to an already stable project. + +The 'modus-operandi' and 'modus-vivendi' themes are built into Emacs-28 +(next stable release) or later, and are available on GNU ELPA as well as +other archives. Emacs-28 ships version 1.6.0, while the current +'master' branch (i.e. Emacs-29) and, by extension, GNU ELPA include the +latest tagged release. The packaged version is available as +'modus-themes'. + +Read the manual inside Emacs by evaluating: + + (info "(modus-themes) Top") + +Or visit: <https://protesilaos.com/emacs/modus-themes>. + + +Migration to SourceHut +====================== + +The sources of the project are as follows: + +- Git repo on SourceHut: <https://git.sr.ht/~protesilaos/modus-themes> + - Mirrors: + - GitHub: <https://github.com/protesilaos/modus-themes> + - GitLab: <https://gitlab.com/protesilaos/modus-themes> +- Mailing list: <https://lists.sr.ht/~protesilaos/modus-themes> + +- Official manual: <https://protesilaos.com/emacs/modus-themes> +- Change log: <https://protesilaos.com/emacs/modus-themes-changelog> +- Colour palette: <https://protesilaos.com/emacs/modus-themes-colors> +- Sample pictures: <https://protesilaos.com/emacs/modus-themes-pictures> + +It is still possible to open issues on either of the mirrors and I will +handle them in a timely fashion, though I encourage you to at least try +the mailing list workflow---it is ordinary email (just remember to +"reply to all"). + +Further reading that is relevant to SourceHut: + +- Moving all my Emacs projects to SourceHut: + <https://protesilaos.com/codelog/2022-04-07-all-emacs-projects-sourcehut/> + +- Primer on formatting Git patches with Emacs (Magit): + <https://protesilaos.com/codelog/2022-04-09-simple-guide-git-patches-emacs/> + + +Problems with byte compilation on Emacs 29 +========================================== + +For some time between mid-April to mid-May, users of Emacs 29 could not +byte compile the Modus themes. This has now been fixed in emacs.git, +per bug#55414: <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=55414>. +Thanks to everyone involved (A-Z): Alan Mackenzie, Eli Zaretskii, Lars +Ingebrigtsen, Mattias Engdegård, Stefan Monnier. + + +Messages about invalid face attributes while using the centaur-tabs +=================================================================== + +I mentioned this issue in the previous change log as well: upstream does +not allow us to use indirection in faces (the ':inherit' attribute). +This is not our bug. It is standard behaviour for themes to use +inheritance. + +I have an open pull request on the matter (since 2022-02-24): +<https://github.com/ema2159/centaur-tabs/pull/179>. + +Relevant reports: + +- <https://github.com/protesilaos/modus-themes/issues/30> +- <https://gitlab.com/protesilaos/modus-themes/-/issues/288> +- <https://github.com/protesilaos/modus-themes/issues/15> + + +Support for new faces or face groups +==================================== + +Directly supported +------------------ + +These are packages whose faces we override to make them work with the +themes. + +- 'calibredb'. I have tried to limit the wanton use of colour in the + relevant buffers and also align the package with the overall style of + the themes. The currently selected line is affected by the user + option 'modus-themes-hl-line'. + + Thanks to Ivan Popovych for the feedback on the official mailing list: + <https://lists.sr.ht/~protesilaos/modus-themes/%3C87zgkgroi7.fsf%40gmail.com%3E>. + + Ivan also introduced some new faces to 'calibredb', which I helped + test. See: <https://github.com/chenyanming/calibredb.el/pull/60>. + +- 'ein' (Emacs IPython Notebook). We support its code blocks with the + appropriate colouration, while avoiding exaggerations. Thanks to + Maxime Tréca for the feedback in issue 31 over at the GitHub mirror: + <https://github.com/protesilaos/modus-themes/issues/31>. + +- 'tree-sitter'. My intent was to reduce the overall colouration + produced by the default 'tree-sitter' faces. These tweaks give us + good results, though there still are some cases where 'tree-sitter' + exaggerates the styles it uses, such as by combining types with + constants to produce ad-hoc (anonymous) faces. We cannot do anything + about anonymous faces at the theme level. As such, we may get an + additional bold weight (when 'modus-themes-bold-constructs' is + non-nil) when we would rather not have it and/or a different colour + than the one desired. + + Thanks to Przemysław Kryger for the feedback in issue 303 over at the + GitLab mirror: <https://gitlab.com/protesilaos/modus-themes/-/issues/303>. + + If you are involved in the 'tree-sitter' project, please eliminate all + anonymous faces and replace them with symbols (i.e. defface) that are + editable by the user/theme. You are welcome to contact me if you need + help/ideas. + +- 'vundo' + + +Indirectly supported +-------------------- + +These are packages that either (i) inherit from base faces we already +support, or (ii) use colours from the Modus themes' palette. A list of +them is available in the manual. + +- egerrit. an in-development package by Niklas Eklund which provides an + Emacs interface to Gerrit: <https://git.sr.ht/~niklaseklund/egerrit>. + + +Changes to supported face +========================= + +- Reworked the internal functions that handle the styling of diffs to + allow the user option 'modus-themes-deuteranopia' to combine with the + styles of the 'modus-themes-diffs' option. + + Before, when 'modus-themes-deuteranopia' was non-nil it would affect + diffs by forcibly applying the default style of 'modus-themes-diffs' + (fairly prominent background colours) with the primary difference of + replacing greens with blues. + + Now all combinations work as expected. For example: + + (setq modus-themes-deuteranopia t + modus-themes-diffs 'desaturated) ; nil, 'desaturated, 'bg-only + + Thanks to Kevin Le Gouguec for the feedback on the mailing list: + <https://lists.sr.ht/~protesilaos/modus-themes/%3C878rqt4jhm.fsf@gmail.com%3E> + +- Conducted a major (and highly demanding) review of the colours used by + Avy in the interest of optimising the contrast between its constructs. + Read the analysis: <https://protesilaos.com/codelog/2022-04-20-modus-themes-case-study-avy/>. + + Thanks to Daniel Mendler and Damien Cassou for their feedback on the + mailing list: + + - <https://lists.sr.ht/~protesilaos/modus-themes/%3C83f18e2e-d726-0248-72f5-95e896cbcf4c%40daniel-mendler.de%3E> + - <https://lists.sr.ht/~protesilaos/modus-themes/%3C87czhgt5nm.fsf%40cassou.me%3E> + +- Updated the 'vertico-quick' faces to be consistent with Avy. + +- Made the 'line-number' face conform with the user option + 'modus-themes-mixed-fonts'. This means that if the user option is + non-nil, line numbers of 'display-line-numbers-mode' will use a + monospaced typeface at all times (inheriting the 'fixed-pitch' face, + as explained in the themes' manual). Otherwise they use whatever font + the 'default' face has. This makes it better when the user enables + 'variable-pitch-mode' but still wants spacing-sensitive constructs to + remain monospaced. + + Thanks to Christopher League for the feedback in issue 302 over at the + GitLab mirror: <https://gitlab.com/protesilaos/modus-themes/-/issues/302>. + +- Aligned the regexp construct faces with the meaning of the user option + 'modus-themes-bold-constructs'. They will use a bold weight only when + the user option is non-nil. This design is consistent with all other + aspects of syntax highlighting. These specific faces were + unconditionally bold due to a mistake of mine. + + Remember to check the manual on what "a bold weight" means, as we make + everything easy to customise (e.g. if you prefer a semibold weight): + <https://protesilaos.com/emacs/modus-themes#h:2793a224-2109-4f61-a106-721c57c01375>. + +- Removed the typographic emphasis from the 'file-name-shadow' face by + no longer inheriting the 'italic' face. Thanks to Nicolas De Jaeghere + for the patch. + + [ Nicolas has assigned copyright to the Free Software Foundation. ] + +- Stopped using the 'inverse-video' face attribute in 'powerline'. We + now apply the colours directly. The reason is that 'inverse-video' + makes it tricky to override the face as it swaps the foreground with + the background. That behaviour is only needed in special cases: + 'powerline' is not one of them. + + Thanks to Thibaut Verron for the feedback in issue 305 over at the + GitLab mirror: <https://gitlab.com/protesilaos/modus-themes/-/issues/305>. + +- Ensured that git commit/rebase comments (as seen in the workflow of + the 'magit' package) inherit from appropriate font-lock faces. This + makes it possible to customise 'font-lock-comment-face' and have the + changes apply to those elements as well. Such a customisation can, + for example, involve the change of the font family or the addition of + a background colour. We want the whole comment block, including those + special keywords from Git, to look consistent. This change also makes + git-{commit,rebase}-comment-heading attain the foreground colour of + comments, instead of the default one (black or white), making it look + part of the comment block. + +- Tweaked the 'fountain' package comments to be the same as all others. + This avoids inconsistencies, such as when the user opts for something + like the following: + + (setq modus-themes-syntax '(yellow-comments)) + +- Disabled padding in the 'keycast' package, meaning that the box around + the key indicator always has the same height, even if the user opts + for a padding value in 'modus-themes-mode-line' (read the manual or + its doc string for how to assign a padding). + + This is in response to a change upstream that introduces the + 'keycast-tab-bar-mode', which re-uses the faces that were originally + intended for the mode line in the tab-bar. Ideally, upstream will + provide distinct faces for each context so that we can have padding in + the mode line but not the tab-bar. However, I have not had the + opportunity to suggest such a change and/or prepare the relevant patch + (it is not straightforward). + +- Refined some colour combinations for the "alternative syntax" style + that is available when the user option 'modus-themes-syntax' includes + the 'alt-syntax' property. These tweaks pertain to changes in hue + that improve the appearance of certain faces in their context. + +- Enabled conditional use of 'fixed-pitch' for key bindings. This + happens when the user option 'modus-themes-mixed-fonts' is non-nil + (all spacing-sensitive elements become monospaced even if the user + opts for a default font that is proportionately spaced or activates + the 'variable-pitch-mode'). Thanks to Manuel Giraud for the patch. + + [ Manuel has assigned copyright to the Free Software Foundation. ] + +- Covered the face rotation option of 'highlight-changes-mode'. It is + done with the 'highlight-changes-rotate-faces' command when + 'highlight-changes-mode' is enabled (the mode is built into Emacs). + + Thanks to Philip Kaludercic for the feedback on the mailing list: + https://lists.sr.ht/~protesilaos/modus-themes/<878rs14il4.fsf@posteo.net> + + +Updates to the manual +===================== + +- Acknowledged Andrew Tropin as one of the contributors to the Guix + package of the Modus themes. The latest patch to that end: + <https://issues.guix.gnu.org/55268>. + +- Rewrote the note on 'fill-column-indicator' to show how the user can + use a thicker line than the one we style by default. + +- Wrote a note in manual about 'php-mode' multiline comments which use + the 'font-lock-doc-face' instead of 'font-lock-comment-face'. Sample + code is provided to ensure consistency between all types of comments. + +- Added note about custom 'hl-todo' colours, specifically the user + option 'hl-todo-keyword-faces' (which the themes customise as an + exception to the rule, otherwise the default colours would not always + be accessible). + + This is in relation to the mailing list thread on the matter with + feedback from Vincent Foley and Christian Tietze: + <https://lists.sr.ht/~protesilaos/modus-themes/%3C871qwh1r88.fsf%40era.co%3E>. + +- Elaborated on the style of 'git-gutter' faces in Doom Emacs, which are + not as the Modus themes intend. Basically, the problem is that Doom + changes the way that package draws its bitmaps: the faces we configure + no longer appear as intended and sensitive colouration is lost. + + Thanks to Gonçalo Marrafa for reporting the issue, testing the code we + recommend on Doom Emacs, and suggesting the inclusion of the reference + to the 'after!' call (a macro that Doom defines). + + +Miscellaneous +============= + +- Dedicated the colours of the Modus themes---just the colours---to the + public domain. The Emacs package as a whole is still distributed + under the terms of the GNU General Public License. The announcement: + <https://protesilaos.com/codelog/2022-05-10-modus-themes-palette-cc0/> + +- Stopped using a timestamp in the modus-themes.el file. It could lead + to situations where there was a mismatch between the latest change and + the recorded time. It also introduced a barrier to entry for + contributors, as they need to set up 'time-stamp.el'. + +- Removed the unnecessary 'require' call to the 'seq' library and made + the necessary changes. Thanks to Daniel Mendler for the patch. + + [ Daniel has assigned copyright to the Free Software Foundation. ] + +- Applied the correct order of inheritance for all markup faces. This + fixes a problem where not all typographic attributes where applied to + the faces when 'modus-themes-mixed-fonts' was non-nil and the value of + 'modus-themes-markup' included '(bold italic)'. + +- Tweaked how 'org-date' conditionally uses 'fixed-pitch'. Basically, + we remove an internal stylistic inconsistency. There is no + user-facing change. Thanks to Manuel Giraud for the patch. + +- Implemented the command 'modus-themes-report-bug'. It might help + users find the email address of the mailing list and get started with + the email-centric workflow of SourceHut. Note this is but a first + step in that direction. If you think it can be improved, please + report as much (or send a patch). + +- Included the command 'modus-themes-version', which prints in the echo + area the current version of the package. With an optional prefix + argument, it inserts the string at point. + + The version either is the last tagged release, such as '2.4.0', or an + in-development version like '2.5.0-dev'. As we use semantic + versioning, tags of the '2.4.1' sort are not considered: those would + count as part of '2.5.0-dev'. +#+end_src + +* 2.3.0 +:PROPERTIES: +:CUSTOM_ID: h:f95fb7e2-fcc8-43f6-bde5-27fe51b1bdd5 +:END: + +#+begin_src text +Modus themes version 2.3.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2022-04-01 + +This entry documents the changes made to the project since the +publication of version 2.2.0 on 2022-02-23. It spans more than 70 +commits. + +To access the URL of the manual visit: +<https://protesilaos.com/emacs/modus-themes>. Or read it in the Emacs +Info reader by evaluating: + + (info "(modus-themes) Top") + +The 'modus-operandi' and 'modus-vivendi' themes are built into Emacs-28 +(next stable release) or later, and are available on GNU ELPA as well as +other archives. Emacs-28 ships version 1.6.0, while the current +'master' branch (i.e. Emacs-29) and, by extension, GNU ELPA include the +latest tagged release. + + +Customisation options +===================== + +,* The 'modus-themes-completions' now accepts a 'text-also' property for + the 'selection' key. This has the effect of colourising the current + line's text. Whereas the default does not change the text colour, + re-using whatever underlying colours are available. Consult the doc + string of this user option, as it provides for fine-grained control of + how completion UIs may look. Thanks to Morgan Willcock whose feedback + in issue 278 inspired me to add the 'text-also' property: + <https://gitlab.com/protesilaos/modus-themes/-/issues/278>. + +,* The 'modus-themes-box-buttons' now accepts an 'all-buttons' property. + It applies whatever other style is used for the boxed buttons to the + generic 'widget.el'. By default, the faces of 'widget.el' do not look + like graphical buttons: they have a bold weight and a foreground + colour instead. Examples where those are used are the Notmuch "hello" + buffer and the main view of the 'elfeed-summary' package. Thanks to + Daniel Mendler, Rudolf Adamkovič, and Tony Zorman for their feedback + in issue 296: <https://gitlab.com/protesilaos/modus-themes/-/issues/296>. + +,* The 'modus-themes-intense-mouseovers' is a boolean user option which + makes mouse hover effects more intense when set to a non-nil value. + By default, mouseovers use a cyan background value. This changes it + to a more prominent blue. Thanks to John Haman for the feedback in + issue 290: <https://gitlab.com/protesilaos/modus-themes/-/issues/290>. + +,* The user options 'modus-themes-box-buttons', 'modus-themes-mode-line', + 'modus-themes-org-agenda', and 'modus-themes-headings' can now read a + number value as a cons cell. The old method of a plain number + continues to work. This makes it possible to be more descriptive on + what a given value signifies. Each doc string describes the + technicalities. Here are samples that yield identical results: + + (setq modus-themes-mode-line '(accented 0.9 borderless 2)) + (setq modus-themes-mode-line '(accented (heigh 0.9) borderless (padding 2))) + + Thanks to Daniel Mendler for proposing this idea in issue 282: + <https://gitlab.com/protesilaos/modus-themes/-/issues/282#note_842257619> + + +Attempted bug fix for byte compiled files +========================================= + +Quoting from the git log: + + commit f067d2ef39c22174b95584f2cba7942aaf03bcca + Author: Protesilaos Stavrou <info@protesilaos.com> + Date: Thu Mar 3 06:52:31 2022 +0200 + + Reify themes with eval-and-compile + + This is an attempt to fix a bug that has existed since version 1.2.0 of + the themes or even earlier. + + The bug is about a mismatch between compiled code and runtime + dependencies. The runtime expects the current version while the + compiled code only furnishes an outdated one, thus resulting in an + error. This only happens when: + + 1. Private functions change to accept more/fewer arguments. + 2. Variables change their acceptable value (e.g. from symbol to list). + 3. The user is installing the package via the package.el mechanism which + takes care of byte compilation (though anything that mimics + package.el should exhibit the same behaviour). + + My understanding is that the cause was the limited scope of the + 'eval-and-compile' we had before: it would run the 'require' also at + compile time, whereas the 'modus-themes-theme' macro, which reifies the + actual theme, would only be evaluated at runtime. Hence the mismatch as + 'require' would read the already installed byte code while the macro + would expect newer forms. + + Wrapping everything in the 'eval-and-compile' should address this + problem. Hopefully it will not engender new ones... + + ,* * * + + The latest reports about this bug: + + ,* GitLab issue 287 with Mark Bestley and Daniel Mendler: + <https://gitlab.com/protesilaos/modus-themes/-/issues/287>. + + ,* GitHub issue 22 with Rytis Paškauskas: + <https://github.com/protesilaos/modus-themes/issues/22>. + + doc/modus-themes.info | 30 +++++++++++++++--------------- + doc/modus-themes.org | 15 ++++++++------- + modus-operandi-theme.el | 10 +++++----- + modus-vivendi-theme.el | 10 +++++----- + 4 files changed, 33 insertions(+), 32 deletions(-) + +After nearly one month, no problem has been observed as a result of this +change. + + +Newly supported packages +======================== + +These are added to the already comprehensive coverage we guarantee. + +Directly supported: + +,* devdocs. Thanks to Augusto Stoffel, its developer, for the feedback + which was sent via email. + +,* mini-modeline. Thanks to Julio C. Villasante for the feedback in + issue 24 over at the GitHub mirror: + <https://github.com/protesilaos/modus-themes/issues/24>. + +Indirectly supported (they use faces that we already cover): + +,* elfeed-summary +,* undo-hl + + +Changes to supported faces or packages +====================================== + +,* Improved the colours used by 'avy' to always guarantee constrast in + hueness between side-by-side characters with a variety of user + settings. I tried various styles, such as: + + (setq avy-style 'pre) + (setq avy-style 'at-full) + + For the sake of completeness, I also ran tests by modifying the + 'avy-lead-faces' (which is a 'defconst', not a 'defcustom'): + + (setq avy-lead-faces + '(avy-lead-face + avy-lead-face-0 + avy-lead-face-2 + avy-lead-face + avy-lead-face-0 + avy-lead-face-2)) + + (setq avy-lead-faces + '(avy-lead-face + avy-lead-face-1 + avy-lead-face-1 + avy-lead-face-1 + avy-lead-face-1)) + + (setq avy-lead-faces + '(avy-lead-face + avy-lead-face-2 + avy-lead-face-2 + avy-lead-face-2 + avy-lead-face-2)) + +,* Updated the 'vertico-quick' faces to keep them aligned with the new + Avy styles. Thanks to Daniel Mendler (Vertico's developer) for the + reminder: + <https://gitlab.com/protesilaos/modus-themes/-/commit/404a9658196debdde95a51148fc62c5b2faccfb9#note_856454659>. + +,* Applied warmer though still not saturated colours for Org clocking + overlays. The previous style could be mistaken for a mouse highlight + or the highlighted line if 'modus-themes-hl-line' included the + properties 'intense' and 'accented'. Thanks to Rudolf Adamkovič for + the feedback in issue 293: + <https://gitlab.com/protesilaos/modus-themes/-/issues/293>. + +,* Broadened coverage of the built-in 'shr.el' library to include the new + 'shr-code' face (Emacs 29). + +,* Expanded support for the 'embark' package by covering its new + 'embark-collect-marked' face. Thanks to Daniel Mendler for the + feedback in issue 299: + <https://gitlab.com/protesilaos/modus-themes/-/issues/299>. + +,* Made the 'fill-column-indicator' a contiguous line. It was a dashed + line before, per the Emacs defaults, which led to awkward results + depending on the font family and value of 'line-spacing'. Thanks to + Daniel Mendler for the feedback in issue 297: + <https://gitlab.com/protesilaos/modus-themes/-/issues/297>. + +,* Added explicit support for the built-in 'separator-line' face in order + to refine its presentation. This is present in 'M-x shortdoc' buffers + (Emacs 28). Thanks to Daniel Mendler for the feedback in issue 297: + <https://gitlab.com/protesilaos/modus-themes/-/issues/297>. + +,* Applied explicit styling to the generic 'underline' face in order to + ensure its consistent colouration. The problem before was that an + underline that spanned text with distinct colours would inherit the + colour of the affected character. A uniform presentation makes + everything easier to read. + +,* The 'ement.el' Matrix client now uses a subtle background for username + mentions and/or quoted text. This is consistent with how other Matrix + clients style such constructs. Thanks to Adam Porter (aka + "alphapapa"), the developer of ement.el, for explaining the + technicalities and providing the relevant feedback in issue 25 over at + the GitHub mirror: <https://github.com/protesilaos/modus-themes/issues/25>. + +,* Enforced consistency between 'icomplete' and 'ido'. The first match + was coloured differently in 'ido-mode' by mistake. Thanks to Morgan + Willcock for the feedback in issue 278: + <https://gitlab.com/protesilaos/modus-themes/-/issues/278>. + +,* Used the main foreground for Company's tooltip. This is how it should + have been. Corfu is designed that way as well. Thanks to user okamsn + for the feedback in issue 278: + <https://gitlab.com/protesilaos/modus-themes/-/issues/278>. + +,* Corrected an omission whereby the AUCTeX verbatim face was not + consistent with other such faces. Now it too is governed by the user + option 'modus-themes-markup'. + +,* Fixed the 'centaur-tabs' invalid background message. Thanks to + Lennart C. Karssen for reporting the bug in issue 288: + <https://gitlab.com/protesilaos/modus-themes/-/issues/288>. Note, + however, that the problem is due to some decisions made upstream. My + patch has not been merged yet (open since 2022-02-24): + <https://github.com/ema2159/centaur-tabs/pull/179>. Given this + opportunity, always anticipate that faces may ':inherit' from others + and thus functions like 'face-background' might return an undesirable + nil value if used without a fallback. + + +Miscellaneous +============= + +,* Made the 'modus-themes--current-theme' return the first Modus theme + instead of the 'car' of 'custom-enabled-themes'. This makes the + themes work at all times even when the user has multiple of them + enabled. Thanks to Pierre Téchoueyres for the patch, which was sent + via email with regard to Emacs bug#54598: + <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=54598>. + +,* Implemented compile-time requirement for built-in libraries to be sure + that the themes work in all cases. Thanks to Antonio Hernández Blas + for reporting in issue 292 the bug with the old design that assumed + the 'cl-lib' and 'subr-x' as already loaded: + <https://gitlab.com/protesilaos/modus-themes/-/issues/292>. + +,* Wrote in the manual how to achieve a monochrome style (with + permutations) for code syntax highlighting. Thanks to Augusto Stoffel + for sharing the idea via an email exchange (this information is + divulged with permission). + +,* Clarified some statements in the manual's section about the nuances in + "enabling" and "loading" a theme. + +,* Documented how the applicable palette affects the outer boundaries of + the colour range that terminal emulators set when Emacs is ran without + a GUI. Here "the palette" refers to the relevant 16 ANSI escape + sequences (terminal colours 0 through 15). For the sake of + convenience, the node includes ready-to-use palettes for XTerm, which + can be adapted to other terminal emulators. This entry complements an + existing one on improving the colour accuracy in terminal emulators. + +,* Used American English constructions in a few places such as "color" + instead of "colour" as that is what core Emacs expects (and the themes + are part of emacs.git). + +,* Updated the description of the themes to be more user-friendly. + Instead of "Highly accessible themes (WCAG AAA)" we now have "Elegant, + highly legible and customizable themes". Nothing changes in terms of + substance. Thanks to Jorge Morais for the feedback. + +,* Clarified that the version of the themes which is built into Emacs + does not use 'require'. It is in response to this thread: + <https://lists.gnu.org/archive/html/help-gnu-emacs/2022-03/msg00049.html>. + Thanks to Philip Kaludercic for bringing the issue to my attention. + +,* Improved the code samples that show how to set up the package. + +,* Wrote the correct symbols for some obsoletion forms. + +Thanks once again to everyone involved! +#+end_src + +* 2.2.0 +:PROPERTIES: +:CUSTOM_ID: h:251849ee-3328-48c7-af5f-d1d6daca3a97 +:END: + +#+begin_src text +Modus themes version 2.2.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2022-02-23 + +The present entry records the changes made to the project since the +publication of version 2.1.0 on 2022-02-17. This spans about 10 commits +(though one of them is massive). Normally the release cycle occurs over +periods of 4-5 weeks. This is a necessary exception. + +To access the URL of the manual visit this web page: +<https://protesilaos.com/emacs/modus-themes>. Or read it in the Emacs +Info reader by evaluating this form: + + (info "(modus-themes) Top") + +The 'modus-operandi' and 'modus-vivendi' themes are built into Emacs-28 +(next stable release) or later, and are available on GNU ELPA as well as +other archives. Emacs-28 ships version 1.6.0, while the current +'master' branch (i.e. Emacs-29) and, by extension, GNU ELPA include the +latest tagged release. + + +Initialisation of user options +============================== + +Removed a superfluous default value that hampered the initialisation of +defcustom forms in the M-x customize interface. Things would still +work, but the interface was not looking right while editing the relevant +variables. Thanks to Gustavo Barros for reporting the bug in issue 267: +<https://gitlab.com/protesilaos/modus-themes/-/issues/267>. + + +Refactor 'modus-themes-completions' +=================================== + +Implemented thoroughgoing reforms across all completion User Interfaces +(UIs) in order to make them more flexible/powerful and harmonise their +looks. + +'modus-themes-completions' now accepts an alist instead of a symbol. +Each cons cell is in the form of '(key . list-of-properties)'. The doc +string describes all the details. + +In terms of out-of-the-box appearences, all completion UIs have a subtle +aesthetic. This was always the case for the likes of Vertico, Icomplete +(Fido), and related, though it constitutes a marked departure from what +Ivy and Helm used to look like. Users of the latter two can still get +the more colourful or intense style with something like this: + + (setq modus-themes-completions '((matches . (background intense)) + (selection . (accented intense)) + (popup . (accented intense)))) + +Or simply: + + (setq modus-themes-completions '((t background intense accented))) + +The documentation explains all those associations in-depth. There also +are other styles on offer (and combinations thereof). + +Furthermore, the new 'modus-themes-completions' encompasses more UIs +than its predecessor, including Company and Corfu. + +In the interest of theme-wide consistency, all applicable faces have +been reviewed. + +Finally, note that the previous tagged release also made changes on this +front, but it did not disrupt the status quo that was in place from +before the release of version 1.0.0 of the themes (more than a year +ago). In other words, it tried to make unnecessary compromises within +the confines of an outdated design that did not fit in with the rest of +the code base. The new 'modus-themes-completions' might require manual +intervention from users who want to customise things to their liking, +though I feel this change is to our long-term benefit. + +Thanks to Daniel Mendler and Rudolf Adamkovič for their feedback in +issue 278: <https://gitlab.com/protesilaos/modus-themes/-/issues/278>. +And thanks to Kenta Usami for recommending the use of a warning in issue +286: <https://gitlab.com/protesilaos/modus-themes/-/issues/286>. + + +Miscellaneous changes +===================== + ++ Removed the pseudo-button effect from the 'org-checkbox' face. It was + not up-to-date with the current style of the rest of the themes, + including the Org constructs for source block delimiters, the TODO + keywords, the priority cookies (e.g. '[#A]'), and others. + ++ Introduced a section in the manual which provides an alternative to + the standard 'modus-themes-toggle' that leverages 'enable-theme' + instead of 'load-theme' under the hood. These technicalities are all + explained in the manual. + ++ Provided an alternative greyscale palette subset for 'modus-operandi' + in the manual's section about overriding colours. + ++ Added support for the built-in 'custom-variable-obsolete' face. + ++ Fixed typo in the 'modus-themes-box-buttons' variable. Thanks to + Illia Ostapyshyn for the patch in merge request 58: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/58>. +#+end_src + +* 2.1.0 +:PROPERTIES: +:CUSTOM_ID: h:15098250-7b41-404b-86e1-9a99984976b9 +:END: + +#+begin_src text +Modus themes version 2.1.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2022-02-17 + +The present entry records the changes made to the project since the +publication of version 2.0.0 on 2021-12-24. There have been more than +110 commits in the meantime (and this log is close to 5000 words). + +All modifications of colour combinations mentioned herein are made in +accordance with the primary accessibility objective of the themes for a +minimum contrast ratio of 7:1 between background and foreground values +in their given combination (the WCAG AAA standard for relative colour +luminance). Edits also account for colour-coding that is optimised for +the needs of users with red-green colour deficiency (deuteranopia). + +To access the URL of the manual visit this web page: +<https://protesilaos.com/emacs/modus-themes>. Or read it in the Emacs +Info reader by evaluating this form: + + (info "(modus-themes) Top") + +The 'modus-operandi' and 'modus-vivendi' themes are built into Emacs-28 +(next stable release) or later, and are available on GNU ELPA as well as +other archives. Emacs-28 ships version 1.6.0, while the current +'master' branch (i.e. Emacs-29) and, by extension, GNU ELPA include the +latest tagged release. + + +Commands +======== + +The following produce a buffer that previews the colour palette of the +given theme ('modus-operandi' or 'modus-vivendi'). + +,* 'modus-themes-list-colors' prompts for a theme before producing the + preview. + +,* 'modus-themes-list-colors-current' uses the current Modus theme. + +These commands are useful to anyone who wants to reference a named +colour from the themes or copy a colour value, such as for the purposes +of user-level customisation (as documented at length in the manual +across several use-cases and with the inclusion of custom code). + +The commands are not bound to any key. + + +Customisation options +===================== + +,* Implemented the 'modus-themes-markup' variable, which supersedes the + now-deprecated 'modus-themes-intense-markup'. The new user option + accepts a list of properties (symbols). It affects constructs such as + Org's =verbatim=, ~code~, and macro (with three pairs of braces). By + default, when this user option is either nil or an empty list, the + affected constructs only have a foreground colour (e.g. Org verbatim + is magenta). Properties that change this style are: + + 1. 'italic' for an added slant to the text. + 2. 'bold' for a heavier weight. + 3. 'background' to add a background colour. + 4. 'intense' to amplify the colouration (especially of 'background'). + + As with all user options which accept a list of properties, the order + of the symbols is no significant. In user configurations it may look + like this: + + (setq modus-themes-markup '(background intense bold)) + + [ Read the manual for bold and italic fonts. We do not hardcode a + :weight or :slant, instead giving the user the option to set their + own values. The defaults are what you would normally expect from + "bold" and "italic". ] + + Thanks to Rudolf Adamkovič for reporting some problems with the old + design in issue 274: + <https://gitlab.com/protesilaos/modus-themes/-/issues/274>. + +,* Added the 'modus-themes-box-buttons' which affects all pseudo + graphical buttons, such as those found in Custom UI buffers or EWW web + pages which include search forms and the like. The variable accepts a + list of properties as its value. By default (nil or empty list), + buttons have a grey background and the familiar 3D effect. Valid + properties are: + + 1. 'flat' to remove the 3D effect. + 2. 'accented' to shift the colouration away from grey. + 3. 'faint' to reduce the overall colouration (e.g. grey becomes white). + 4. 'variable-pitch' to apply a proportionately spaced font. + 5. 'underline' to draw a line instead of applying a 3D or flat box + (particularly useful for those who use Emacs in a terminal emulator). + 6. The symbol of a font weight, such as 'bold', 'semibold', 'light' or + any one among those included in the 'modus-themes-weights' constant + (the underlying font family has to support the given weight). + 7. A number, expressed as a floating point (e.g. 0.9), which adjusts + the height of the button’s text to that many times the base font + size. The default height is the same as 1.0, though it need not be + explicitly stated. + + The order in which those symbols appear in the list is not + significant. If 'underline' and 'flat' are both specified, the former + takes precedence. In user init files the form may look like this: + + (setq modus-themes-box-buttons '(variable-pitch flat semilight 0.9)) + + Thanks to Daniel Mendler for suggesting this user option and providing + the relevant feedback in issue 282: + <https://gitlab.com/protesilaos/modus-themes/-/issues/282>. + +,* Expanded the 'modus-themes-mail-citations' with an 'intense' variant. + For example: + + (setq modus-themes-mail-citations 'intense) + + The default is a moderately coloured style. Other variants include + 'faint' for subtle colouration and 'monochrome' for an all-grey look. + +,* Reviewed the 'modus-themes-completion' option and harmonised all the + face specifications it governs. The variable now accepts a fourth + stylistic variant in 'super-opinionated': it is like the 'opinionated' + one though some details are even more pronounced. Other noteworthy + items: + + [ Remember to read the doc string of 'modus-themes-completions', which + explains the grouping of the completion UIs. ] + + - The (setq modus-themes-completions 'moderate) style is more-or-less + the same across all completion UIs. The highlight applied to the + current line is a bespoke shade of blue, the characters are less + saturated than before and their hues are different, though the + overall effect should still feel "sufficiently colourful, but not + overdone". + + - The (setq modus-themes-completions nil) is the same as before. + However: + + - The current line in Ivy now uses a shade of blue that is + specific to completion UIs instead of an intense cyan + background. This is for theme-wide consistency. + + - Helm's current line has the same bespoke blue for its current + line instead of another shade of blue it was using before. + + - The (setq modus-themes-completions 'opinionated) should be the same + as before, notwithstanding the aforementioned tweaks to Ivy/Helm. + + - The (setq modus-themes-completions 'super-opinionated) for + Icomplete, Vertico, Selectrum, Mct uses the same blue for the + current line as is the default of Ivy and Helm. + + Miscellaneous: + + - The relevant private helper functions were rewritten. + + - We declare a few faces to help streamline certain styles. + + - Ivy action keys now inherit from 'modus-themes-key-binding'. We + generally try to make all keys look the same, except when that would + be detrimental to the usability of the given context/interface. + + - Some Ivy faces are simplified or otherwise tweaked to fit in with + the rest of the theme. + + Thanks to Rudolf Adamkovič for the feedback about Vertico in issues + 214 and 278 which prompted me to review all completion UIs: + + - <https://gitlab.com/protesilaos/modus-themes/-/issues/214> + - <https://gitlab.com/protesilaos/modus-themes/-/issues/278> + +,* Adjusted the applicable hues in some 'modus-themes-syntax' variants. In + particular: + + - The strings' hue has more hints of blue when 'modus-themes-syntax' + includes the 'green-strings' property. Such as: + + (setq modus-themes-syntax '(green-strings)) + (setq modus-themes-syntax '(alt-syntax green-strings)) + (setq modus-themes-syntax '(alt-syntax green-strings faint)) + (setq modus-themes-syntax '(alt-syntax green-strings faint yellow-comments)) + + - Strings are more orange/yellow than red when 'modus-themes-syntax' + includes the 'alt-syntax' property but NOT the 'green-strings'. For + example: + + (setq modus-themes-syntax '(alt-syntax)) + (setq modus-themes-syntax '(alt-syntax yellow-comments)) + (setq modus-themes-syntax '(alt-syntax yellow-comments faint)) + + - Backslashes for regexp constructs are coloured appropriately to look + distinct from the rest of the string and from the escaped construct in + all cases. + +,* Removed background colours from the the default style of Org block + delimiters. + + As I explained in Emacs bug#52587,[1] Org has code that overrides + themes which prefer not to extend the block delimiter faces to the + edge of the window (as we would like to do by default). This + practically means that we cannot have backgrounds for those lines and + keep them limited to the stretch of area covered by their text. + + As such, the default for Org block delimiter lines now is a gray + foreground with no distinct background colour. The user option + 'modus-themes-org-blocks' provides "blocky" alternatives that use + background colours---those extend to the edge of the window. + + [1] <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=52587#46> + +,* Deleted the compatibility layer for all user options that used to + accept symbols in the past but now expect a list of symbols. The + manual contains a snippet with all customisation options for those who + do not want to read all the relevant doc strings. Evaluate this: + + (info "(modus-themes) Customization Options") + + Or visit: <https://protesilaos.com/emacs/modus-themes#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f>. + + The original plan was to remove those during the transition to version + 2.0.0 (about a month ago) though I changed my mind thinking they would + not pose a longer-term problem. + + New information by Mark Bestley in issue 272 shows that this kind of + complexity can lead to errors: + <https://gitlab.com/protesilaos/modus-themes/-/issues/272#note_826725412>. + + So it is better to keep things simple and ask users to configure all + user options based on the up-to-date documentation. + + Also thanks to Saša Janiška for the feedback in issue 272. + + +New packages, faces, or face groups +=================================== + +,* all-the-icons-dired. + +,* all-the-icons-ibuffer. + +,* 'child-frame-border' face (Emacs 28). + +,* 'citar' package. Thanks to Rudolf Adamkovič for the feedback in issue + 280: <https://gitlab.com/protesilaos/modus-themes/-/issues/280>. + +,* 'elisp-shorthand-font-lock-face' (Emacs 29). Read the manual by + evaluating: + + (info "(elisp) Shorthands") + +,* 'ement' (ement.el) Matrix client, though it is not listed in any + archive yet: <https://github.com/alphapapa/ement.el>. + + Thanks to Samuel Culpepper for the feedback in issue 279: + <https://gitlab.com/protesilaos/modus-themes/-/issues/279>. + + Also check the Ement issue tracker on the matter: + <https://github.com/alphapapa/ement.el/issues/53>. + +,* 'mct' package. + +,* 'menu' face (built-in) which is used in the menu-bar when Emacs runs + without a graphical toolkit. + +,* 'pgtk-im-0' face (Emacs 29). This is shown as a single-character-long + block when you type the Compose key followed by the composable + characters. + +,* 'pyim' (an input method for CJK characters). Thanks to Yuanchen Xie for + the contribution in merge request 57: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/57>. + The patch is small and is thus excluded from the requirement for + copyright assignment to the FSF (remember that the themes are built + into Emacs and any major contribution needs such copyright + assignment---read the relevant entry in the themes' manual). + +,* 'slime' and 'sly' packages. Thanks to John Haman for the feedback + which was done via email due to some problems with the web UI on + GitLab (this information is shared with permission). Please note that + I am not familiar with Common Lisp and could not test these + thoroughly. Any mistakes or omissions are my own. + + Concerning the web UI, there is a fully functional mirror of the + themes on GitHub, while email is always an option. Use whatever works + for you to report an issue or send a patch. + +,* 'textsec' package (Emacs 29). + +New indirectly supported packages +--------------------------------- + +These inherit from base faces and look good enough already or use +appropriate colours from the Modus themes: + +,* dtache +,* org-remark + + +Changes to supported faces or face groups +========================================= + +,* Stopped making key bindings look like boxes. We revert to the old + style we were using before the introduction of the 'help-key-binding' + face (Emacs 28). + + By default Emacs 28 or higher will render all key bindings it + identifies with a box around them. The idea is to make them look like + keys on a keyboard, which I never really liked because without + generous padding you get a very tight space between the character and + the box's borders which can look weird at small point sizes (Emacs + faces do not have padding in the same way CSS does). + + I tried following the default style for a few months and have concluded + that it is not good enough for our purposes (my preferences + notwithstanding): + + - The box attribute does not work in terminal emulators. This means + that keys only get a subtle grey background and the default + foreground, which can be hard to make them stand out from their + surrounding text if the font height is small and/or the keybinding is + short (e.g. a single character). + + - The box and grey background combination limits our options when we + need to colour-code different types of keys. For example, the + 'which-key' package can show TAB as T and applies to it a different + face to make the distinction obvious. In that case, the presence of + the tight box makes the use of a bold weight inappropriate: the + character and the box's borders seem to overlap. While the grey + background limits our choice of colour as, for instance, yellow + never looks good against it. Same principle for interfaces that can + have colour-coded keys like 'transient' and 'hydra', where we lose + much-needed flexibility. + +,* Adjusted the brightness of the 'which-key-special-key-face'. This is + the face that applies to special keys. For example: + + (setq which-key-special-keys '("SPC" "TAB" "RET" "ESC" "DEL")) + +,* Made 'transient' faces which are supposed to be de-emphasise certain + elements inherit the 'shadow' face. This is an implicit customisation + option, as it allows the user to adjust the foreground value of all + "less important" constructs simply by changing the 'shadow' face. + +,* Covered the 'transient-purple' face (these are like the colour-coding + of 'hydra'). + +,* Tweaked the 'transient-argument' and 'transient-value' faces to make + things look a bit more consistent with the other transient faces. + This is to avoid potential conflicts with the highlighted key + bindings, especially when transient uses hydra-style colour-coded + keys. + +,* Applied the same metaphors for key bindings to 'marginalia-key' + ('marginalia' package) and 'embark-keybinding' ('embark' package). + They inherit the 'modus-themes-key-binding' when possible. The only + exception is with (setq modus-themes-completions nil) where conflicts + may arise between the key's style and matching characters of the + ongoing completion session. + + Thanks to Rudolf Adamkovič for pointing out the inconsistency in issue + 278: <https://gitlab.com/protesilaos/modus-themes/-/issues/278>. + +,* Refrained from treating LaTeX sections as headings. This is because + unlike Org/Outline/Markdown Latex is basically source code, so the + sectioning does not work the same way it does for those lightweight + markup/outlining modes. + + Furthermore, font-latex.el defines 'font-latex-fontify-sectioning' + which can be used to control the scale of those sections. It makes + sense for the themes to not interfere with that design and just allow + users to customise things uniformly regardless of the active theme. + + Thanks to Gustavo Barros for the detailed feedback in issue 265: + <https://gitlab.com/protesilaos/modus-themes/-/issues/265>. + +,* Reviewed the hues of 'all-the-icons' and related packages. + +,* Applied the correct style to 'info-menu-header', meaning that it now + only uses a bold weight as it is not a real heading, instead of being + affected by the user option 'modus-themes-headings'. + +,* Included new 'telega-entity-type-spoiler' face. Thanks to bit9tream + for informing me about it in issue 271: + <https://gitlab.com/protesilaos/modus-themes/-/issues/271>. The + conclusion: + + Tricky though perhaps dull + + I understand this is not an interesting topic and it probably is + too difficult to relate to the various data points without + visualising them and comparing the before and after + states. Furthermore, data can be deceptive and I have always + maintained that theme development stands at the intersection of + science and art (at least for the purposes of conforming with the + rigorous accessibility standards of the Modus themes). + + That granted, I wanted to shed light on the “behind the scenes” + work that is not immediately obvious when one checks a diff that + introduces some seemingly trivial tweaks like '#49d239'->'#49c029' + or '#7fcfff'->'#8fbfff'. + +,* Tweaked the hues of all graph colours, which are used in the + 'org-habit' table. The changes are subtle and should improve the + overall usability of the graph. For the technicalities, read: + <https://protesilaos.com/codelog/2022-01-02-review-modus-themes-org-habit-colours/>. + + Also thanks to Rudolf Adamkovič for reporting the problem with white + text on yellow background in issue 270: + <https://gitlab.com/protesilaos/modus-themes/-/issues/270>. + +,* Styled the 'markdown-highlighting-face'. This is the face used for + text in between double equals signs when the user option + 'markdown-enable-highlighting-syntax' is non-nil. + +,* Amplified the overall colouration of Eldoc's current argument. It is + a yellow foreground with a tinted background. The blue foreground + which was applied before could be hard to tell apart in some cases, + especially because it is a common colour that is used elsewhere in the + themes. Whereas the warmer hues are easier to discern, especially + while relying only on peripheral vision. + + Thanks to Rudolf Adamkovič for the feedback in issue 275: + <https://gitlab.com/protesilaos/modus-themes/-/issues/275>. + +,* Instructed Geiser to use the same style for its argument as Eldoc + (edited the faces 'geiser-font-lock-autodoc-current-arg' and + 'geiser-font-lock-autodoc-identifier'). + +,* Made the 'keycast-key' face work when 'modus-themes-mode-line' has a + padding value (read the latter doc string or consult the manual). + +,* Refined the 'magit' faces for bisect, reflog, sequence, and signature + views. They get a bold weight and, where appropriate, are made to + comply with the 'modus-theems-deueteranopia' option (meaning that + greens turn into blues). + +,* Recoloured 'elfeed' tags from a shade of cyan to magenta, in the + interest of theme-wide consistency but also to make them easier to + tell apart from the name of the feed. Also updated the faces used in + the header-line to look better in context. + +,* Removed the hardcoded ':slant italic' from the 'italic' face, which is + consistent with how we do not hardcode ':weight bold' in the 'bold' + face. + + Such a design allows users to configure those faces and have the + desired slant/weight (and even font family) apply consistently + throughout the theme. Read the manual for further details: + <https://protesilaos.com/emacs/modus-themes#h:2793a224-2109-4f61-a106-721c57c01375>. + + Thanks to user derek-upham for pointing out the inconsistency in issue + 21 over at the GitHub mirror: + <https://github.com/protesilaos/modus-themes/issues/21>. + +,* Improved the styles that apply to compilation buffers and related. + The overarching intent was to reduce the excess colouration, without + upsetting expectations and affecting the overall presentation. + + Thanks to Rudolf Adamkovič for the feedback in issue 277: + <https://gitlab.com/protesilaos/modus-themes/-/issues/277>. + + Note that compilation buffers apply an underline by default. The + manual explains how to change that: + <https://protesilaos.com/emacs/modus-themes#h:420f5a33-c7a9-4112-9b04-eaf2cbad96bd>. + +,* Ensured a consistent style for the 'highlight' face across all + contexts (typically used for mouse hover effects). The mode line has + an exception when its style includes an accented background (per + 'modus-themes-mode-line'). + + Thanks to Rudolf Adamkovič for the feedback in issue 214: + <https://gitlab.com/protesilaos/modus-themes/-/issues/214>. + +,* Changed the foreground of 'mode-line-emphasis' from blue to purple, in + order to avoid potential (albeit unlikely) confusion with other + indicators. + +,* Desaturated the 'man' and 'woman' foreground value of the bold + constructs and tweaked other faces to avoid potential inconsistencies. + Thanks to Daniel Mendler for the feedback: + <https://gitlab.com/protesilaos/modus-themes/-/commit/8080eb1c6c0020ba82e8abaa933d6686327bc616#note_841424489>. + +,* Removed certain exaggerations from widgets as seen in the Custom UI + and EWW. Specifically: + + - 'widget-field' does not need to ':extend', as that typically does + not look good. + + - 'custom-state' gets a warmer colour to convey its message more + effectively. + + - 'eww-form-text' no longer uses a ':box' because that breaks when the + widget occupies more than one line. + + - 'eww-form-textarea' can now inherit from 'eww-form-text'. + + Thanks to Daniel Mendler for the feedback on the style of those faces in + issue 284: <https://gitlab.com/protesilaos/modus-themes/-/issues/284>. + + +The manual +========== + +,* Clarified the wording of 'shr' fonts, which affect 'eww', 'elfeed', + 'ement', and possibly others. + +,* Wrote section on custom Org emphasis faces. It includes code samples. + +,* Answered a Frequently Asked Question on whether the Modus themes are + "colour schemes"---they are not and it is important to understand why. + +,* Addressed another Frequently Asked Question about porting the themes + to other platforms or editors. Relevant blog posts which explain how + complex the issue is and why porting requires the same attention to + detail as this project: + + - <https://protesilaos.com/codelog/2022-01-03-modus-themes-port-faq/>. + - <https://protesilaos.com/codelog/2022-01-23-base16-modus-themes/>. + +,* Improved the sample code in the section about the backdrop of PDF + files while using 'pdf-tools'. Thanks to Utkarsh Singh for the patch, + which was sent via email. + +,* Provided sample code on an alternative style for Ediff. + + There was a discussion with Philip Kaludercic in issue 273 about making + this a defcustom: <https://gitlab.com/protesilaos/modus-themes/-/issues/273>. + + I first entertained the notion and did set up a branch for testing + purposes. However, I ultimately decided that such a course of action + would establish a bad precedent because then every conceivable stylistic + tweak could, in principle, become a user option. Furthermore, the + potential defcustom would introduce too much complexity as Ediff would + have to continue to behave as other diffs (per 'modus-themes-diffs') if + the user did not want the alternative style. + + As such, documenting how a user can achieve this is the right choice. + +,* Fixed internal link in the manual. Thanks to Rudolf Adamkovič for + reporting the problem in issue 277: + <https://gitlab.com/protesilaos/modus-themes/-/issues/277>. + + +Miscellaneous +============= + +,* Covered workaround for improving the accuracy of colour reproduction + in terminal emulators. The results are still not as good as the + graphical version of Emacs, though they are considerably better than + before. Thanks to gitrj95's issue 18 at the GitHub mirror, which + prompted me to research this topic: + <https://github.com/protesilaos/modus-themes/issues/18>. + +,* Helped report a bug in the PGTK build of Emacs where a new emacsclient + window with the 'modus-vivendi' face would not show the cursor: + <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=53073>. Thanks to + contributed to the discussion on issue 7 over at the GitHub mirror: + <https://github.com/protesilaos/modus-themes/issues/7> + +,* Shifted the hue of the intense 'hl-line' from a grey-cyan to a more + vivid blue by reducing the relative contribution of the green channel + of light. + + The change affects these styles: + + (setq modus-themes-hl-line '(accented intense)) + (setq modus-themes-hl-line '(accented intense underline)) + + Thanks to Rudolf Adamkovič for suggesting a more vivid colour in issue + 214: <https://gitlab.com/protesilaos/modus-themes/-/issues/214>. + +,* Recalibrated the 'modus-vivendi' named colour 'bg-paren-match'. + + I wanted to increase its distance relative to the main background, + just to be sure that it is easier to spot. This is achieved by moving + the hueness from the yellow to the magenta side of the spectrum. + + Overall, the change is subtle and has no major impact on the contrast + ratio relative to the main background and foreground (we need to + consider both due to the specifics of show-paren-mode (and related)). + + The results (#5f362f is the old, #6f3355 the new): + + | | #000000 | #ffffff | #000000 | #ffffff | + |---------+---------+---------+---------+---------| + | #5f362f | 2.06 | 10.22 | 37904 | 333060 | + | #6f3355 | 2.28 | 9.21 | 58282 | 291037 | + + The TBLFM formula for this table (org-mode notation): + + $2='(Λ $1 @1$2);%.2f :: $3='(Λ $1 @1$3);%.2f :: $4='(Δ $1 @1$4) :: $5='(Δ $1 @1$5) + + The Greek letters mean: + + (defalias 'Λ #'modus-themes-contrast) + (defalias 'Δ #'color-distance) + +,* Expanded the "special" subset of the palette with faint variants of + the four backgrounds. These are reserved for special circumstances, + as the name implies. Below are the contrast values (see + 'modus-themes-contrast'). + + Modus Operandi main accept colours against faint special backgrounds: + + | | #f0f1ff | #ebf5eb | #fef2ea | #faeff9 | + |---------+---------+---------+---------+---------| + | #a60000 | 7.15 | 7.17 | 7.29 | 7.16 | + | #972500 | 7.26 | 7.28 | 7.40 | 7.28 | + | #a0132f | 7.13 | 7.15 | 7.27 | 7.14 | + | #7f1010 | 9.44 | 9.47 | 9.63 | 9.47 | + | #702f00 | 8.94 | 8.97 | 9.12 | 8.96 | + | #7f002f | 9.64 | 9.67 | 9.83 | 9.66 | + | #005e00 | 7.20 | 7.23 | 7.34 | 7.22 | + | #315b00 | 7.13 | 7.15 | 7.27 | 7.15 | + | #145c33 | 7.18 | 7.20 | 7.32 | 7.20 | + | #104410 | 10.09 | 10.12 | 10.29 | 10.12 | + | #30440f | 9.56 | 9.59 | 9.75 | 9.58 | + | #0f443f | 9.76 | 9.79 | 9.96 | 9.79 | + | #813e00 | 7.14 | 7.17 | 7.28 | 7.16 | + | #70480f | 7.14 | 7.17 | 7.28 | 7.16 | + | #863927 | 7.13 | 7.15 | 7.27 | 7.15 | + | #5f4400 | 8.10 | 8.12 | 8.26 | 8.12 | + | #5d5000 | 7.17 | 7.19 | 7.31 | 7.19 | + | #5e3a20 | 8.91 | 8.94 | 9.09 | 8.93 | + | #0031a9 | 9.31 | 9.34 | 9.49 | 9.33 | + | #2544bb | 7.14 | 7.16 | 7.28 | 7.16 | + | #0000c0 | 10.64 | 10.67 | 10.85 | 10.66 | + | #003497 | 9.66 | 9.70 | 9.86 | 9.69 | + | #0f3d8c | 9.06 | 9.09 | 9.24 | 9.09 | + | #001087 | 13.15 | 13.20 | 13.42 | 13.19 | + | #721045 | 9.99 | 10.02 | 10.19 | 10.01 | + | #8f0075 | 7.72 | 7.75 | 7.88 | 7.74 | + | #5317ac | 8.98 | 9.01 | 9.16 | 9.00 | + | #752f50 | 8.22 | 8.25 | 8.38 | 8.24 | + | #7b206f | 8.22 | 8.25 | 8.38 | 8.24 | + | #55348e | 8.26 | 8.29 | 8.42 | 8.28 | + | #00538b | 7.18 | 7.20 | 7.32 | 7.19 | + | #30517f | 7.18 | 7.20 | 7.32 | 7.20 | + | #005a5f | 7.13 | 7.15 | 7.27 | 7.15 | + | #005077 | 7.76 | 7.79 | 7.91 | 7.78 | + | #354f6f | 7.49 | 7.52 | 7.64 | 7.51 | + | #125458 | 7.69 | 7.72 | 7.85 | 7.71 | + + Modus Vivendi main accept colours against faint special backgrounds: + + | | #0e183a | #001f1a | #241613 | #251232 | + |---------+---------+---------+---------+---------| + | #ff8059 | 7.01 | 7.01 | 7.07 | 7.00 | + | #ef8b50 | 7.01 | 7.00 | 7.07 | 7.00 | + | #ff9077 | 7.85 | 7.85 | 7.93 | 7.85 | + | #ffa0a0 | 8.91 | 8.91 | 9.00 | 8.91 | + | #f5aa80 | 9.04 | 9.04 | 9.13 | 9.04 | + | #ff9fbf | 9.06 | 9.05 | 9.14 | 9.05 | + | #44bc44 | 7.04 | 7.04 | 7.11 | 7.04 | + | #70b900 | 7.13 | 7.13 | 7.20 | 7.12 | + | #00c06f | 7.24 | 7.24 | 7.31 | 7.24 | + | #78bf78 | 7.87 | 7.86 | 7.94 | 7.86 | + | #99b56f | 7.60 | 7.59 | 7.67 | 7.59 | + | #88bf99 | 8.23 | 8.22 | 8.30 | 8.22 | + | #d0bc00 | 8.98 | 8.98 | 9.07 | 8.98 | + | #c0c530 | 9.31 | 9.31 | 9.40 | 9.30 | + | #d3b55f | 8.71 | 8.71 | 8.79 | 8.71 | + | #d2b580 | 8.81 | 8.80 | 8.89 | 8.80 | + | #cabf77 | 9.28 | 9.27 | 9.36 | 9.27 | + | #d0ba95 | 9.20 | 9.20 | 9.29 | 9.20 | + | #2fafff | 7.18 | 7.18 | 7.25 | 7.18 | + | #79a8ff | 7.32 | 7.32 | 7.39 | 7.31 | + | #00bcff | 7.96 | 7.96 | 8.04 | 7.96 | + | #82b0ec | 7.74 | 7.74 | 7.81 | 7.74 | + | #a0acef | 7.97 | 7.96 | 8.04 | 7.96 | + | #80b2f0 | 7.89 | 7.88 | 7.96 | 7.88 | + | #feacd0 | 9.94 | 9.93 | 10.03 | 9.93 | + | #f78fe7 | 8.29 | 8.29 | 8.37 | 8.29 | + | #b6a0ff | 7.82 | 7.81 | 7.89 | 7.81 | + | #e0b2d6 | 9.51 | 9.50 | 9.60 | 9.50 | + | #ef9fe4 | 8.88 | 8.88 | 8.96 | 8.87 | + | #cfa6ff | 8.72 | 8.71 | 8.80 | 8.71 | + | #00d3d0 | 9.28 | 9.27 | 9.36 | 9.27 | + | #4ae2f0 | 11.09 | 11.09 | 11.20 | 11.09 | + | #6ae4b9 | 11.08 | 11.07 | 11.18 | 11.07 | + | #90c4ed | 9.34 | 9.34 | 9.43 | 9.33 | + | #a0bfdf | 9.10 | 9.09 | 9.18 | 9.09 | + | #a4d0bb | 10.18 | 10.17 | 10.27 | 10.17 | + +,* Add docs on color overrides through blending. Thanks to Alex Griffin + for the contribution in issue 269 and the subsequent patch in merge + request 56 (the patch is exempt from copyright assignment): + + - <https://gitlab.com/protesilaos/modus-themes/-/issues/269>. + - <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/56>. + +,* Fixed typo in the ':group' value of some faces defined in + modus-themes.el. Thanks to Gustavo Barros for reporting it in issue + 266: <https://gitlab.com/protesilaos/modus-themes/-/issues/266> + +,* Updated copyright statement in all .el files to use the same wording + as all other files that are built into Emacs. + +,* Made all sorts of tweaks and refinements to doc strings and nodes in the + manual. + +Thanks again to everyone involved! This has been yet another cycle of +intense work which further iterated on an already solid base. +#+end_src + +* 2.0.0 +:PROPERTIES: +:CUSTOM_ID: h:46d92baa-eff3-4973-bac0-cf762b457e2d +:END: + +#+begin_src text +Modus themes version 2.0.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2021-12-24 + +This entry covers the changes made to the project since the publication +of version 1.7.0 on 2021-11-18. There have been more than 90 commits in +the meantime. This is a major upgrade with some backward-incompatible +changes, even though most work was done behind the scenes (i.e. not in +git commits but local testing) to guarantee the relevance of all +user-facing styles, code practices, et cetera. + +All modifications of colour combinations mentioned herein are made in +accordance with the primary accessibility objective of the themes for a +minimum contrast ratio of 7:1 between background and foreground values +in their given combination (the WCAG AAA standard for relative colour +luminance). Edits also account for colour-coding that is optimised for +the needs of users with red-green colour deficiency (deuteranopia). + +To access the URL of the manual visit this web page: +<https://protesilaos.com/emacs/modus-themes>. Or read it in the Emacs +Info reader by evaluating this form: + + (info "(modus-themes) Top") + +The 'modus-operandi' and 'modus-vivendi' themes are built into Emacs-28 +(next stable release) or later, and are available on GNU ELPA as well as +other archives. Emacs-28 ships version 1.6.0, while the current +'master' branch (i.e. Emacs-29) and, by extension, GNU ELPA include the +latest tagged release. + +A fully fledged org-mode file with the annotated task list for Modus +themes version 2.0.0 is supplied as complementary material to the +present entry. It should be annexed below this text on the announcement +page: <https://protesilaos.com/codelog/2021-12-24-modus-themes-2-0-0/>. + + +Customisation options +===================== + +There are some breaking changes that were necessary to improve the code +base and make things easier as well as more efficient for end users. +Please read carefully and apologies in advance for whatever +inconvenience. + +,* The 'modus-themes-variable-pitch-headings' no longer has any effect. + Instead, users can specify a 'variable-pitch' property to the list + they pass to the 'modus-themes-headings' or 'modus-themes-org-agenda' + (examples below). + +,* All 'modus-themes-scale-*' options are removed. Scaling of headings + is now handled directly by the user options 'modus-themes-headings' + and 'modus-themes-org-agenda' (code samples below). + +,* The 'modus-themes-headings' option now accepts a floating point (see + function 'floatp') that represents the multiplier relative to the base + font size. This can be used to scale headings accordingly. Since + this option can target individual heading levels (for 1 through 8), + users can now implement their desired scale with greater precision. + Whereas before it was limited to the first four levels, admittedly for + no good reason. + + The newly introduced 'variable-pitch' property can also be applied on + a per-level basis (making it easy to combine with existing properties, + such as a custom weight, for maximum control). Example: + + ;; This is an alist: read the manual or its doc string. + (setq modus-themes-headings + '((1 . (variable-pitch light 1.6)) + (2 . (overline semibold 1.4)) + (3 . (monochrome overline 1.2)) + (4 . (overline 1.1)) + (t . (rainbow 1.05)))) + +,* The 'modus-themes-org-agenda' follows the same design as the + 'modus-themes-headings' where appropriate. Headings that can be + scaled accept a floating point, while those that may be rendered in a + proportionately spaced font accept the 'variable-pitch' property. In + addition, a custom font weight is also supported in the relevant + places (just as with 'modus-themes-headings'). Overall, the interface + can now be tailored to the user's preferences with greater precision. + + ;; This is an alist: read the manual or its doc string. + (setq modus-themes-org-agenda + '((header-block . (variable-pitch light 1.6)) + (header-date . (bold-today grayscale underline-today 1.2)) + (event . (accented varied)) + (scheduled . uniform) + (habit . traffic-light))) + +,* The 'modus-themes-scale-small' that was used in the Org agenda + interface has been removed. No replacement is provided, as the + downsizing had the undesired effect of breaking the otherwise neat + alignment of elements on the grid. + +,* The 'modus-themes-mode-line-padding' option has been removed. + Instead, users can specify a natural number (positive integer) + directly in the list of properties passed to the + 'modus-themes-mode-line' variable. This has no effect when the + 'moody' property is also set, because the Moody library applies its + own padding. For example: + + (setq modus-themes-mode-line '(borderless accented 4)) + + Though not related to changes on our end, users of Emacs 29 must now + set 'x-use-underline-position-properties' to nil for padding to work + properly (due to other adjustments upstream). This relates to Emacs + bug#52324 we had reported: + <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=52324>. + +,* All deuteranopia styles are consolidated in a single toggle: + 'modus-themes-deuteranopia'. The 'modus-themes-success-deuteranopia' + is thus rendered obsolete and superseded, while the individual + deuteranopia-friendly styles for diffs ('modus-themes-diffs') and the + Org agenda's habit graph ('modus-themes-org-agenda') are altogether + removed. As opposed to top-level forms, there is no clean way to + notify the user of the deprecation of individual values of a user + option. + +,* The "foreground only" style has been altogether removed from the user + option 'modus-themes-diffs'. It never was up to the aesthetic + standard of the themes even though the colours met the minimum 7:1 + contrast ratio. There is a new section in the manual which documents + how to implement such a style with user-level configurations. Short + version: + + (defun my-modus-themes-custom-faces () + (modus-themes-with-colors + (custom-set-faces + `(modus-themes-diff-added ((,class :background unspecified :foreground ,green))) ; OR ,blue for deuteranopia + `(modus-themes-diff-changed ((,class :background unspecified :foreground ,yellow))) + `(modus-themes-diff-removed ((,class :background unspecified :foreground ,red))) + + `(modus-themes-diff-refine-added ((,class :background ,bg-diff-added :foreground ,fg-diff-added))) + ;; `(modus-themes-diff-refine-added ((,class :background ,bg-diff-added-deuteran :foreground ,fg-diff-added-deuteran))) + `(modus-themes-diff-refine-changed ((,class :background ,bg-diff-changed :foreground ,fg-diff-changed))) + `(modus-themes-diff-refine-removed ((,class :background ,bg-diff-removed :foreground ,fg-diff-removed))) + + `(modus-themes-diff-focus-added ((,class :background ,bg-dim :foreground ,green))) ; OR ,blue for deuteranopia + `(modus-themes-diff-focus-changed ((,class :background ,bg-dim :foreground ,yellow))) + `(modus-themes-diff-focus-removed ((,class :background ,bg-dim :foreground ,red))) + + `(modus-themes-diff-heading ((,class :background ,bg-alt :foreground ,fg-main))) + + `(diff-indicator-added ((,class :foreground ,green))) ; OR ,blue for deuteranopia + `(diff-indicator-changed ((,class :foreground ,yellow))) + `(diff-indicator-removed ((,class :foreground ,red))) + + `(magit-diff-added ((,class :background unspecified :foreground ,green-faint))) + `(magit-diff-changed ((,class :background unspecified :foreground ,yellow-faint))) + `(magit-diff-removed ((,class :background unspecified :foreground ,red-faint))) + `(magit-diff-context-highlight ((,class :background ,bg-dim :foreground ,fg-dim)))))) + + ;; This is so that the changes persist when switching between + ;; modus-operandi and modus-vivendi + (add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) + + +Removed support for packages +============================ + +The following are no longer supported by the themes. The reasons vary +in each case, though they boil down to (i) the package being obsoleted, +or (ii) the package's faces inheriting from base faces that we already +support (e.g. font-lock). Each case was carefully considered as part of +the comprehensive review of all packages supported by the themes, though +chances are that some mistake was made regardless. If you believe a +package should not have been removed, please report as much. + +,* ag +,* apt-sources-list +,* apt-sources-list +,* buffer-expose +,* counsel-org-capture-string +,* define-word +,* diredc +,* disk-usage +,* easy-kill +,* flyspell-correct +,* git-gutter{,fringe}+ +,* git-lens +,* git-walktree +,* highlight-blocks +,* highlight-defined +,* highlight-escape-sequences +,* highlight-symbol +,* highlight-tail +,* hyperlist-mode +,* isl (isearch-light) +,* minibuffer-line +,* mu4e-conversation +,* no-emoji +,* objed +,* parrot +,* phi-search +,* pkgbuild-mode +,* rainbow-identifiers +,* sallet +,* spell-fu +,* spray +,* swoop +,* vdiff +,* volatile-highlights + + +Changes to supported faces or face groups +========================================= + +,* Eliminated any possible exaggerations in wgrep faces. Those no longer + use coloured backgrounds. Instead they have colour-coded foreground + colours as well as a bold weight (they ultimately inherit from the + 'bold' face, which is a "hidden" customisation option, as explained in + the manual). + +,* Forced Org block delimiters to not extend their background by default + (though check 'modus-themes-org-blocks'). That was the intended + design all along, but now it needs to be made explicit. See, for + example, bug#52587 for Emacs: + <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=52587> + +,* Revised the 'org-sexp-date' face so that it no longer looks like + 'org-date'. Dates are clickable buttons: they work like links, so + they have an underline by default and are subject to the + 'modus-themes-links' user option. Whereas the 'org-sexp-date' is not + applied to interactive elements and must thus be visually distinct. + + This face is used for diary-style entries in Org files. For example: + + %%(diary-anniversary 2000 12 25) NAME %d%s birthday + +,* Rewrote several Auctex/Tex faces to inherit from base faces where + relevant (e.g. 'bold', 'success') as well as from font-lock faces. In + the latter case, the end-result makes Auctex/Tex subject to the + 'modus-themes-syntax' option. These refinements promote theme-wide + consistency without detracting from the established styles. + +,* Improved Git (Magit) commit faces for warnings or errors. This + concerns two cases: + + 1. The summary line exceeds the recommended limit of 50 characters. + This now uses a yellow foreground colour which contrasts well with + the summary line's new blue hue (blue and yellow are complementary + for our purposes, meaning that they have good contrast in hueness). + + 2. The second line (the one right below the summary) has text that + should not be there. This one is coloured in a shade of red, which + again contrasts well with blue. + + Thanks to Damien Cassou for noticing in issue 261 that the previous + style of applying tinted backgrounds did not work well when + 'hl-line-mode' was enabled ('hl-line-mode' overrides backgrounds and + so the warnings/errors where not always obvious): + <https://gitlab.com/protesilaos/modus-themes/-/issues/261>. + +,* Added support for the new 'magit-branch-warning' face that we helped + upstream define: <https://github.com/magit/magit/issues/4550>. It + disambiguates warnings in Magit status buffers from the generic and + often inappropriate for such a context 'font-lock-warning-face'. + +,* Simplified all the Apropos faces. They no longer look like buttons or + links as that makes the presentation of 'M-x apropos' very busy. + Instead, they now only have a foreground colour. + +,* Updated support for org-roam faces by removing old entries and + covering new ones. + +,* Replaced old company-mode faces with their new aliases: + + - company-scrollbar-bg => company-tooltip-scrollbar-thumb + - company-scrollbar-fg => company-tooltip-scrollbar-track + +,* Made 'org-column-title' inherit from 'fixed-pitch' when the user + option 'modus-themes-mixed-fonts' is non-nil. This is needed to line + up columns correctly. Thanks to Björn Lindström for the contribution + in merge request 52: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/52>. + +,* Forced the 'org-colview' faces to use the same height, even when + headings are scaled (see 'modus-themes-headings'). This ensures that + the columns are aligned properly and text fits on the same row. + Thanks to Björn Lindström for the contribution in merge request 53: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/53>. + +,* Refrained from applying a bold weight to the Org date selection + indicator in the calendar. The use of bold has the potential to create + problems with the alignment of dates for certain typefaces that do not + have a proper bold variant. Also, there is no need for added emphasis + given that we already use a prominent background colour. + +,* Made 'M-x org-table-header-line-mode' or the third-party package + 'org-table-sticky-header' use colours that fit better with those of + tables. + +,* Removed explicit styling of the 'magit-branch-current' face because + its definition checks if the ':box' attribute can be set and if not, it + uses ':inverse-video'. Useful for terminal emulators. + +,* Expanded support for the 'mode-line-active' face for Emacs29. The + face upstream basically adds proportionately spaced fonts (the + 'variable-pitch' face) to the mode line. The themes can already use + that if the user option 'modus-themes-variable-pitch-ui' is non-nil. + Thanks to Manuel Uberti for the feedback in issue 257: + <https://gitlab.com/protesilaos/modus-themes/-/issues/257>. + +,* Implemented some stylistic refinements for ERC and Rcirc to ensure + theme-wide consistency (e.g. timestamps are a shade of cyan). + +,* Tweaked adoc-mode faces for stylistic theme-wide consistency. + +,* Refashioned all the git faces of Treemacs so that they are more + consistent with other such contexts or uses. The new styles also + conform with the 'modus-themes-deuteranopia' option. + + +Miscellaneous +============= + +,* Ended the wanton use of internal functions in places that did not + require them. Instead, the themes define faces that evaluate such + functions once and pass their results to the relevant entries. Cases + include: + + - Symlink and/or broken link faces in contexts such as Dired, + Eshell, Helm, Trashed. + + - Tabbed interfaces (tab-bar, tab-line, centaur-tabs). + + - Verbatim markup or that of inline code in Org, Markdown, Asciidoc, + etc. + + - The optional use of 'variable-pitch' for User Interface elements + (see 'modus-themes-variable-pitch-ui'). + +,* Refined the dedicated diff background colours of modus-vivendi that + are used when the user option 'modus-themes-deuteranopia' is non-nil. + The changes improve the distinction between all red and yellow + constructs in contexts where they appear together (e.g. smerge-mode). + Basically, yellows will look more bright, while reds appear as + brown. The corresponding blues are toned down a bit to be consistent + with the other colours. Consequently, the standard shades of green + for added lines (when 'modus-themes-deuteranopia' is nil) are + recalibrated to combine well with all other values. + +,* Made several faces return an 'unspecified' value instead of nil for + their unused attributes under certain circumstances. This is to guard + against third-party code that unconditionally expects a non-nil value. + +,* Omitted {over,under}line attributes from the mode line when the + 'padded' property is added to the 'modus-themes-mode-line' user + option. Those are not necessary in that context. Thanks to Illia + Ostapyshyn for the contribution in merge request 54: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/54> + +,* Rewrote several internal functions in the interest of consistency and + clarity. + +,* Deleted two user options that were long obsolete: (i) + 'modus-themes-org-habit' has been superseded by + 'modus-themes-org-agenda' since version 1.5.0 of the themes and (ii) + 'modus-themes-intense-hl-line' has been replaced by + 'modus-themes-hl-line' since version 1.3.0. + +,* Removed parentheses from headings in the manual as they are invalid + characters for some version of Texinfo. See Emacs bug#52126: + <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=52126>. + +,* Updated all doc strings so that quoted lists yield valid syntax in + Help buffers; syntax that can be directly evaluated (otherwise Emacs + prettifies straight quotes as curly ones, which break the code). + Thanks to Christian Tietze for bringing this issue to my attention: + <https://gitlab.com/protesilaos/modus-themes/-/issues/248#note_753169268>. + +,* Rewrote all sections of the manual to document the current state of + the project as pertains to valid user options, explicitly supported + face groups, and so on. +#+end_src + +* 1.7.0 +:PROPERTIES: +:CUSTOM_ID: h:22de7065-f54c-4944-b47f-3cc8a30551c8 +:END: + +#+begin_src text +Modus themes version 1.7.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2021-11-18 + +The present entry records the changes made to the project since the +release of version 1.6.0 on 2021-09-29. There have been more than 60 +commits since then. + +Every modification pertaining to colour combinations referenced herein +is implemented in accordance with the primary accessibility objective of +the themes for a minimum contrast ratio of 7:1 between background and +foreground values in their given combination (the WCAG AAA standard). +Edits also account for colour-coding that is optimised for the needs of +users with red-green colour deficiency (deuteranopia). + +To access the URL of the manual visit this web page: +<https://protesilaos.com/emacs/modus-themes>. Or read it from Emacs by +evaluating this form: + + (info "(modus-themes) Top") + +The themes are built into Emacs version 28 (next stable release), and +are available on GNU ELPA as well as other archives. This release is +the first one that is included with Emacs 29, or else the 'master' +branch in emacs.git. + + +Customisation options +===================== + ++ The 'modus-themes-no-mixed-fonts' has been deprecated and replaced by + the 'modus-themes-mixed-fonts'. This is a breaking change for users + who want to use "mixed fonts": they must set the new variable to + non-nil. + + As the name implies, the new variable changes the meaning of the + feature to make it opt-in by default. This is consistent with the + principle of least surprise, as users may not know why some fonts look + different than others in certain cases. + + Thanks to Christian Tietze for clarifying the doc string of this new + user option in merge request 51: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/51>. + + For context, "mixed fonts" refers to a design where spacing-sensitive + constructs, such as code blocks and Org tables, inherit from the + 'fixed-pitch' face to remain monospaced (and properly aligned) at all + times. Depending on the user's configurations, the 'fixed-pitch' face + may not use the typeface that the user expects. + + The manual provides information on how to set the desired fonts by + editing the 'default', 'fixed-pitch', and 'variable-pitch' faces. + ++ The new 'modus-themes-mode-line-padding' can be used to control the + apparent padding of the mode line when the user option + 'modus-themes-mode-line' includes the 'padded' property. The padding + must be a positive integer (otherwise the code would be needlessly + complex to guard against values that make the mode line look awkward, + like anything lower than -3 or maybe even -2). + + Thanks to Guilherme Semente and Manuel Uberti for the feedback in + issue 245: <https://gitlab.com/protesilaos/modus-themes/-/issues/245>. + + Note that the out-of-the-box style of the themes has a padding of 1 + (technically a ':line-width' of 1 for the ':box' attribute), whereas + the default style of Emacs has it at -1. This is a design choice to + avoid an overlap between the outer boundaries of a font's glyphs and + the borders of the mode line, when using certain common typefaces at + various point sizes. Such an overlap can hinder readability. + + The manual contains a new Do-It-Yourself (DIY) section with detailed + code samples on how to apply a negative value. + ++ The new 'modus-themes-intense-markup' option can be set to non-nil to + make constructs such as inline code and verbatim text more colourful. + This has a general utility, though its consideration was prompted by a + phenomenon reported by Stefan Kangas in issue 238 where the overlay of + the 'hl-line-face' overrides the subtle background these constructs + use and can thus make them virtually indistinguishable from ordinary + text: <https://gitlab.com/protesilaos/modus-themes/-/issues/238>. + + Such is the standard behaviour of 'hl-line-mode' and there is nothing + a theme can (or rather "should") do about it. Thanks to Stefan Kangas + for the feedback. + ++ The 'modus-themes-headings' option can now accept and apply an exact + font weight such as 'semibold' or 'light'. (The list of available + weights is the value of the 'modus-themes--heading-weights' internal + variable.) This supersedes the now-deprecated 'no-bold' property: + 'no-bold' is henceforth understood as the presence of a 'regular' + weight. + + Recall that this user option is an alist and can be used to target + heading levels individually, which further reinforces the utility of + this new property. + + Thanks to Christian Tietze for suggesting this idea in issue 248: + <https://gitlab.com/protesilaos/modus-themes/-/issues/248>. And + thanks to Daniel Mendler for refining its implementation in commit + 54bfd62, which was sent as a patch file (yes, we accept those and I + actually prefer them over a web app's UI). + ++ The 'modus-themes-org-agenda' has seen improvements to its 'event' key + (this is an alist that has multiple keys). It now accepts a 'varied' + property which differentiates between (i) plain timestamp entries and + (ii) entries that are generated from either the diary or a symbolic + expression. The 'varied' property combines with the other available + properties to particularise their effects. Consult the doc string or + the manual for the technicalities. + + Thanks to Gustavo Barros for the detailed commentary in issue 241: + <https://gitlab.com/protesilaos/modus-themes/-/issues/241>. + ++ The 'modus-themes-lang-checkers' now accepts a 'faint' property. This + has the effect of toning down the colours in use. By default, the + only colour is that of the underline, though more can be added by + combining the properties accepted by this user option. Consult its + doc string or the manual for further details. + + Thanks to Morgan Smith for suggesting the idea in issue 239: + <https://gitlab.com/protesilaos/modus-themes/-/issues/239>. + + +Add support for new packages or face groups +=========================================== + ++ 'company-tooltip-deprecated' face. Thanks to Roman Rudakov for the + feedback in issue 247: <https://gitlab.com/protesilaos/modus-themes/-/issues/247>. + ++ 'corfu-default' face. Thanks to Daniel Mendler (Corfu's developer) + for the feedback in issue 254: + <https://gitlab.com/protesilaos/modus-themes/-/issues/254>. + ++ 'image-dired' package (Emacs 29). Thanks to Stefan Kangas for making it + happen in emacs.git and for the feedback in issue 250: + <https://gitlab.com/protesilaos/modus-themes/-/issues/250>. + ++ 'nano-modeline' package. + ++ 'vertico-quick' package. Thanks to Nicolas De Jaeghere for the + contribution in merge request 48: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/51>. + + +Changes to existing faces or face groups +======================================== + ++ Added support for the new Org agenda faces that improve the + contextuality of various views. We implemented those upstream for Org + version 9.5 in close cooperation with Gustavo Barros. Thanks to + Gustavo for the detailed feedback in issue 241: + <https://gitlab.com/protesilaos/modus-themes/-/issues/241>. The + thread about the patch upstream: + <https://list.orgmode.org/87lf7q7gpq.fsf@protesilaos.com/> + ++ Refined Org agenda date faces in the interest of consistency and in + accordance with the aforementioned change. Thanks again to Gustavo + Barros for the discussion in issue 241. + ++ Applied the 'shadow' face more consistently across all contexts where + only a subtle foreground value is expected. This design choice makes + it possible for users to manually edit the foreground colour of + 'shadow' to something even more subtle than the 'fg-alt' palette + variable we use, which maps to a gray colour (e.g. they could use + "gray50"). + ++ Implemented a subtle background colour to the 'widget-inactive' face. + This makes it easier to discern inactive buttons, checkboxes, and the + like, in contexts such as the Customize User Interface. Thanks to + Stefan Kangas for the feedback in issue 242: + <https://gitlab.com/protesilaos/modus-themes/-/issues/242>. + ++ Tweaked 'file-name-shadow' to also use italics (inherit from the + 'italic' face) in order to be more easy to distinguish it from + ordinary text in the minibuffer. + + Recall that the manual documents the meaning of inheriting from the + 'bold' and 'italic' faces instead of hardcoding a bold weight and an + italic slant, respectively. In short: users can change the weight to + what they want (e.g. semibold) and/or use distinct font families. + ++ Amplified the style of Version Control (VC) warnings and errors to let + them draw more attention to themselves (because these indicators need + to be acted upon). + ++ Recoloured the 'custom-group-tag' face to make it fit better in its + context and be consistent with the rest of the themes' established + patterns. + ++ Made marks for selection in Dired, Ibuffer, and related, conform with + the 'modus-themes-success-deuteranopia' option. This means that they + use blue colours when the option is non-nil, instead of their default + shades of green. + ++ Adjusted the box width of key bindings for Emacs 28 or higher. They + should no longer cause any alignment issues. This style is now used + throughout the themes, including in transient views (e.g. Magit) which + were the exception before. Thanks to Manuel Uberti and Kevin Fleming + for the feedback in issue 232: + <https://gitlab.com/protesilaos/modus-themes/-/issues/232>. + + +Miscellaneous +============= + ++ Wrote a brief description of every user option in the manual. Also + covered its type, as in boolean, alist, et cetera. + ++ Corrected the mode line border width for one combination of properties + in the 'modus-themes-mode-line' option. This should now have the same + height as all others: + + (setq modus-themes-mode-line '(accented borderless)) + ++ Ensured that mode line attributes would not be set to nil, but kept at + an 'unspecified' value instead, where relevant. This avoids problems + with [faulty] code that unconditionally depends on something that does + not exist, as in the following while ':box' is nil: + + (face-attribute 'mode-line :box) + ++ Expanded, reworded, or otherwise improved the manual, based on the + aforementioned. + +Thanks once again to everyone involved! +#+end_src + +* 1.6.0 +:PROPERTIES: +:CUSTOM_ID: h:e4b9945c-1db8-4626-abc9-372469b19253 +:END: + +#+begin_src text +Modus themes version 1.6.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2021-09-29 + +This entry records the changes made to the project since the release of +version 1.5.0 on 2021-07-15. There have been around 70 commits since +then. + +Every colour-related modification referenced herein is always +implemented in accordance with the primary accessibility objective of +the themes for a minimum contrast ratio of 7:1 between background and +foreground values in their given combination (the WCAG AAA standard). +Such edits also account for colour-coding that is optimised for the +needs of users with red-green colour deficiency (deuteranopia or +variants). + +Here is the URL of the manual: <https://protesilaos.com/emacs/modus-themes>. +Or read it from Emacs by evaluating this form: + + (info "(modus-themes) Top") + +The themes are built into Emacs version 28 (current development target), +and are available on GNU ELPA as well as other archives. This release +is the final one for the emacs-28 branch, as that gets cut as the next +stable release of GNU Emacs. Future releases will target Emacs 29 once +that becomes the new 'master' branch. + + +Customisation options +===================== + +[ Themes need to be reloaded for changes to take effect. ] + ++ Introduced the new 'modus-themes-tabs-accented' boolean option. When + set to non-nil, it renders the background of all tab interfaces in a + shade of blue. Those interfaces are tab-bar (built-in), tab-line + (built-in), and Centaur tabs. + + - The background "accented" colour is the same as the one used for + mode lines when 'modus-themes-mode-line' is configured accordingly. + ++ Tweaked the 'modus-themes-mode-line' to accept a 'padded' symbol as + part of the list of properties it can read. This will increase the + spacing around the mode lines' text, making the line taller overall + but also more spacious. + + Thanks to Manuel Uberti for making the proposal and providing feedback + in issue 228: <https://gitlab.com/protesilaos/modus-themes/-/issues/228>. + ++ Added the 'modus-themes-scale-small' which complements the existing + scale values with one that is meant to be smaller than the base + height. This option is reserved for special cases and is currently + only used as an opt-in feature in the Org agenda. + ++ Expanded the 'modus-themes-org-agenda' with more parameters: + + - The current date can now also be underlined. + - Date headings can be scaled/enlarged in size. + - Events, like those of the Diary or sexp entries, can be customised. + + Consult the manual or the variable's doc string for the details. + ++ Removed the obsoleted aliases 'modus-themes-slanted-constructs' and + 'modus-themes-scale-5'. Those are superseded by the more + appropriately named 'modus-themes-italic-constructs' and + 'modus-themes-scale-title'. + + Thanks to Nicolas De Jaeghere for the patch in merge request 47: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/47>. + + +Faces and face groups +===================== + ++ Make the 'prodigy' faces for red/green/yellow inherit from the faces + 'error'/'success'/'warning', respectively. This is done to (i) avoid + duplication and (ii) ensure that the green/success colour coding is + consistent with the goal of the themes to empower users with red-green + colour deficiency. The boolean option that changes all such greens to + shades of blue is 'modus-themes-success-deuteranopia'. + ++ Assigned the ':extend' attribute to the 'org-code' face. This is + necessary when the Org source contains lines that start with a colon + sign. Those are interpreted as code blocks. For example: + + : #+BEGIN_SRC emacs-lisp + : (defun in-interval (bounds el) + : (and (>= el (car bounds)) (<= el (cadr bounds)))) + : #+END_SRC + + With the ':extend' in place, the background stretches to the edge of + the window, thus giving those lines a uniform rectangular shape. For + inline uses of 'org-code', the background should remain limited to the + span of the text. + ++ Broadened support for 'marginalia' faces in two phases. + + - The first pertained to the file permissions that are shown when + completing against file paths. Their style is similar to what + 'dired+' or the 'direfl' packages provide, however we have taken + care to optimise the interface for the purposes of completion + UIs---where things can look like Dired, we make them alike, but + where they must differ, we differentiate the designs accordingly. + There can be no compromises or arbitrary constraints. + + Also read: <https://github.com/minad/marginalia/pull/91>. + + - The second batch covered all sorts of extra classes that provide + granular control over the appearance of Marginalia instances. + Refinements also had to be made to already-supported faces for the + sake of achieving consistency across the various Marginalia + interfaces. + + Also read: <https://github.com/minad/marginalia/pull/92>. + ++ Refined 'diredfl' and 'dired+' faces. For the various "priv" faces, + the intent is to increase the difference in hueness between adjacent + file permissions (the changes are minor, but they do change the + overall result). Numbers are toned down so that they do not clash + with dates. The file suffix no longer uses cyan to stand out more in + detailed views. + ++ Made 'icomplete-selected-match' (Emacs28) more legible by aligning its + presentation with metaphors that are estaslished across the + modus-themes. Thanks to Kévin Le Gouguec (peniblec) for noting the + inconsistency with the new face upstream and for writing the patch for + it in merge request 50: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/50>. + Also thanks to Manuel Uberti for confirming that things would look + consistent in the comments' section of that merge request. + ++ Fixed faulty inheritance for the 'web-mode-keyword-face'. It should + now properly copy the attributes of 'font-lock-keyword-face'. + ++ Made inheritance of the new 'help-key-binding' (Emacs28 key) the + default for all faces that need to style key bindings. + + In Emacs 28 all key bindings are automatically displayed with the face + 'help-key-binding' which uses some new face attributes to draw a + cleaner box around it. Given that the themes must work with earlier + versions of Emacs, we cannot inherit it unconditionally so we added + the relevant conditionality. It is nice to offer this feature to + those who use the themes on Emacs 28. Older versions retain the + previous style of a blue colour coupled with a bold weight. + + The exception to this rule is the transient.el faces (this is the + pop-up window used by Magit, among others---transient.el is now built + into Emacs). The box effect creates unpredictable misalignments, so + we default to the old key binding style for those. + + Thanks to Manuel Uberti and Kevin Fleming for their feedback in issue + 232: <https://gitlab.com/protesilaos/modus-themes/-/issues/232>. + ++ Added support for the new 'notmuch-jump-key' face. I contributed this + face in commits c37c9912, 5cc106b0 to the Notmuch git repo: + <https://git.notmuchmail.org/git/notmuch>. + ++ Updated the 'bookmark-face' (Emacs28) as it has been changed upstream + to be a fringe indicator instead of an in-buffer, line-wide background + highlight. + ++ Aligned Ediff faces with other 'modus-themes-diffs' styles. Before we + would differentiate a "focus state", though that is now considered + surplus to requirements. The notion of a "focus state" only make + sense in Magit which applies variegated colour-coding to diff hunks + based on their state. Whereas non-active Ediff changes are grayed + out, so there is no need for further colour-coding nuances. The most + noticeable change is with: + + (setq modus-themes-diffs 'bg-only) + + As noted in the commit message of 64c74ae (from 2021-09-04): + + If users think this change is for the worse, we can always define a + helper function like this: + + (defun modus-themes--ediff-style (bgonly default) + "Diff style for Ediff. + BGONLY and DEFAULT depend on the value of `modus-themes-diffs'. + The former is more subtle." + (if (eq modus-themes-diffs 'bg-only) + (list bgonly) + (list default))) + + And apply it thus: + + `(ediff-current-diff-A ((,class :inherit ,@(modus-themes--ediff-style + 'modus-themes-diff-removed + 'modus-themes-diff-focus-removed)))) + + No feedback was received towards that end in about a month, so we + consider the change to be acceptable, without prejudice to the + possibility of future updates. + ++ Unified the styles of 'org-agenda-calendar-sexp', 'org-agenda-diary', + and 'org-agenda-calendar-event'. This is not a user-facing change but + an internal refactoring to avoid repetition. It also makes things + easier for the implementation of the 'modus-themes-org-agenda' (as + mentioned above). + ++ Ensured that the 'bookmark-menu-bookmark' face inherits from the + 'bold' face. By default it hardcodes the bold weight, whereas we + instruct it to inherit the 'bold' face. A user can thus change the + ':weight' of that face to whatever they want, like semibold, + extrabold, etc. We do this throughout the themes for bold and + italics---consider it a "hidden feature" of sorts. Check the manual + for more on the matter: + + (info "(modus-themes) Configure bold and italic faces (DIY)") + ++ Provided support for tab-bar groups (Emacs28). Specifically the faces + 'tab-bar-tab-group-current' and 'tab-bar-tab-group-inactive'. + + Thanks to Adam Porter (alphapapa) for the feedback in issue 8 over at + the Github mirror: <https://github.com/protesilaos/modus-themes/issues/8>. + ++ Decoupled the 'stripes' face from that of 'hl-line-face'. This is + because the stripes are not meant to change depending on the value of + the user option 'modus-themes-hl-line'. + ++ Revised the red shade of "flagged" entries in mu4e and notmuch. Those + are now consistent with Gnus. The shade of red that was used before + was closer to the orange side of the spectrum whereas the current has + hints of blue (a cherry colour) and thus combines better with the cyan + and blue that prevail in those interfaces. These are fine margins, + though the effect is noticeable regardless. + ++ Configured the new 'ansi-color' faces (Emacs28) which are used by + shells and terminals (among others). Thanks to Manuel Uberti for + reporting the changes to upstream Emacs in issue 236: + <https://gitlab.com/protesilaos/modus-themes/-/issues/236>. + ++ Expanded support for EMMS faces, pertaining to its browser views. + Thanks to Feng Shu (tumashu) for bringing those to my attention in + issue 11 over at the Github mirror: + <https://github.com/protesilaos/modus-themes/issues/11>. + ++ Styled the new 'tab-line-tab-modified' face (Emacs28). It should now + use a faint red colour to denote changes to the underlying file. + Thanks to Adam Porter (alphapapa) for bringing it to my attention in + issue 12 over at the Github mirror: + <https://github.com/protesilaos/modus-themes/issues/12>. + ++ Configured the single face that the 'cursor-flash' package has to + offer. Thanks to Manuel Uberti for the feedback in issue 231: + <https://gitlab.com/protesilaos/modus-themes/-/issues/231>. + ++ Included 'elpher' in the list of supported packages by means of + covering the heading faces it implements. + ++ Recalibrated certain dedicated colours for inactive tabs and tweaked + tab faces to (i) marginally improve the default aesthetic and (ii) + harmonise it with the style of 'modus-themes-tabs-accented'. + ++ Removed the foreground attribute from all markup faces that are meant + to denote emphasis in italics. That is because such faces are + typically composed with others, so we do not wish to inadvertently + override any other colour that would otherwise have taken effect. + ++ Wrote the faces for upstream Org that improve the contextuality of + various agenda views (included in version 9.5). This was done in + close collaboration with Gustavo Barros who offered detailed feedback + in issue 208 (which also led to the creation and eventual expansion of + the 'modus-themes-org-agenda' user option): + <https://gitlab.com/protesilaos/modus-themes/-/issues/208>. + + Four new faces improve certain styles and offer more flexibility for + some Org agenda views: 'org-agenda-date-weekend-today', + 'org-imminent-deadline', 'org-agenda-structure-secondary', + 'org-agenda-structure-filter'. They inherit from existing faces in + order to remain backward-compatible. + + Quoting from <https://list.orgmode.org/87lf7q7gpq.fsf@protesilaos.com/>: + + + The 'org-imminent-deadline' is useful to disambiguate generic + warnings from deadlines. For example, a warning could be + rendered in a yellow colored text and have a bold weight, + whereas a deadline might be red and styled with italics. + + + The 'org-agenda-structure-filter' applies to all tag/term + filters in agenda views that search for keywords or patterns. + It is designed to inherit from 'org-agenda-structure' in + addition to the 'org-warning' face that was present before (and + removes the generic 'warning' face from one place). This offers + the benefit of consistency, as, say, an increase in font height + or a change in font family in 'org-agenda-structure' will + propagate to the filter as well. The whole header line thus + looks part of a singular design. + + + The 'org-agenda-structure-secondary' complements the above for + those same views where a description follows the header. For + instance, the tags view provides information to "Press N r" to + filter by a numbered tag. Themes/users may prefer to + disambiguate this line from the header above it, such as by + using a less intense color or by reducing its height relative to + the 'org-agenda-structure'. + + + The 'org-agenda-date-weekend-today' provides the option to + differentiate the current date on a weekend from the current + date on weekdays. + +Other patches I have made to, inter alia, emacs.git and org.git with +regard to faces are documented in previous change log entries. + + +Documentation +============= + ++ Removed references to old versions of the themes from before their + refactoring in version 1.0.0. Those old packages no longer exist. + Users must install the 'modus-themes' and then load either of + 'modus-operandi' or 'modus-vivendi'. + ++ Included various extensions of the Vertico package in the list of + indirectly supported packages. Those define faces which either + inherit from basic ones that we already support or use colours that + are consistent with our accessibility target. + ++ Referenced 'side-hustle', 'tide', 'bufler' as an indirectly supported + packages for the same reasons. + ++ Simplified time-stamp local variables that are used in modus-themes.el + to show the time the file was edited. We apply 'time-stamp-pattern' + instead of setting multiple time-stamp variables. Thanks to Stephen + Gildea for the patch, which was sent to me via email (yes, you can + always do that). + ++ Updated the manual's "acknowledgements" section to name all new + contributors to code/ideas/feedback. + ++ Furnished information on how to configure the 'highlight-parentheses' + package and extend its faces for use with the themes. The entry + provides a complete Elisp implementation. + ++ Improved the code samples for the prism.el setup that users may wish + to set up by themselves. The new lists of colours work better when + Prism's colouration is limited to a small set of hues. + ++ Deleted trailing whitespace in the manual which had adverse effects + when trying to compile the modus-themes.org over at emacs.git. Thanks + to Philip Kaludercic for the patch in merge request 49: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/49>. + +Thanks again to everyone involved. Looking forward to see the Modus +themes, version 1.6.0, as part of the next stable release of Emacs. +#+end_src + +* 1.5.0 +:PROPERTIES: +:CUSTOM_ID: h:05fc633d-69d6-4b5e-aade-1f9e4ba30ed3 +:END: + +#+begin_src text +Modus themes version 1.5.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2021-07-15 + +This entry outlines the set of changes made to the project since the +release of version 1.4.0 on 2021-05-25. There have been over 130 +commits since then. + +Every colour-related modification referenced herein is always +implemented in accordance with the primary accessibility objective of +the themes for a minimum contrast ratio of 7:1 between background and +foreground values in their given combination (the WCAG AAA standard). +Such edits also account for colour-coding that is optimised for the +needs of users with red-green colour deficiency (deuteranopia or +variants). + +Here is the URL of the manual: <https://protesilaos.com/emacs/modus-themes>. +Or read it from Emacs by evaluating this form: + + (info "(modus-themes) Top") + +The themes are built into Emacs version 28 (current development target), +and are available on GNU ELPA as well as other archives. + + +Customisation options +===================== + +Overview of new style of sets of properties +------------------------------------------- + +Several variables now accept a list of symbols as a value. Those +represent properties, which can be combined with each other to realise +the possible styles. The idea was to simplify their specification in +order to make them easier to both maintain and extend. Thanks to Philip +Kaludercic for introducing this concept in issue 210: +<https://gitlab.com/protesilaos/modus-themes/-/issues/210>. + +The variables are: + ++ 'modus-themes-prompts' by Philip Kaludercic in merge request 43: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/43> + ++ 'modus-themes-mode-line' by Philip Kaludercic in merge request 40: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/40>. + ++ 'modus-themes-lang-checkers' by Philip Kaludercic in merge request 46: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/46> + ++ 'modus-themes-org-agenda' ++ 'modus-themes-links' ++ 'modus-themes-headings' ++ 'modus-themes-hl-line' ++ 'modus-themes-paren-match' ++ 'modus-themes-region' ++ 'modus-themes-syntax' + +Take 'modus-themes-syntax' as an example. Up until version 1.4.0, it +would only accept a symbol, signifying a predefined style. So we had +the possible value 'faint' and another 'faint-yellow-comments'. To make +a third variant of the "faint" aesthetic, such as by combining it with +the "alt syntax" and/or "green strings", we would need to write new +presets in the form of 'faint-green-strings', 'faint-alt-syntax', +'faint-alt-syntax-green-strings', 'faint-green-strings-yellow-comments', +'faint-alt-syntax-green-strings-yellow-comments'. That would have been +inefficient, hence why it was not done. + +With the new approach of defining a list of properties, those +combinations are all possible. Such as: + + (setq modus-themes-syntax '(faint alt-syntax)) + + (setq modus-themes-syntax '(yellow-comments alt-syntax green-strings)) + +The order in which the properties are set is not significant. + +The doc string of each of the aforementioned variables, or the +corresponding entry in the manual, provides guidance on how to configure +things. The old forms will continue to work for the time being, though +they are considered deprecated and will stop being supported at a future +date. + + +Changes in stylistic variants for variables with sets of properties +------------------------------------------------------------------- + ++ The meaning of the "alt syntax" style in 'modus-themes-syntax' has + been redefined. In the past, it used to have green-coloured strings + and doc strings. Those are now red. Some other changes have been + implemented to make the overall looks more consistent. Users who + liked the old style can retain it by passing this list of properties: + + (alt-syntax green-strings) + + New styles for the "faint" aesthetic are possible, here shown as lists + of properties: + + (faint green-strings) + (faint alt-syntax) + (faint alt-syntax green-strings) + + To each of those the 'yellow-comments' property can be added as well. + + Consult the doc string or the manual for the technicalities and code + samples. + ++ The 'modus-themes-hl-line' no longer has styles that include only an + underline. Those proved to be problematic under certain circumstances + and were thus removed. + + Minor changes have been implemented to make the following combination + of properties more consistent, by colourising the underline: + + (accented intense underline) + ++ The 'modus-themes-paren-match' now has styles that include an + 'underline' property. Those extend the old options, such as: + + (bold intense underline) + ++ The 'modus-themes-headings' have an improved set of styles for the "no + text color" aesthetic. Those involve the 'monochrome' property, which + can now yield results that include a background (whereas before it was + just colourless text for the headings, optionally without a bold + weight). As this is an alist, here is an example (always check the + docs for fully fledged code samples): + + (setq modus-themes-headings + '((1 . (background overline)) + (2 . (overline background rainbow)) + (t . (monochrome no-bold background)))) + + To allow a heading level N to retain its original style, a 't' value + can be passed. In the previous version of the themes, it was possible + to use 'nil' for the same purpose, though that is no longer valid. In + those cases, the fallback value of the alist will be used instead, + such as what is noted above: + + (t . (monochrome no-bold background)) + ++ The 'modus-themes-links' provide several new possible styles, due to + an expanded set of properties that includes, among others, 'bold', + 'italic', and 'background'. The documentation covers the details. + ++ The 'modus-themes-lang-checkers' can now attain a style that uses a + prominently coloured background in addition to what was available + before as a subtle background and the other variants. + + +New variables +------------- + ++ The 'modus-themes-org-agenda' provides the means to refashion the + entirety of the Org agenda buffer. The value it accepts is an alist, + with some keys expecting a symbol and others a list of properties. + The minutia are covered in its doc string. A possible configuration + can look like this: + + (setq modus-themes-org-agenda + '((header-block . (variable-pitch scale-title)) + (header-date . (grayscale workaholic bold-today)) + (scheduled . uniform) + (habit . traffic-light))) + + 'modus-themes-org-agenda' supersedes the old variable that was specific + to the Org habit graph: 'modus-themes-org-habit'. There now is a + 'habit' key which accepts the same values as before, plus a new style + that is optimised for users with red-green colour deficiency: + 'traffic-light-deuteranopia'. Please consult the doc string of + 'modus-themes-org-agenda' or the relevant entry to the manual. + + Thanks to Gustavo Barros for contributing to the creation of this + variable as well as to all other changes in the relevant faces that + were done in the interest of usability. A full report about + 'modus-themes-org-agenda' with screen shots is available here: + <https://protesilaos.com/codelog/2021-06-02-modus-themes-org-agenda/>. + + A patch has been sent to upstream Org, with its review pending, which + improves upon some of the areas we had identified: + <https://lists.gnu.org/archive/html/emacs-orgmode/2021-06/msg00092.html>. + ++ The 'modus-themes-inhibit-reload' controls a new behaviour of + automatically reloading the active theme when an option is set via the + Custom interfaces or with 'customize-set-variable'. To opt-in to this + feature, set the variable to a 'nil' value. + + Thanks to Philip Kaludercic for implementing this in merge request 40: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/40>. + + In the development phase of this option, a bug was identified + pertaining to recursion, as reported by Gustavo Barros in issue 213: + <https://gitlab.com/protesilaos/modus-themes/-/issues/213>. Changes + have been made to remove that possibility, as found in merge request + 45: <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/45>. + + A thread was started on the emacs-devel mailing list to inquire upon + the technicalities of this option, but it did not gain any traction: + <https://lists.gnu.org/archive/html/emacs-devel/2021-06/msg00828.html>. + + As such, we have decided to take our chances by pressing on with this + feature. Users who are interested in it are encouraged to give it a + try and report any possible complications. Issue 213 remains open. + ++ The 'modus-themes-italic-constructs' is the new name of the variable + 'modus-themes-slanted-constructs'. The term "slant" was considered + too vague or technical and some users could have missed the meaning of + this option. + ++ The 'modus-themes-scale-5' is renamed to 'modus-themes-scale-title' to + better convey its utility. + + +Changes to the manual +===================== + ++ Rewrote or introduced the documentation for all the customisation + options mentioned above. Also updated relevant code samples, such as + in the manual's introduction to the customisation options. Evaluate + this form for an annotated code overview: + + (info "(modus-themes) Customization Options") + ++ Rephrased a reference to "gamma ray values" as "gamma values". Thanks + to Anders Johansson for the contribution in merge request 42: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/42>. + ++ Removed the Org macro that would insert the build date in the manual's + introduction. This was required to make the file reproducible, + otherwise it would keep changing each time a new version of Emacs was + built. Refer to Emacs bug#48661 by Glenn Morris: + <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=48661>. + ++ Included note on tweaking the key hints that the Avy package produces. + This is in response to issue 215 by Rudolf Adamkovič: + <https://gitlab.com/protesilaos/modus-themes/-/issues/215>. Thanks to + Nicolas De Jaeghere for providing the text. + ++ Wrote a note on how to control the underlines that are generated in + compilation-mode buffers and related. It is about configuring the + variable 'compilation-message-face'. + ++ Documented how to configure the colours that are applied to the names + of the days in the 'M-x calendar' interface. The relevant variable is + 'calendar-weekend-days'. + ++ Elaborated on a "do it yourself" (DIY) guide on how to benefit from + the hidden feature of the themes about how they handle the bold weight + and the italic slant. In short, we do not hardcode values and thus + make it easy for users to specify the particularities of what it means + for a face to have a 'bold' or 'italic' attribute. + + +Faces and face groups +===================== + +New entries +----------- + +Newly supported packages: + ++ 'ledger-mode'. Thanks to Pengji Zhang for the feedback in issue 202: + <https://gitlab.com/protesilaos/modus-themes/-/issues/202>. + ++ 'gotest'. Thanks to Jerry Zhang for the feedback in issue 226: + <https://gitlab.com/protesilaos/modus-themes/-/issues/226>. + ++ 'css-mode' + +New faces for already supported groups: + ++ 'shr-h1', 'shr-h2', 'shr-h3', 'shr-h4', 'shr-h5', 'shr-h6' of the + shr.el library (simple HTML renderer, as experienced in, for example, + EWW). Those are available for Emacs28, with a patch by me: + <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=49433> + ++ 'apropos-button' as a generic face that fontifies faces in apropos + buffers. Available for Emacs28, with a patch by me: + <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=49162>. + ++ 'selectrum-mouse-highlight'. This makes the mouse hover effect for + selectrum look the same as in most other contexts. Thanks to okamsn + for the feedback in issue 203: + <https://gitlab.com/protesilaos/modus-themes/-/issues/203>. + + +Review of existing entries +-------------------------- + ++ Added an ':extend' property to 'next-error' face. This face is used + for pulse effects. It is good to have them extend to the edge of the + window, so that they are easier to spot. Thanks to Gustavo Barros for + the feedback in issue 200, which is about pulse.el: + <https://gitlab.com/protesilaos/modus-themes/-/issues/200>. + ++ Tweaked the various Apropos faces. The idea was to remove the colour + from the pseudo headings so that we would not get an exaggerated + result of too much variety in the buffer (e.g. that of 'M-x apropos'). + The individual buttons retain their style as links, meaning that they + are governed by the variable 'modus-themes-links'. + ++ Revised 'whitespace-line' face to make it look like a warning, as it + ought to be. Thanks to Pengji Zhang for the feedback in issue 204: + <https://gitlab.com/protesilaos/modus-themes/-/issues/204>. + ++ Reworked the colour-coding of the Hydra and Transient packages. These + are meant to tone down some excesses with the standard red and to + adapt other colours to it. Thanks to Gustavo Barros for providing + suggestions and helping me tweak those in issue 206: + <https://gitlab.com/protesilaos/modus-themes/-/issues/206>. + ++ Recoloured 'transient-argument' to improve its uniqueness in its + context and to better comply with the expectation of hydra-style + colour coding, as noted right above. + ++ Made the 'org-agenda-done' face conform with the customisation option + 'modus-themes-success-deuteranopia'. This means that it will be + coloured in blue instead of green when the option is set to a non-nil + value. + ++ Grayed out the foreground of the Org block delimiter lines on the + premise that any extra colouration was not needed, given the presence + of a gray background and the overall markup of the block. + ++ Toned down the colouration of the 'org-code' face, so that it is + consistent with 'org-verbatim' as well as the colours used in opening + and closing lines of blocks. Thanks to Gustavo Barros for suggesting + this change in issue 206, though it went through a couple of reviews: + <https://gitlab.com/protesilaos/modus-themes/-/issues/206>. + ++ Simplified the inheritance of the 'fixed-pitch' face, which is used + for internal purposes to ensure alignment of elements in buffers that + must cope with mixed font configurations, such as an org-mode file + with 'M-x variable-pitch-font' enabled. + + [ Recall that the option 'modus-themes-no-mixed-fonts' can disable + this feature. Also note that the 'mixed-fonts' package, or + equivalent, is not needed while using the Modus themes (though there + is nothing wrong with having them together). ] + ++ Reduced the overall intensity of 'org-mode-line-clock-overrun'. + Thanks to Gustavo Barros for the feedback in issue 208: + <https://gitlab.com/protesilaos/modus-themes/-/issues/208>. + ++ Simplified or otherwise tweaked several Org agenda faces to render + possible the new 'modus-themes-org-agenda' variable, as documented + above. Thanks to Gustavo Barros for the feedback in issue 208: + <https://gitlab.com/protesilaos/modus-themes/-/issues/208>. + ++ Increased ever so slightly the foreground colour of the 'highlight' + face. This can help improve the perception of highlights, such as + upon hovering over a link with the mouse. Thanks to Rudolf Adamkovič + for reporting the potential problem in issue 216: + <https://gitlab.com/protesilaos/modus-themes/-/issues/216>. + ++ Prevented the override of the 'diff-context' face when users assign a + 'bg-only' value to the 'modus-themes-diffs' variable. This makes it + consistent with the intent of this style, which is to work with a + non-nil value for 'diff-font-lock-syntax' (basically to allow the + usual colour highlights of the underlying code syntax in diff + buffers). + ++ Ensured consistency of all prompt-related faces by introducing a new + face, 'modus-themes-prompt', that is inherited by all others (all + prompt styles are controlled by the variable 'modus-themes-prompts'). + This was originally implemented with the 'comint-highlight-prompt' + face, though that could potentially lead to undefined faces if the + comint library was not loaded. Whereas the 'modus-themes-prompt' + guarantees that we pass a known face at all times. Thanks to Philip + Kaludercic for bringing this potential bug to my attention in a + comment to merge request 43: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/43#note_615224855>. + ++ Removed the background colour from the 'widget-inactive' face. It + would create problems in some cases, such as in Custom buffers for + multiple choice options. + ++ Refined 'calendar-weekend-header' and 'calendar-weekday-header' to + emulate the design of physical calendars and remain truthful to the + expectations set by the default configuration of the calendar.el + library. Weekends now use a faint red, while weekdays are rendered in + the same subtle gray they had before. The underlying principle is to + make weekends convey a subtle warning to the effect that "this is not + a day for work" (notwithstanding precarious economic realities). As + noted above, there is an entry in the manual on how to make all days + look the same, be it gray or faint red. Evaluate this form: + + (info "(modus-themes) Note on calendarel weekday and weekend colors") + + +Request for feedback on a potential version 2.0.0 of the Modus themes +===================================================================== + +While we maintain a cautious stance towards preserving the default +styles, there are some cases where we might be forced to introduce +backward-incompatible changes. + +Three such cases that can benefit from user feedback are: + ++ Issue 196 on 'modus-themes-no-mixed-fonts' + <https://gitlab.com/protesilaos/modus-themes/-/issues/196>. + ++ Issue 198 on 'modus-themes-hl-line' + <https://gitlab.com/protesilaos/modus-themes/-/issues/198> + + [ Note that 'modus-themes-hl-line now accepts a list of properties as + described in the opening sections of this entry. ] + ++ Issue 218 on 'modus-themes-diffs' + <https://gitlab.com/protesilaos/modus-themes/-/issues/218>. + + +Miscellaneous +============= + ++ Recalibrated the value of the colour 'bg-hl-line-intense' in the + palette 'modus-themes-vivendi-colors'. The change should be + practically indecipherable, though it slightly improves things in + certain contexts. + ++ Refined the intensity of the three main yellow colours in + 'modus-themes-vivendi-colors'. + ++ Introduced a new 'modus-themes-faces' group so that those are + decoupled from the customisation options in the various Custom + buffers. Thanks to Philip Kaludercic for the patch in merge request + 39: <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/39>. + ++ Updated the manual's "Acknowledgements" section to include all new + users who contributed to the project. + +Thanks again to everyone involved! + + +#+end_src + +* 1.4.0 +:PROPERTIES: +:CUSTOM_ID: h:4c643e3c-5284-4fab-97e8-217bc1c02f5d +:END: + +#+begin_src text +Modus themes version 1.4.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2021-05-25 + +This entry records the changes made to the project since the release of +version 1.3.0 on 2021-04-17. There have been around 100 commits in the +meantime, as is the norm. + +If you are coming from older versions, please consult the change log +entry for version 1.0.0 with regard to the breaking changes that were +introduced. + +Every colour-related modification is always done in accordance with the +overarching accessibility objective of the themes for a minimum contrast +ratio of 7:1 between background and foreground values in their given +combination (the WCAG AAA standard). + +URL of the official manual: <https://protesilaos.com/emacs/modus-themes>. Or +read it with Emacs' Info reader by evaluating this form: + + (info "(modus-themes) Top") + +Remember that the themes are built into Emacs version 28 (current +development target), and are available on GNU ELPA, as well as other +archives. + + +Customisations variables +------------------------ + ++ Redefined the style of 'fg-only' that 'modus-themes-diffs' accepts, so + that it no longer uses a red-green colour coding, but applies a + red-blue distinction instead. The symbol 'fg-only' is a deprecated + alias for the more descriptive 'fg-only-deuteranopia'. + + This is done because green text on a light background is one of the + worst combinations for the purposes of legibility, as it does not + stand out in its context and thus forces undesirable compromises. + Whereas red and blue work well in this case, while making the style + accessible to users with red-green colour deficiency (deuteranopia). + To avoid inconsistencies between Modus Operandi and Modus Vivendi, we + replace green with blue in both themes. A full report is available in + issue 183 which was created on April 21, 2021: + <https://gitlab.com/protesilaos/modus-themes/-/issues/183>. + ++ Introduced the boolean 'modus-themes-success-deuteranopia' which + replaces all instances of green with blue in contexts where a + red-green colour coding is in effect (e.g. Org TODO vs DONE keywords, + isearch current match...). + ++ Implemented 'modus-themes-mail-citations' to control the colouration + of cited text in email-related buffers, such as Gnus or message.el. + It accepts values nil, 'faint', and 'monochrome'. By default (the nil + value) the text of citations cycles through blue, green, red, yellow + depending on the level of depth. + ++ Expanded the set of options for 'modus-themes-mode-line' to encompass + the values 'borderless-accented', 'borderless-accented-3d', and + 'borderless-accented-moody'. Those are variations of existing styles. + The complete list: + + - nil (default) + - 3d + - moody + - borderless + - borderless-3d + - borderless-moody + - accented + - accented-3d + - accented-moody + - borderless-accented + - borderless-accented-3d + - borderless-accented-moody + ++ Renamed the non-nil values that 'modus-themes-org-blocks' accepts from + 'grayscale', 'rainbow' to 'gray-background' and 'tinted-background', + respectively. The new symbols better describe their effect on Org + source blocks, namely, that they affect the background of the block + rather than the foreground. The old symbols will still work but are + considered deprecated aliases of the newer ones. + ++ Altered the intensity of the 'modus-themes-hl-line' option + 'accented-background' to a more noticeable shade of cyan/teal. The + old style was too subtle to have the desired effect. The value + 'underline-accented' is not affected by this change, as it still uses + the same subtle background it did before in combination with a more + pronounced underline colour. + ++ Deleted all deprecation warnings that concerned the transition from + version 0.13.0 of the themes to 1.0.0. Those had been in effect for + several months, spanning four tagged releases. + + +Faces or face groups +-------------------- + ++ Reconsidered the use of colour in all email-related citation faces to + avoid exaggerations and reduce complexity. Colour values have been + tweaked to tone down their overall intensity, while the number of + colours has been reduced to four. Gnus and Mu4e have faces for more + levels of citation depth, though those will simply repeat the + four-colour cycle. + ++ Made the 'message-mml' face look consistent with the rest of the + buffer while composing an email by changing its foreground colour from + a yellow to a cyan variant. + ++ Refined several faces in the Notmuch group in the interest of harmony: + + - Individual message headers in 'notmuch-show-mode' use bold text in + addition to their existing subtle background to better stand out in + their context. The face is 'notmuch-message-summary-face'. + + - Tags are no longer set unconditionally to a bold typographic weight. + They become such for unread threads in 'notmuch-search-mode' + buffers, as well as for headers of 'notmuch-show-mode'. + + - Removal and addition of tags is now denoted by a strike-through and + an underline effect, respectively, whereas before they both used + underlines with the only difference being their colour. + + - The subject line in 'notmuch-search-mode' buffers uses the main + foreground instead of a dimmed one. The field of matching authors + has a tweaked foreground to keep the tabular view easy to read. + + - All cryptography-related faces are simplified to not show a coloured + background but only use a foreground colour instead. + ++ Removed direct support for 'counsel-notmuch' as it already inherits + from the relevant notmuch faces. The package is thus considered + indirectly supported. + ++ Refrained from setting a background to the 'csv-separator-face' as it + would inevitably colourise the negative space in the tabular view + created by 'csv-align-mode'. A red text colour is used instead, even + though this is not common practice: it is easier to spot for small, + single characters, such as a comma or a semicolon that is meant to + have a special meaning. Thanks to Kevin Fleming for reporting the + problem and for offering feedback on the choice of colour in issue + 194: <https://gitlab.com/protesilaos/modus-themes/-/issues/194>. + ++ Distinguished between ordinary links and widget buttons by removing + the underline from the latter (the 'widget-button' face) and altering + the shade of its foreground colour. Such widgets are used in Emacs' + Custom interfaces and can also be found in the default Notmuch "hello" + buffer that runs 'notmuch-hello-mode'. + ++ Tweaked the Ediff current faces to be consistent with 'diff-mode' and + related. In practice, this only applies when 'modus-themes-diffs' is + set to a value of 'fg-only-deuteranopia', as it adds a dim background + to the current diff hunk. All other styles of 'modus-themes-diffs' + look the same as before while using Ediff. + ++ Simplified the faces of 'corfu' to match the current state of the + upstream project. Thanks to Daniel Mendler (its developer) for + reporting this in issue 184: + <https://gitlab.com/protesilaos/modus-themes/-/issues/184>. + ++ Refined all Eshell faces so that the output of 'ls' is consistent with + the overall aesthetic of the themes. Also made 'eshell-prompt' + inherit from 'comint-highlight-prompt' to look the same as other such + prompts (all are configurable by 'modus-themes-prompts'). + ++ Revised 'eshell-prompt-extras' and 'eshell-git-prompt' to use colours + and typographic weight that better match the style of the various + configurations they offer. + ++ Simplified 'eshell-syntax-highlighting' to inherit from the standard + Eshell faces, where appropriate. + ++ Adjusted the colour of 'centaur-tabs-active-bar-face' and removed the + bespoke 'fg-tab-accent' colour from 'modus-themes-operandi-colors' and + 'modus-themes-vivendi-colors' that was only used by it (and which + should have never been introduced to begin with). + ++ Updated the 'tab-bar-groups' faces to match changes upstream. Thanks + to Fritz Grabo (its developer) for the patch in merge request 35: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/35>. + ++ Changed the Ibuffer title and group faces to better differentiate + between group titles and special or non-file-visiting buffers. Thanks + to Nicolas De Jaeghere for the patch in merge request 37: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/37>. + ++ Ensured that all faces that denote a "success" state, or which are + expected to be coloured in green in a red-green binary, can use an + appropriate blue colour (or colour combination that involves blue) + instead when 'modus-themes-success-deuteranopia' is set to a non-nil + value. + ++ Added support for the new 'bookmark-face' in Emacs version 28. This + means that the built-in bookmark.el library is directly supported by + the themes. This face can be disabled by setting 'bookmark-fontify' + to nil. Thanks to Mark Barton for reporting the presence of this new + face and for providing feedback on its style in issue 189: + <https://gitlab.com/protesilaos/modus-themes/-/issues/189>. + ++ Aligned 'hes-mode' ('highlight-escape-sequences') with the standard + font-lock faces for regexp grouping. This means that it conforms with + changes to the 'modus-themes-syntax' variable. + ++ Reconfigured the 'org-quote' face to adapt its style depending on the + value of 'modus-themes-org-blocks'. The default is a subtle blue/cold + foreground colour against the main background. When a value of + 'gray-background' is assigned to 'modus-themes-org-blocks', the text's + colour becomes that of the main foreground in order to maintain a good + level of legibility. Thanks to Rudolf Adamkovič for the feedback in + issue 190: <https://gitlab.com/protesilaos/modus-themes/-/issues/190>. + ++ Refashioned the 'show-paren-match-expression' face to make it apply a + bespoke background colour and not override the expression's foreground + colours. This face is used by 'show-paren-mode' when the + customisation variable 'show-paren-style' is set to the 'expression' + value. Thanks to Rudolf Adamkovič for the feedback in issue 191: + <https://gitlab.com/protesilaos/modus-themes/-/issues/191>. + ++ Made headings level 8 use a fine shade of magenta by default instead + of gray (notwithstanding user changes to 'modus-themes-headings'). + This should have a negligible difference in Org or Outline buffers, + but is more noticeable when editing Elisp in Emacs28 while also using + 'outline-minor-mode' and with 'outline-minor-mode-highlight' set to + 'override'. That is because several top-level forms use that heading + level with those configurations. + + +Documentation (the manual) +-------------------------- + ++ Incorporated a sample configuration block with all customisation + variables and with comment annotations of their available options, in + an attempt to make it easier for users to discover what the themes + provide. + ++ Replaced all instances of "modeline" with "mode line" for consistency + with the Emacs style. Thanks to Rudolf Adamkovič for the patch that + started this process in merge request 33: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/33>. + ++ Wrote note on setting mode line faces that indicate the state of + 'god-mode'. Thanks to Rudolf Adamkovič for the feedback in issue 187: + <https://gitlab.com/protesilaos/modus-themes/-/issues/187>. Also + thanks to Rudolf for updating the applicable hook in merge request 34: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/34>. + ++ Listed 'org-mode' variables that affect fontification in blocks: + 'org-src-fontify-natively', 'org-fontify-whole-block-delimiter-line', + and 'org-fontify-quote-and-verse-blocks'. This complements the + already documented variables 'org-fontify-whole-heading-line' and + 'org-fontify-done-headline' that pertain to headings. + ++ Included note on fontifying inline Latex expressions in Org buffers. + Thanks to Rudolf Adamkovič for the feedback in issue 190: + <https://gitlab.com/protesilaos/modus-themes/-/issues/190>. + ++ Elaborated on the use of 'face-remap-add-relative' by means of sample + code that cycles through arbitrary colours for the 'region' face. + This is filed under the "Do It Yourself" (DIY) section. + ++ Provided a DIY method for adapting the fontification of Org source + block delimiter lines to the value of 'modus-themes-org-blocks'. + ++ Expanded the DIY entry on overriding the saturation of the active + theme's colours with a method that combines the programmatic approach + with manual overrides. The user can thus specify the colour values + they want to override and let the rest be handled by Elisp. + ++ Introduced a section with answers to Frequently Asked Questions (FAQ) + about the design of the themes as well as recommendations on how to + ensure optimal reading conditions or start thinking about them. The + questions are: + + - Is the contrast ratio about adjacent colors? + - What does it mean to avoid exaggerations? + - Why are colors mostly variants of blue, magenta, cyan? + - What is the best setup for legibility? + + +Miscellaneous +------------- + ++ Removed superfluous code from internal functions and adapted their + indentation to make them easier to read. + ++ Recalibrated some values in 'modus-themes-vivendi-colors' to ensure + consistency in luminance with other colours that are used in their + context. Those are subtle changes that can only be discerned in + side-by-side comparisons of the before and after states. Thanks to + André Alexandre Gomes for the feedback in issue 193: + <https://gitlab.com/protesilaos/modus-themes/-/issues/193>. + ++ Changed the saturation and hueness of the bespoke 'fg-comment-yellow' + in 'modus-themes-operandi-colors' and 'modus-themes-vivendi-colors' to + better contrast with its context, while still keeping its luminance + consistent with its role as a colour for comments in code. This is + used when 'modus-themes-syntax' is configured appropriately (read its + doc string or consult the manual). + ++ Attempted to add explicit support for the faces of the built-in + pulse.el library, but ultimately opted against them as the doc string + of 'pulse-highlight-face' advises against customising it, even though + it is not clear from the source code in emacs.git what the problem + could be. We shall reconsider this case for the next release cycle. + Thanks to Gustavo Barros for the feedback on several aspects of this + topic in issues 185 and 200: + + - <https://gitlab.com/protesilaos/modus-themes/-/issues/185> + - <https://gitlab.com/protesilaos/modus-themes/-/issues/200> + ++ Took the feedback of John Haman in issue 199 as a reminder to complete + the set of possible values for the 'modus-themes-mode-line' variable: + <https://gitlab.com/protesilaos/modus-themes/-/issues/199>. +#+end_src + +* 1.3.0 +:PROPERTIES: +:CUSTOM_ID: h:5063c0c5-832e-4577-936e-d602b07d6d79 +:END: + +#+begin_src text +Modus themes version 1.3.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2021-04-17 + +This entry records the changes introduced to the project since the +publication of version 1.2.0 (2021-03-04). There have been around 100 +commits in the meantime, as is the norm with all releases hitherto. + +Every colour-related modification documented herein conforms with the +overarching accessibility objective of the themes for a minimum contrast +ratio of 7:1 between background and foreground values in their given +combination (the WCAG AAA standard). + +As the official manual is referenced several times throughout this log, +make sure to store its URL: <https://protesilaos.com/emacs/modus-themes>. Or +read it from Emacs' Info reader by evaluating this form: + + (info "(modus-themes) Top") + +If you are coming from older versions, please consult the change log +entry for version 1.0.0 with regard to the breaking changes that were +introduced. + +Remember that the themes are built into Emacs28, and are available on +GNU ELPA, as well as other archives. + + +Customisation options +--------------------- + ++ The old 'modus-themes-intense-hl-line' boolean variable has been + replaced by 'modus-themes-hl-line', which provides several options for + how to style the current line of 'hl-line-mode'. To retain the old + effect, one must do this: + + ;; Replacement for (setq modus-themes-intense-hl-line t) + (setq modus-themes-hl-line 'intense-background) + + The list of possible values: + + 1. nil (default) + 2. intense-background + 3. accented-background + 4. underline-neutral + 5. underline-accented + 6. underline-only-neutral + 7. underline-only-accented + + The doc string of 'modus-themes-hl-line' as well as the manual + describe the specifics. Thanks to Manuel Uberti for the feedback in + commit b020592: + <https://gitlab.com/protesilaos/modus-themes/-/commit/b020592e1a96d6e00d7d03faf9c293ec6081d49c>. + ++ The 'modus-themes-mode-line' variable now accepts three new "accented" + styles that complement the existing set: + + 1. nil (default) + 2. 3d + 3. moody + 4. borderless + 5. borderless-3d + 6. borderless-moody + 7. accented + 8. accented-3d + 9. accented-moody + ++ The 'modus-themes-region' is extended with two new options of an + "accent" background: + + 1. nil (default) + 2. no-extend + 3. bg-only + 4. bg-only-no-extend + 5. accent + 6. accent-no-extend + ++ The default value of 'modus-themes-headings' for per-level styles can + now be set to nil. This fixes an inconsistency between the fallback + value, which accepted nil, and the per-level styles which did not. + Thanks to Mauro Aranda for reporting this in issue 163: + <https://gitlab.com/protesilaos/modus-themes/-/issues/163>. + + Please read the manual for the specifics of this variable, as it is an + alist that accepts several possible combinations. + + +Updates to the manual +--------------------- + ++ Rewrote the sections that cover the aforementioned customisation + options. + + - For 'modus-themes-mode-line', we had to revise the recommendation + for setting 'face-near-same-color-threshold' to 45000. That value + is appropriate for the 'moody' and 'borderless-moody' options. + Whereas for 'accented-moody' the number should be raised to 70000. + Thanks to Nicolas De Jaeghere for providing this piece of + information: + <https://gitlab.com/protesilaos/modus-themes/-/commit/ab6ba698269f012ec880b690282264649bfb3b0d#note_551342198> + ++ Rephrased the GNU Free Documentation License quote to match the style + of other manuals that are also built into Emacs. + ++ Documented 'org-mode' variables that affect the looks of various + fontification styles. + ++ Simplified the 'kbd' macro that is declared in modus-themes.org to + allow GNU ELPA's build system to parse the file for Emacs 26. + ++ Documented existing support for 'tab-bar-mode' and 'tab-line-mode'. + ++ Wrote a note on how to configure the 'dimmer.el' library by Neil + Okamoto, in order to guarantee consistent results with the themes. + The key is to use the RGB colour space instead of CIELAB. + ++ Included note on shr.el fonts and how those are used by EWW and + Elfeed. + ++ Added a "Do-It-Yourself" (DIY) section on how to remap buffer-local + faces. + ++ Detailed a DIY method to make the buffer-local backdrop of a pdf-tools + page use a distinct colour than the default white for Modus Operandi. + Extended the same principle to Modus Vivendi and described how to + adapt to theme changes (such as via 'modus-themes-toggle'). Thanks to + Utkarsh Singh for providing feedback on this topic in issue 175: + <https://gitlab.com/protesilaos/modus-themes/-/issues/175>. + ++ Elaborated on DIY techniques to programmatically override the + saturation of all colours specified by the active Modus theme. Thanks + to user pRot0ta1p for the feedback in issue 166: + <https://gitlab.com/protesilaos/modus-themes/-/issues/166>. + + +Support for packages +-------------------- + +These are added to the already comprehensive list of explicitly +supported packages: + ++ corfu ++ embark + ++ pandoc-mode. Thanks to Farasha Euker for the feedback in issue 171: + <https://gitlab.com/protesilaos/modus-themes/-/issues/171>. + ++ tab-bar-groups ++ telega ++ vertico + +Also added support for the 'help-key-binding' face which is part of +Emacs 28. + + +Changes to already supported faces or face groups +------------------------------------------------- + ++ Renamed all internal faces that the themes defined from + "modus-theme-*" to "modus-themes-*". + ++ Refashioned all Ediff faces in the process of a major review of this + tools' overall design. The manifold changes are: + + - All inactive diffs respect the underlying fontification + (e.g. programming syntax highlighting). Before they would override + it with a gray foreground. + + - All inactive diffs have been toned down, as their background is a + finer shade of gray than the prominent one that was used before. + + - There no longer is a visual distinction between even and odd + inactive diffs (by means of different shades of gray). We are of + the opinion that such subtleties, whose utility is marginal at best, + have no place in themes that are designed for accessibility. + + - All bespoke gray colour combinations that were only intended for + those inactive diffs have thus been removed from each theme's + palette. + + - Active diffs follow the same style as diff-mode, to ensure + theme-wide consistency (all diff styles are controlled by the + variable 'modus-themes-diffs'). + + This topic was discussed at length (with screenshots) in issue 169: + <https://gitlab.com/protesilaos/modus-themes/-/issues/169>. Thanks to + peniblec and Nicolas De Jaeghere for their feedback. + ++ Made 'smerge-markers' and 'vdiff-closed-fold-face' look like the + headings in 'diff-mode' in the interest of consistency, especially + while configuring the 'modus-themes-diffs' variable. + ++ Ensured consistency between all faces that pertain to key bindings in + contexts where the hint to the key is active, in that pressing the key + performs the action (e.g. Magit's transient buffers, which-key,...). + The 'help-key-binding' for Emacs 28 is not included in this group, + because it applies in cases where the keys are not active, such as in + Help buffers. + ++ Refined 'epa-validity-disabled' and 'epa-validity-high' faces. The + former no longer uses a background, as that was considered an + exaggeration. While the latter is cast in a cyan hue instead of green + for greater clarity (this relates to the general push to optimise for + red-green colour deficiency, which means to only use green where it is + absolutely necessary and, in such cases, to provide for a blue-ish + alternative, as with the 'deuteranopia' value that can be assigned to + 'modus-themes-diffs'). + ++ Reworked 'ace-window', 'avy', and 'magit-blame' faces to ensure that + their overlays do not inherit the face properties of underlying text, + such as a different font family or height. Thanks to Nicolas De + Jaeghere for the multiple merge requests and the concomitant feedback: + + - <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/27>. + - <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/29>. + - <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/30>. + - <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/31>. + - <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/32>. + + Also thanks to Damien Cassou for reporting an intermediate problem + with 'avy' in issue 177; a problem that was eventually addressed by + Nicolas De Jaeghere in merge request 31 (cited above): + <https://gitlab.com/protesilaos/modus-themes/-/issues/177>. + ++ Optimised the colour combinations used by 'avy' to improve the + distinction between consecutive characters. + ++ Reduced the brightness of EWW certificate faces, as they would attract + disproportionate attention to themselves. + ++ Reworked all EWW text field and button faces to look more like what + they are supposed to. + ++ Removed the slant and distinct foreground from the 'org-quote' face, + as they would interfere with emphasis within the quote block. Thanks + to Farasha Euker for the feedback in issue 171: + <https://gitlab.com/protesilaos/modus-themes/-/issues/171>. + ++ Reduced the intensity in colouration of 'org-code' and 'org-macro' in + order to avoid exaggerations and prevent their compounding effect in + technical documents that include a high concentration of those faces. + They still retain their overall character and continue to look like + variants of 'org-verbatim'. + ++ Extended support for Selectrum's new 'selectrum-quick-keys-highlight' + and 'selectrum-quick-keys-match'. + ++ Adjusted a few bongo faces for improved consistency and a more + pleasant result overall. Quote from commit 07224cda08: + + Refine bongo faces for consistency + + The previous design was meant to keep the track fields distinct + from each other. However the use of yellow was not good + aesthetically: it does not fit with the rest of the theme. + + Upon further experimentation, I realised that the album field + (yellow) is only present when the artist and title fields are also + available: first is the title, then the artist, and finally the + album. This is true even with 'bongo-join-inserted-tracks' set to + a non-nil value. So changing the face from yellow to a neutral + value is safe. + + The other two faces are adapted to look better in the new context. + ++ Made more command prompt faces respond to changes in the variable + 'modus-themes-prompts'. This concerns faces from the groups cider, + circe, erc, indium, rcirc. + ++ Refashioned typescript faces, making them more prominent by default, + while also exposing them to the value of 'modus-themes-syntax'. + ++ Revised the style of 'info-colors-ref-item-command'. This makes + commands look the same as functions, which is technically correct. It + also predicates the exact style on the value of the variable + 'modus-themes-syntax'. + ++ Made all enh-ruby-mode faces adapt to 'modus-themes-syntax'. Same for + julia. + ++ Reconfigured all ztree faces for stylistic consistency. The + 'ztreep-diff-model-add-face' now responds to the 'deuteranopia' value + that can be passed to 'modus-themes-diffs'. + ++ Appended the ':extend t' attribute to 'gnus-summary-cancelled' and + 'gnus-summary-selected'. These are only noticeable on Emacs 28 + following commit 88409b21c2 in emacs.git. + ++ Tweaked all faces of 'highlight-changes-mode' to better deliver on the + intent of that mode. + ++ Opted to unconditionally render all 'dired-async' faces in a bold + typographic weight, instead of basing them on a non-nil value for + 'modus-themes-bold-constructs'. Also changed 'dired-async-message' to + a blue foreground, which further improves the themes' performance for + red-green colour deficiency. + ++ Adjusted the colours of some 'notmuch-crypto-*' faces to better convey + their meaning. + ++ Removed remaining conditional logic for underline styles in some + spell- and linter- related faces to ensure that all such cases are + controlled by the variable 'modus-themes-lang-checkers' (building on + work that had been done in the past). + ++ Stopped changing 'keycast-key' to match the modeline style, as that + diluted the meaning of the variable 'modus-themes-mode-line'. + ++ Tweaked calendar and diary faces for stylistic effect, except for the + 'diary' face which has been converted from a green to a blue variant + for the purposes of coping with cases of red-green colour deficiency. + + +Miscellaneous +------------- + ++ Clarified the changes in the backward-incompatible transition from + version 0.13.0 of the themes to >= 1.0.0. Thanks to Damien Cassou for + reporting the absence of easy-to-find information in issue 174: + <https://gitlab.com/protesilaos/modus-themes/-/issues/174>. + ++ There were three point releases after 1.2.0 which refined certain + aspects of the themes' packaging so that they could work both as + built-in themes for Emacs as well as in package format via the likes + of GNU ELPA. Those issues were eventually resolved by Basil + L. Contovounesios: + + - Issue 162: <https://gitlab.com/protesilaos/modus-themes/-/issues/162>. + - Emacs bug#45068: <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=45068#218>. + ++ Rewrote the 'modus-themes-headings' variable's declaration to improve + its presentation in Custom interfaces. Thanks to Mauro Aranda for + submitting the patch for commit 1c60927ebd. + ++ Applied the ':format' keyword to all 'defcustom' forms, based on the + aforementioned patch. This should make all options look better in the + various Custom interfaces. Thanks to Mauro Aranda for the feedback in + issue 163: <https://gitlab.com/protesilaos/modus-themes/-/issues/163>. + ++ Refined the colour values 'bg-alt' and 'bg-dim' in 'modus-vivendi' to + improve their instantiation on Textual User Interfaces. In + particular, recalibrated the blue channel of light so that when the + TUI cannot render the colour directly, it defaults to a gray value + instead of a dark blue. + ++ Added a "Last-Modified" meta header to modus-themes.el, with gets + updated automatically and uses a timestamp. This helps users who + track the themes' git repo directly. Thanks to Togan Muftuoglu for + the feedback in issue 168: + <https://gitlab.com/protesilaos/modus-themes/-/issues/168>. + ++ Expanded the palette of each theme with accent values that are + reserved for use in the tab-bar. Those are used by the newly + supported 'tab-bar-groups' package. + ++ Recalibrated a few colour combinations to improve their resulting + legibility. The changes should not be noticeable to the untrained + eye. Interested parties can consult commit 349ea4a943. + ++ Tweaked the hueness of the 'yellow-active' colour of 'modus-operandi'. + +Thanks once again to everyone involved! +#+end_src + +* 1.2.0 +:PROPERTIES: +:CUSTOM_ID: h:751083a7-3514-40f5-9928-17a11de5b439 +:END: + +#+begin_src text +Modus themes version 1.2.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2021-03-04 + +This entry records the changes introduced to the project since the +publication of version 1.1.0 (2021-01-24). There have been close to 100 +commits in the meantime. + +Every colour-related modification documented herein conforms with the +overarching accessibility objective of the themes for a minimum contrast +ratio of 7:1 between background and foreground values in their given +combination (the WCAG AAA standard). + +As the official manual is referenced several times throughout this log, +make sure to store its URL: <https://protesilaos.com/emacs/modus-themes>. Or +read it from Emacs' Info reader by evaluating this form: + + (info "(modus-themes) Top") + +If you are coming from older versions, please consult the change log +entry for version 1.0.0 with regard to the breaking changes that were +introduced. + + +Prior notice: Upgrading the themes in Emacs28 and GNU ELPA +---------------------------------------------------------- + +Emacs28, the current development target, now includes a 'require-theme' +function. It is a prerequisite to upgrading the Modus themes to their +current version. Prior to the definition of that function, the themes +could not transition from their 0.13.0 version to >=1.0.0. Special +thanks to Basil L. Contovounesios for making it happen, as well Mauro +Aranda and Eli Zaretskii for their feedback and support. + +Expect the Modus themes in upstream Emacs to be updated shortly after +the publication of this document. + +GNU ELPA currently ships version 0.12.0 of the two standalone packages +'modus-operandi-theme' and 'modus-vivendi-theme'. This will change in +the immediate future, as a new 'modus-themes' package will succeed them. +That new package will be built directly from emacs.git, as it must now +become a ':core' entity instead of being listed as an ':external' one. + +Again, expect a patch to be applied to elpa.git shortly after this +document goes live. + + +Customisation options +--------------------- + +[ All variables and their values are documented in the themes' manual. + The default value is always nil. ] + ++ The new boolean 'modus-themes-subtle-line-numbers' variable will make + the effect of 'display-line-numbers-mode' more subtle when set to a + non-nil value. It removes the underlying background of the unfocused + lines while toning down their foreground. + ++ The 'modus-themes-diffs' variable now accepts a 'deuteranopia' value. + This optimises for red-green colour deficiency in all modes that show + diffs (diff-mode, ediff, Magit...). In practice, all instances of + green are replaced with appropriate blue hues. For more on the + matter, read the report which also includes pictures: + <https://protesilaos.com/codelog/2021-02-25-modus-themes-diffs-deuteranopia/>. + ++ The 'modus-themes-syntax' variable now reads 'faint-yellow-comments' + as a valid value. This has the same scope as the existing 'faint' + value with the added effect of assigning a yellow tint to comments: it + tones down the saturation of colours that apply to code syntax + (standard font-lock faces and others inheriting from them). + ++ The 'modus-themes-links' variable is expanded to accept the new value + of 'neutral-underline-only': it removes the foreground from the link + and draws a neutral gray underline below it. + + +Refinements to existing packages or face groups +----------------------------------------------- + ++ Refashioned all faces that pertain to emails, including Gnus, Mu4e, + Notmuch, and the standard 'message.el' library. This concerns the + colours that apply to the message header keys and their values, as + well as quote levels. + + - Introduced more contrasting hues for headings and made more + considerate use of bold typography. The new colour combinations are + better suited for the task of delivering a sense of structure; + structure that is at once effective and subtle. + + - Applied less intense colours throughout all quotation levels. + + - Revised the sequencing of hues in quotation levels to allow distinct + levels to stand out more without relying on excessive saturation. + + - Aligned the styling of Notmuch header dates with their counterparts + in other similar contexts, in pursuit of theme-wide consistency. + ++ Rewrote the faces of EBDB to achieve a better sense of structure. + ++ Refined the colour combinations of change-log and log-view buffers to + make it easier to discern distinct elements. + ++ Tweaked the colours of certain Elfeed constructs to improve the + overall presentation of its search buffers. + ++ Changed the colour combinations of 'M-x re-builder' to amplify the + distinction between the matching regexp groups while still reducing + their overall intensity. + ++ Reconfigured the 'diff-changed' face to always extend its background + to the edge of the window. Such "changed" lines are visible in + 'diff-mode' buffers when the command 'diff-unified->context' is + invoked. + ++ Tweaked the colour combinations of ancillary faces in diff buffers + when the variable 'modus-themes-diffs' is set to the value 'fg-only'. + In particular: + + - Removed the subtle background from the diff hunk headings and changed + their colour to ensure good visibility---guarantees a sense of + structure. + + - Made the context lines inherit the default foreground colour (pure + black/white), so that it contrasts better with red, green, and + yellow text. + + - Applied an accented foreground to the diff header. This is to + ensure that it is not mistaken for a diff hunk's context. + + All these guarantee that the foreground-only highlights in line-wise + differences draw more attention to themselves. + ++ Aligned all the standard hi-* faces with their default aesthetics. + Those are used by commands such as 'highlight-symbol-at-point'. + Thanks to Philip K. for the valuable feedback in issue 157: + <https://gitlab.com/protesilaos/modus-themes/-/issues/157>. + ++ Removed obsolete Consult faces and added new ones, so as to remain in + sync with the latest developments in that project. Thanks to Daniel + Mendler (Consult's maintainer) for reporting the inconsistency in + issue 155: <https://gitlab.com/protesilaos/modus-themes/-/issues/155>. + + - 'consult-preview-line' now retains fontification on the current + line, instead of applying its own foreground. + + - 'consult-narrow-indicator' is refashioned to be colour-coded in a + consistent way with 'consult-async-split', as both denote the + delineation of a given scope. + + - 'consult-imenu-prefix' contrasts better with text on its current + line, while it adapts to possible customisations performed on the + Consult front. + ++ Expanded the coverage of 'marginalia' faces to two include + 'marginalia-char' and 'marginalia-type'. This is done in the interest + of internal consistency between the elements of this set, as their + defaults were also accessible (they inherit from standard faces that + we already support). + ++ Opted to render the Notmuch logo in a neutral gray backdrop. This was + deemed necessary as the logo is an immutable image file that consists + of black and white strokes. Black and white are the main background + values of 'modus-vivendi' and 'modus-operandi' respectively, which + could lead to confusion. The neutral gray ensures that the logo is + visible at all times. Thanks to Utkarsh Singh for the feedback in + issue 122: <https://gitlab.com/protesilaos/modus-themes/-/issues/122>. + ++ Refined the dedicated colour values used for diff hunk headings, as + seen in diff-mode buffers or Magit. The new colours yield text that + is easier to read by slightly toning down the combined intensity of + background+foreground. + ++ Removed the subtle background of 'diff-header' and 'diff-file-header'. + The header's foreground and textual representation suffice to render + it distinct in its context. + ++ Tweaked 'org-agenda-structure' and 'org-scheduled' to enhance the + usability of Org Agenda buffers. + + - Made 'org-agenda-structure' use the largest possible height that we + expose to users: 'modus-themes-scale-5'. + + - Re-calibrated the hueness of 'org-scheduled' and amplified its + saturation, in order to better convey the meaning of a scheduled + task. + + Thanks to Morgan Smith for the valuable feedback in issue 153: + <https://gitlab.com/protesilaos/modus-themes/-/issues/153>. + ++ Tweaked the faces of the 'bongo' package to enhance the + distinctiveness of the constructs they style. + ++ Adjusted the overall aesthetic of calendar faces in the interest of + theme-wide consistency. + ++ Aligned the visual metaphors of 'org-code' with those of 'org-macro' + and 'org-verbatim', by ensuring that a subtle background is present + behind the affected text, while the foreground conforms with the norms + of the 'modus-themes-no-mixed-fonts' customisation option. + ++ Made quoted text in Info buffers look the same as 'org-verbatim' and + Markdown's inline code. + ++ Instructed the faces of 'info-colors' to inherit from appropriate + font-lock faces. This guarantees that everything works as intended + with the various values of 'modus-themes-syntax'. + ++ Refined the language tag of Markdown fenced blocks so that it does + attract unwarranted attention while delivering on its intended + purpose. + ++ Rendered explicit the slant of ace-window hints, guaranteeing that it + does not inherit from the underlying text. Thanks to Nicolas De + Jaeghere for the patch: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/27>. + + [ Some more changes have been discussed, but those require tweaks to + the upstream package. ] + ++ Ensured that the 'org-tree-slide-header-overlay-face' never draws an + overline when the variable 'modus-themes-headings' includes a relevant + setting for heading level 1. Such as with the following example (all + customisation options are documented in the themes' manual): + + (setq modus-themes-headings + '((1 . section) + ...)) + ++ Extended support for the new 'tab-line-tab-inactive-alternate' face as + that occurs in Emacs28 (current development target). It comes into + effect when the variable 'tab-line-tab-face-functions' includes a + value of 'tab-line-tab-face-inactive-alternating'. + + +Newly supported packages +------------------------ + ++ bbdb :: Thanks to Nicolas De Jaeghere in issue 128: + <https://gitlab.com/protesilaos/modus-themes/-/issues/128>. + ++ mmm-mode :: Thanks to Davor Rotim for the feedback in issue 161: + <https://gitlab.com/protesilaos/modus-themes/-/issues/161>. + ++ quick-peek :: Thanks to Burgess Chang for the feedback in issue 151: + <https://gitlab.com/protesilaos/modus-themes/-/issues/151> + ++ selectrum-prescient :: This new package was brought to my attention by + Manuel Uberti. The intent is to phase out the faces in Selectrum, + namely 'selectrum-primary-highlight', 'selectrum-secondary-highlight', + though those will still be supported by the Modus themes for the + foreseeable future. + ++ shortdoc + ++ spray + ++ terraform-mode :: Thanks to Kevin Fleming for the feedback in issue + 159: <https://gitlab.com/protesilaos/modus-themes/-/issues/159>. + ++ vc-dir (Emacs28) + + +Theme-related contributions to the wider community +-------------------------------------------------- + ++ Contributed the faces for 'vc-dir' in Emacs28 and applied them to all + VC backends: <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=46358> and + <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=46745>. + ++ Contributed a new face and some related tweaks to Emacs' + 'shortdoc.el': <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=46748>. + ++ Added faces to the 'tab-bar-echo-area.el' package: + <https://github.com/fritzgrabo/tab-bar-echo-area/pull/2>. + ++ Reported issue that led to the review of the header face in + 'org-tree-slide': <https://github.com/takaxp/org-tree-slide/issues/38>. + ++ Helped refine the faces of the 'rlist.el' package: + <https://gitlab.com/mmemmew/rlist/-/commit/386f506d0110bebedd3a48ff972adba96e2232eb>. + + +Documentation updates +--------------------- + ++ Wrote about the indirect support for the 'goggles' package. I had + helped write its faces, as was documented in the changelog for version + 1.1.0 of the themes. Thanks to Manuel Uberti for bringing this to my + attention in issue 158: + <https://gitlab.com/protesilaos/modus-themes/-/issues/158>. + ++ Explained that any changes to 'custom-theme-load-path' and/or + 'custom-theme-directory' should be performed before the themes are + loaded. Thanks to Adrian Manea for the feedback in issue 156: + <https://gitlab.com/protesilaos/modus-themes/-/issues/156>. + ++ Included the symbol 'bg-only' in the 'modus-themes-diffs' section of + the manual. Thanks to user "iSeeU" for reporting the omission: + <https://gitlab.com/protesilaos/modus-themes/-/issues/154>. + ++ Expanded the manual's entry on the semantics of the optional heading + scale used by the themes (the variables 'modus-themes-scale-[1-5]'). + The values 1-4 apply to regular headings, with 4 being the largest on + the scale. While 'modus-themes-scale-5' is reserved for special + headers, such as Org '#+title:' or the Org Agenda's structure. Recall + that those variables only come into effect if the boolean variable + 'modus-themes-scale-headings' is set to a non-nil value (it is nil by + default). + ++ Made several changes to the 'modus-themes.org' file in an effort to + improve the accuracy of the generated Texinfo markup. Thanks to Glenn + Morris and Richard Stallman for their valuable feedback in + <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=45143>. + ++ Recorded a note in the manual on the intended colouration of + backgrounds applied by 'mmm-mode'. It explains what the constraints + are from an accessibility standpoint and how users can configure + things locally for more colourful, yet inaccessible, backgrounds. + Thanks to Davor Rotim for the valuable feedback in issue 161: + <https://gitlab.com/protesilaos/modus-themes/-/issues/161>. + ++ Refined the manual's note on prism.el, simplifying the code samples + and clarifying the commentary. + ++ Wrote indices for concepts, variables, functions, which are rendered + in the Info manual. + ++ Elaborated on the possibility---and relative merits---of implementing + a theme-agnostic hook for advanced face configurations, as opposed to + relying on 'modus-themes-after-load-theme-hook'. Thanks to Daniel + Mendler for the valuable feedback in issue 131: + <https://gitlab.com/protesilaos/modus-themes/-/issues/131>. + + +Miscellaneous +------------- + ++ Rewrote the documentation string of the 'deftheme' declaration of + 'modus-operandi' and 'modus-vivendi'. + ++ Provided links to the Info nodes that discuss each of the 'defcustom' + declarations. + ++ Wrote doc strings for every custom face that the themes define. +#+end_src + + +* 1.1.0 +:PROPERTIES: +:CUSTOM_ID: h:bb0e16a9-8a8b-4b1b-9d62-b1715295247b +:END: + +#+begin_src text +Modus themes version 1.1.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2021-01-24 + +This entry records the changes introduced to the project since the +publication of version 1.0.0 (2020-12-05). There have been around 150 +commits in the meantime, qualifying this as one of the largest releases +to date. + +As always, every colour-related modification documented herein conforms +with the overarching accessibility objective of the themes for a minimum +contrast ratio of 7:1 between background and foreground values in their +given combination (conformance with the WCAG AAA standard). + +As the official manual is referenced several times, make sure to store +its URL: <https://protesilaos.com/emacs/modus-themes>. + +If you are coming from older versions, please consult the change log +entry for version 1.0.0. + + +Overview +-------- + ++ We have brought back the options that were present in version 0.13.0 + or earlier which allowed users to override colors for either---or + both---of Modus Operandi and Modus Vivendi. Compared to the old + mechanism, the new one is more robust and should work regardless of + whether users run byte compiled code or not. This is considered and + advanced, "do-it-yourself" pathway to theme customisation. It is + discussed at length in the manual. + ++ The new 'modus-themes-with-colors' macro makes it possible to read + palette variables from the active theme and, thus, pass them to + arbitrary functions or variables. Again, this is part of the advanced + customisations that are covered in the manual. + ++ Several of the existing customisation options provide new stylistic + variants, further expanding their utility. While there are some new + customisations altogether. Combined with the above, we provide the + infrastructure that allows the themes to adapt gracefully to a variety + of circumstances and cover a broad range of demands. + ++ More packages are added to the already comprehensive list of supported + face groups. + ++ Some of the supported faces have benefited from further, albeit + subtle, refinements, demonstrating our commitment to consistency as + well as our attention to detail. + ++ Two reports on such "further refinements" were published on the code + log section of protesilaos.com: <https://protesilaos.com/codelog>. + ++ We have more people contributing to the project (and assigning + copyright to the FSF---as the themes are part of Emacs) and newer + users reporting issues. Also, there is anecdotal evidence from + several sources on an increased interest to make new or existing faces + accessible by default (such as by copying colour combinations from the + themes). + + +New customisation options +------------------------- + ++ The existing 'modus-themes-mode-line' variable now supports three new + borderless styles: 'borderless', 'borderless-3d', 'borderless-moody'. + + - The 'borderless' value uses the same colors as the default (nil + value), but removes the border effect. This is done by making the + box property use the same color as the background, effectively + blending the two and creating some padding. + + - The 'borderless-3d' and 'borderless-moody' approximate the '3d' and + 'moody' options respectively, while removing the borders. However, + to ensure that the inactive modelines remain visible, they apply a + slightly more prominent background to them than what their + counterparts do (same inactive background as with the default). + + The complete list of options: + + 1. nil (default) + 2. 3d + 3. moody + 4. borderless + 5. borderless-3d + 6. borderless-moody + ++ 'modus-themes-lang-checkers' provides several styles for spell + checkers and code linters with regard to how they underline text. The + default (nil) is to use a colour-coded wavy underline, without + changing the foreground of the affected text. Other options include + the ability to set a straight underline and to control the saturation + of the foreground, while one also provides for a change in the + background of the text in question. The valid symbols are as follows + (read the manual for more on the matter): + + 1. nil (default) + 2. straight-underline + 3. subtle-foreground + 4. subtle-foreground-straight-underline + 5. intense-foreground + 6. intense-foreground-straight-underline + 7. colored-background + ++ The 'modus-themes-org-habit' lets users pick between three styles for + the 'org-habit' table: (1) nil (the default), which uses a total of + eight colours, (2) 'simplified' which reduces the effective colours to + four, while applying less saturated hues, and (3) 'traffic-light' + which bring the colour count to three, thus blending the "clear" and + "ready" states for workflows where the distinction between is not + useful. + + Please read the manual for a more detailed description of those + variants. + + Thanks to Gustavo Barros for suggesting the idea, providing user + feedback on stylistic choices, as well as sharing insights on the + workflow that made the 'traffic-light' style possible: + <https://gitlab.com/protesilaos/modus-themes/-/issues/135>. + ++ 'modus-themes-variable-pitch-ui' when set to a non-nil value applies a + proportionately spaced typeface (controlled by the 'variable-pitch' + face) to the User Interface, specifically the mode line, header line, + and tab-{bar,line}. + ++ The existing 'modus-themes-links' variable now has a colourless + stylistic alternative: 'underline-only'. The available styles: + + 1. nil (default) + 2. faint + 3. neutral-underline + 4. faint-neutral-underline + 5. no-underline + 6. underline-only + ++ The existing 'modus-themes-prompts' variable has two new grayscale + styles: 'subtle-gray', 'intense-gray'. Furthermore, their old + 'subtle' and 'intense' values have more informative aliases in the + form of 'subtle-accented' and 'intense-accented'. All available + values: + + 1. nil (default) + 2. subtle-accented ('subtle' remains for backward-compatibility) + 3. intense-accented ('intense' remains for backward-compatibility) + 4. subtle-gray + 5. intense-gray + ++ The existing 'modus-themes-headings' variable now accepts two new + styles: 'no-color', 'no-color-no-bold'. All stylistic variants: + + 1. nil (default fallback option---covers all heading levels) + 2. t (default style for a single heading, when the fallback differs) + 3. no-bold + 4. line + 5. line-no-bold + 6. rainbow + 7. rainbow-line + 8. rainbow-line-no-bold + 9. highlight + 10. highlight-no-bold + 11. rainbow-highlight + 12. rainbow-highlight-no-bold + 13. section + 14. section-no-bold + 15. rainbow-section + 16. rainbow-section-no-bold + 17. no-color + 18. no-color-no-bold + + Please read the manual for instructions on how to apply those + universally or on a per-level basis. + + +Added support for packages +-------------------------- + ++ cfrs (used by treemacs) ++ cperl-mode ++ diredc + ++ display-fill-column-indicator-mode. Thanks to Gustavo Barros for the + feedback: <https://gitlab.com/protesilaos/modus-themes/-/issues/148>. + ++ evil-snipe. Thanks to Peter Wu for the feedback: + <https://gitlab.com/protesilaos/modus-themes/-/issues/139>. + ++ isl (isearch-light). Thanks to Manuel Uberti for the feedback: + <https://gitlab.com/protesilaos/modus-themes/-/issues/144>. + ++ marginalia ++ org-tree-slide ++ recursion-indicator + ++ solaire. Thanks to CsBigDataHub1 for the feedback: + <https://gitlab.com/protesilaos/modus-themes/-/issues/137>. + + +Refinements to already supported faces +-------------------------------------- + ++ Reviewed the 'rainbow-delimiters' faces. Everything is documented in + a separate report (with screenshots). The short version is that we + pay close attention to detail and are willing to go to great lengths + in pursuit of improving the overall user experience: + <https://protesilaos.com/codelog/2020-12-27-modus-themes-review-rainbow-delimiters/>. + ++ Updated the dedicated colours for 'whitespace-mode'. The background + should now be easier to discern. Also removed any remaining + inconsistencies. Thanks to Toon Claes for the feedback: + <https://gitlab.com/protesilaos/modus-themes/-/issues/149>. + ++ Refined the faces of regexp constructs for strings affected by certain + values passed to the 'modus-themes-syntax' option. This is done to + disambiguate the backslashes and grouping delimiters from the rest of + the string. The relevant values for 'modus-themes-syntax' are: + + - green-strings + - yellow-comments-green-strings + - alt-syntax + - alt-syntax-yellow-comments + + The default colour for strings is blue, while regexp faces are yellow + and red, whereas in those variants the strings become green, hence the + need to make regexp faces more distinct (blue and magenta contrast + better with green and also between themselves, thus matching the + alternative aesthetics). + ++ Reviewed dictionary.el faces (which ships with Emacs 28): + + - Made 'dictionary-reference-face' look like all other links. + + - Removed all properties from 'dictionary-word-definition-face': + the default sets a font family, which can create inconsistencies. + + - Converted 'dictionary-word-entry-face' into comment-like text. + ++ Refined and expanded the faces of Consult. + + - Made its grep commands look the same as those of all other grep + tools. + + - Ensured that line number previews, such as for the 'consult-line' + command use their own style of a subtle foreground instead of + inheriting from the 'line-number' face. This is to avoid cases + where previewed numbers and actual line numbers could be conflated + for one another. + + - Removed the foreground pertinent to 'consult-imenu-prefix', as its + bold weight combined with the structure of Imenu indices was deemed + sufficient to differentiate it from actual 'consult-imenu' targets. + ++ Eliminated exaggerations in the use of colour for various 'which-key' + faces. + ++ Removed the needless background from the 'log-view-commit-body' face. + This is a new face that ships with Emacs 28 (its inclusion upstream + was documented in the last changelog entry). + ++ Applied a subtle background to the 'log-view-message' face, in the + interest of improving the usability of its interface, in particular, + to contribute to heightened situational awareness while invoking + 'log-view-toggle-entry-display' in buffers such as those produced by + 'vc-print-root-log'. + ++ Introduced a neutral background for all 'outline-minor-faces' instead + of merely mirroring the style of 'outline-mode' headings. This is + because it can sometimes be hard to tell whether 'outline-minor-mode' + is active, provided certain fairly common configurations in the + 'modus-themes-headings' user option (refer to the manual for all + customisation options). + ++ Tweaked 'diff-mode' headings. + + - Adjusted the values of the dedicated colours for diff headings in + order to amplify their relative contrast. + + - Assigned a bold typographic weight to the 'diff-hunk-header' face so + as to enforce a greater sense of structure. + + - Instructed 'diff-function' to inherit 'modus-theme-diff-heading' in + order to eliminate exaggerations in colouration. + ++ Removed unnecessary underline from 'selectrum-current-candidate'. + Thanks to Daniel Mendler for the feedback: + <https://gitlab.com/protesilaos/modus-themes/-/issues/132>. + ++ Made 'counsel-outline' inherit from the underlying Org faces. Also + corrected the style of 'counsel-outline-default' to use the main + foreground colour. Thanks to Gustavo Barros for the feedback: + <https://gitlab.com/protesilaos/modus-themes/-/issues/134>. + ++ Prevented headings, ultimately governed by the 'modus-themes-headings' + user option, from inheriting the 'default' face as that could lead to + unintended consequences, such as by retaining a background colour when + none was expected. + ++ Refashioned all faces that specified a foreground value of 'fg-alt' to + inherit the 'shadow' face instead ('fg-alt' is the colour that is + used, for example, in code comments by default). This makes it + possible for users to enact change across the theme just by tweaking + 'shadow'. + ++ Fixed 'ruler-mode' text scaling adjustment, to make it cope well with + 'text-scale-adjust' and relevant commands. Also introduced minor + stylistic changes to the remainder of the 'ruler-mode' faces. + ++ Eliminated the potentially problematic form of ':foreground nil' from + the 'org-ellipsis' face. In such cases it is always better to either + specify no foreground whatsoever, or declare an unspecified value. + + +Patches from the community +-------------------------- + +Remember that the themes are part of Emacs and, thus, contributions that +exceed a cumulative total of ~15 lines require the assignment of +copyright to the Free Software Foundation. Please consult the themes' +manual on the matter. + ++ Nicolas De Jaeghere added support for 'exwm-floating-border-color': + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/15>. + ++ Anders Johansson added support for 'helm-fd-finish': + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/16>. + ++ Carlo Zancanaro fixed misquoting of 'tuareg-font-lock-multistage-face': + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/17>. + ++ Xinglu Chen expanded Notmuch support to all its remaining faces: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/18>. + ++ Kostadin Ninev added support for Dired+: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/19>. + ++ Nicolas De Jaeghere expanded the supported items of 'pdf-faces'. Also + added an entry to the manual pertaining to link hints and the + requisite setup: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/20>. + ++ Nicolas De Jaeghere wrote the new 'modus-themes-with-colors' macro, + which is documented at length in the manual: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/21>. + ++ Nicolas De Jaeghere set up the infrastructure that grants users the + ability to override palette colors; an option that was removed in the + transition from version 0.13.0 to 1.0.0. The relevant variables are + 'modus-themes-colors-operandi', 'modus-themes-colors-vivendi' (again, + consult the manual): + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/23>. + ++ Nicolas De Jaeghere deleted the 'modus-themes-core.el' file and merged + its contents into the main 'modus-themes.el' library: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/24> and + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/25>. + ++ Nicolas De Jaeghere made the 'compilation-info' face consistent with + other compilation faces in terms of their optional bold weight: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/26>. + +Any remaining faults that may exist, despite our best intentions to +remove them, are those of the maintainer and will be addressed as soon +as they are identified. + +FSF copyright status: + +| Full name | Copyright | +|---------------------+--------------| +| Anders Johansson | covered | +| Carlo Zancanaro | not required | +| Kostadin Ninev | covered | +| Nicolas De Jaeghere | covered | +| Xinglu Chen | not required | + + +Theme-related contributions to the wider community +-------------------------------------------------- + ++ Helped address an incomplete colour value in 'org-transclusion-block': + <https://github.com/nobiot/org-transclusion/issues/41>. + ++ Contributed to the formation of the zebra striping of 'embark': + <https://github.com/oantolin/embark/commit/bb4ae2a666ab1f4a307edd71f77bcbb90fb25cef>. + ++ Reviewed the faces of 'goggles': + <https://github.com/minad/goggles/commit/d6e584a2c9487d3df4aee818c43485e437cb87ef>. + ++ Helped raise awareness about refactoring 'org-tree-slide-header-overlay-face': + <https://github.com/takaxp/org-tree-slide/issues/38>. + ++ Reported an issue for Moody that would affect the subset of Emacs 28 + users who enable the new 'mode-line-compact' option: + <https://github.com/tarsius/moody/issues/28>. + ++ Did the same for Keycast: <https://github.com/tarsius/keycast/issues/13>. + ++ Defined the new 'perl-non-scalar-variable' in upstream Emacs: + <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=45840>. + + +Miscellaneous +------------- + ++ Created a new palette subset for "graph" colours, as none of the + existing paradigms would suffice for cases where faithfulness to + colour huenesss is important. Those are currently used by + 'modus-themes-org-habit'. + ++ Ensured that theme functions which need to produce an error message do + so by calling 'error' instead of 'user-error'. + ++ Added a 'modus-themes-load-themes' function that users can add to + their init files. + ++ Expanded the project's git repo README file with a sample + 'use-package' configuration. + ++ The previous two points followed from an inquiry into the subtleties + between 'enable-theme' and 'load-theme'. Those are now documented at + length in the manual. + ++ Added screenshots to the web page that holds the official manual. + Thanks to Damien Cassou for the feedback: + <https://gitlab.com/protesilaos/modus-themes/-/issues/147>. + ++ Swapped the values of 'cyan-faint' and 'cyan-alt-faint' for Modus + Vivendi. + ++ Tweaked 'font-lock-doc-face' and 'font-lock-type-face' variations when + "faint syntax" is in effect: (setq modus-themes-syntax 'faint). + ++ Refined 'font-lock-doc-face' for when modus-themes-syntax is given a + value of either 'yellow-comments-green-strings' or 'green-strings'. + The changes are minor when treated in isolation, though they have + helped improve the overall consistency of the end result: the gestalt. + ++ Reviewed select "faint" colours for both Modus Operandi and Modus + Vivendi. The technicalities are discussed in a complete report: + <https://protesilaos.com/codelog/2021-01-11-modus-themes-review-select-faint-colours/>. + ++ Ensured that (setq modus-themes-syntax 'alt-syntax) and its "yellow + comments" variant are more truthful to their intended style, by + eliminating any exaggerations in the use of colour. + ++ Adjusted the saturation of the green-alt value of Modus Vivendi. + ++ Updated the manual to reflect all of the aforementioned. + +Thanks once again to everyone who contributed patches or reported an +issue. This has been yet another period of intense work; work which +helps solidify the Modus themes as (i) uncompromisingly accessible in +accordance with the highest legibility standard, (ii) highly +customisable in true Emacs fashion, (iii) thoroughly comprehensive in +terms of face coverage, and (iv) meticulously designed throughout. +#+end_src + +* 1.0.0 +:PROPERTIES: +:CUSTOM_ID: h:94b5915e-1085-4859-ac9f-daf91e007741 +:END: + +#+begin_src text +Modus themes version 1.0.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2020-12-05 + +This entry documents the changes since version 0.13.0 (2020-10-08). +They constitute a major release with backward-incompatible additions +which are described below. + +As always, every colour-related modification documented herein conforms +with the overarching accessibility objective of the themes for a minimum +contrast ratio of 7:1 between background and foreground values in their +given combination (conformance with the WCAG AAA standard). + +Expect to find examples of basic and advanced customisations in the +comprehensive Info manual bundled with the themes, which is also +available at: <https://protesilaos.com/emacs/modus-themes>. + + +Overview of major changes +========================= + +0. The option that was present in earlier releases to override the + colour palette has been removed. It cannot work with byte + compilation. We must not compromise on performance, especially in + light of the fairly high line count of the themes (broad face + coverage combined with a multitude of customisation options). + +1. The code base has been refactored. The two themes, Modus Operandi + (light) and Modus Vivendi (dark), derive from the same source. + +2. The refactoring makes it possible to distribute the two themes as + part of a single package. You can find 'modus-themes' on MELPA, with + other archives and core Emacs following suit soon thereafter (the + Modus themes are built into Emacs since their version 0.12.0). + +3. The 'modus-operandi-theme' and 'modus-vivendi-theme' packages in + MELPA and GNU ELPA are obsolete. MELPA has already deleted them and + now only provides 'modus-themes', while GNU ELPA shall do so soon + enough. + + + Package providers of GNU/Linux distros, or other archives, are + encouraged to update their sources so that they only deliver a + single package that covers both themes. + +4. To avoid surprises, the refactored code is in the 'main' branch which + becomes the default henceforth. The 'master' branch, from where all + prior releases were built, is thus deprecated. Existing installs of + 'modus-operandi-theme' and/or 'modus-vivendi-theme' must manually + switch to the new package sources, which offer a certain guarantee + that they are informed of the breaking changes documented herein. + + + Users of 'straight.el' must make sure that they pull from the + 'main' branch. This may also be the case for other such tools, + though I have not had the time to test them all. + +5. The refactoring introduces a unified customisation framework. Now + all user-facing variables are named 'modus-themes-*' instead of + 'modus-operandi-*' and 'modus-vivendi-*'. Users of both items can + thus cut down on duplicate code or inelegant workarounds on their + end. Example: + + modus-operandi-bold-constructs + | | | | | | | ====> modus-themes-bold-constructs + modus-vivendi-bold-constructs + +6. The themes now provide common user-facing functions. + + + 'modus-themes-load-operandi' and 'modus-themes-load-vivendi' can be + used in Lisp to load the theme they name, while disabling their + counterpart and running 'modus-themes-after-load-theme-hook'. The + hook can be used to override or further customise faces (examples + are furnished in the manual). + + + 'modus-themes-toggle' interactively switches between Modus Operandi + and Modus Vivendi or opens a minibuffer prompt to select between + the two if none of them is active. It ultimately calls the + aforementioned functions to load the themes, so it also triggers + the hook. Bind this command to a key of your convenience (the + author uses F5). + + + 'modus-themes-color' returns the colour value of a symbol in the + alists that hold the themes' palettes. The alists are + 'modus-themes-colors-operandi' and 'modus-themes-colors-vivendi'. + 'modus-themes-color' always operates on the active theme, making it + suitable for post-theme-load customisations (via the hook we + covered earlier). Its usage is documented in the manual and is + meant to be employed by those who are prepared to assume + responsibility for face-related changes they introduce on their + setup. + + + 'modus-themes-color-alts' occupies the same niche as the one right + above, with the exception that it takes two arguments. The first + is the alist key to be used by 'modus-operandi' and the second is + for 'modus-vivendi'. + + + 'modus-themes-wcag-formula' implements the WCAG formula to measure + a colour value's relative luminance. While 'modus-themes-contrast' + applies the formula to derive the contrast ratio between two colour + values in hexadecimal RGB notation. This can be used to verify the + accessibility of colour combinations provided by the themes or new + ones defined at the user level (the Modus themes conform with the + WCAG AAA standard which means that this kind of contrast is 7:1 or + higher for all applicable background+foreground combinations). + + +Customisation options +===================== + +This is the complete list with all the customisation options: + + modus-themes-slanted-constructs (boolean) + modus-themes-bold-constructs (boolean) + modus-themes-variable-pitch-headings (boolean) + modus-themes-no-mixed-fonts (boolean) + modus-themes-headings (alist) + modus-themes-scale-headings (boolean) + modus-themes-fringes (choice) + modus-themes-org-blocks (choice) + modus-themes-prompts (choice) + modus-themes-mode-line (choice) + modus-themes-diffs (choice) + modus-themes-syntax (choice) + modus-themes-intense-hl-line (boolean) + modus-themes-paren-match (choice) + modus-themes-region (choice) + modus-themes-links (choice) + modus-themes-completions (choice) + +Plus those which are contingent on 'modus-themes-scale-headings': + + modus-themes-scale-1 + modus-themes-scale-2 + modus-themes-scale-3 + modus-themes-scale-4 + modus-themes-scale-5 + +Consult the manual for each of them and please verify that none of the +older options remains in your init file. + + +Customisation options that did not exist in earlier versions +------------------------------------------------------------ + +New entries and their possible values: + +1. modus-themes-syntax + + ,* nil (default) + ,* faint + ,* yellow-comments + ,* green-strings + ,* yellow-comments-green-strings + ,* alt-syntax + ,* alt-syntax-yellow-comments + + (supersedes options for "faint syntax" and "comments") + +2. modus-themes-links + + ,* nil (default) + ,* faint + ,* neutral-underline + ,* faint-neutral-underline + ,* no-underline + + (supersedes options for "no underlines") + +3. modus-themes-paren-match + + ,* nil (default) + ,* intense + ,* subtle-bold + ,* intense-bold + + (supersedes options for "intense paren match") + +4. modus-themes-region + + ,* nil (default) + ,* no-extend + ,* bg-only + ,* bg-only-no-extend + +Furthermore, the 'modus-themes-diff' has a new option to choose from: +the symbol 'bg-only'. It applies colour-coded backgrounds but does not +override any syntax highlighting that may be present. This makes it +suitable for use with a non-nil value for diff-font-lock-syntax (which +is the default for diff-mode buffers in Emacs 27 or higher). + + +Support for new faces or face groups +==================================== + ++ consult ++ macrostep ++ make-mode ++ pdf-tools ++ popup ++ shr ++ sieve-mode + +(remember that the list of supported packages is already comprehensive) + +Thanks to: + ++ Adam Spiers for bringing 'macrostep' to my attention. + ++ Madhavan Krishnan for submitting the code for pdf-tools: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/14>. + ++ Manuel Uberti for reporting the issue with popup.el: + <https://gitlab.com/protesilaos/modus-themes/-/issues/107>. + ++ Again thanks to Manuel for consult: + <https://gitlab.com/protesilaos/modus-themes/-/issues/123>. And to + Daniel Mendler, its developer, for communicating with us on the status + of the project. + ++ Togan Muftuoglu for reporting the issue with sieve-mode: + <https://gitlab.com/protesilaos/modus-themes/-/issues/121>. + + +Refinements to existing faces +============================= + ++ The diary and holiday marks in 'M-x calendar' are displayed using a + slightly tinted background in order to improve their contrast. + Holidays are also rendered in a bold font. Thanks to Nicolas De + Jaeghere for reporting the issue and following it up with valuable + feedback: <https://gitlab.com/protesilaos/modus-themes/-/issues/127>. + ++ Code blocks in 'markdown-mode' now have a subtle background that + extends to the edge of the window. Thanks to Roman Rudakov for the + suggestion and Hörmetjan Yiltiz for further testing: + <https://gitlab.com/protesilaos/modus-themes/-/issues/115>. + ++ Inline code in 'markdown-mode' has a subtle background that covers the + length of the construct. Refer to issue #115 as above. + ++ Ivy's main pattern-matching faces are slightly adjusted to work more + effectively when users opt for "modus-themes-completions 'moderate" or + "modus-themes-completions 'opinionated". + ++ Swiper's 'swiper-isearch' command defaults to a more colourful + presentation that clearly disambiguates matching pattern groups + between themselves as well as their own active and inactive states. + Thanks to John Haman for reporting the problem: + <https://gitlab.com/protesilaos/modus-themes/-/issues/125>. + ++ Swiper's remaining faces are tweaked to better convey the intent of + this tool. + ++ The border of 'ivy-posframe' is more noticeable. Thanks to Pete + Kazmier: <https://gitlab.com/protesilaos/modus-themes/-/issues/126>. + ++ The 'fringe' face no longer returns a nil background, which allows + 'dap-ui-controls-mode' to display things properly. Thanks to Simon + Pugnet: <https://gitlab.com/protesilaos/modus-themes/-/issues/106>. + ++ Tags and priority cookies in Org mode no longer have a box property. + This is because of changes in upstream Org that we helped solve and + that are covered in the previous CHANGELOG entry (in short: Org + heading constructs inherit the underlying heading's properties that + are not part of their own specs, while they retain those that are + explicitly defined for them---adaptive headings). Properly solves the + following issues: + + ,* <https://gitlab.com/protesilaos/modus-themes/-/issues/104>. Thanks + to user "bepolymathe". + + ,* <https://gitlab.com/protesilaos/modus-themes/-/issues/95>. Thanks + to Roman Rudakov. + ++ The faces of 'M-x re-builder' are less intrusive. + ++ All the following now inherit from basic font-lock faces and thus + benefit from options such as 'modus-themes-syntax': + + ,* geiser + ,* nxml-mode + ,* tuareg + ,* web-mode + ,* xah-elisp-mode + ++ Diff headers have a subtle grey background that extends to the edge of + the window. + ++ The faces of log-view and change-log use colour combinations that + better differentiate the various objects on display. + ++ 'font-lock-type-face' uses a cyan hue instead of magenta. + ++ 'magit-header-line-key' uses a blue foreground colour instead of red. + ++ Doc strings in code syntax are rendered in a new dedicated colour. + The change is fairly subtle and should practically go unnoticed. + ++ 'org-date' now respects the 'modus-themes-no-mixed-fonts' option. + Thanks to user "fleimgruber" for reporting the issue: + <https://gitlab.com/protesilaos/modus-themes/-/issues/124>. + ++ 'org-property-value' uses a slightly different shade of cyan. + ++ 'dim-autoload' will always look like a regular comment. + ++ The 'italic' face is inhereted by all relevant faces instead of + hard-wiring a slant property. This offers the potential advantage of + specifying a distinct family (or other properties) for constructs that + are meant to be rendered in italics (the manual has an example in its + DIY sections for this scenario though it uses the 'bold' face---just + apply the same idea to the 'italic' face). + ++ 'dictionary-reference-face' inherits from 'button' (as with all + links). + ++ Several comment-related faces beyond the basic ones work with + 'modus-themes-syntax' when that has an effect on the colour of + comments. The faces are: + + ,* git-commit-comment-file + ,* git-commit-comment-heading + ,* git-rebase-comment-hash + ,* git-rebase-comment-heading + ++ 'transient-value' is more noticeable and fits better in its context. + ++ All remaining Org metadata-related faces are refined for consistency + between them in an attempt to make them unobtrusive. More subtle + colouration is applied. Affected faces: + + ,* org-drawer + ,* org-property-value + ,* org-special-keyword + + +Theme-related contributions to the wider community +================================================== + ++ Defined the 'log-view-commit-body' for Emacs 28.1: + <https://lists.gnu.org/archive/html/bug-gnu-emacs/2020-11/msg00303.html> + and + <https://lists.gnu.org/archive/html/bug-gnu-emacs/2020-11/msg02196.html>. + ++ Specified the version of the 'diff-error' face for Emacs 28.1: + <https://lists.gnu.org/archive/html/bug-gnu-emacs/2020-11/msg01328.html>. + ++ Added the 'org-dispatcher-highlight' face to upstream Org: + <https://lists.gnu.org/archive/html/emacs-orgmode/2020-10/msg00158.html>. + + ,* Report with screenshots: + <https://protesilaos.com/codelog/2020-10-24-org-export-dispatcher-face/>. + ++ Helped fix face of Flymake's unknown backend in inactive modelines: + <https://lists.gnu.org/archive/html/bug-gnu-emacs/2020-11/msg01119.html>. + ++ Solved bug#44198 about a user not knowning the themes are in Emacs: + <https://lists.gnu.org/archive/html/bug-gnu-emacs/2020-10/msg02001.html>. + + +Miscellaneous +============= + ++ The new default 'main' branch of the Modus themes' git repo is an idea + that was presented by user "Emacs Contrib" in issue 112: + <https://gitlab.com/protesilaos/modus-themes/-/issues/112>. Raising + awareness about the negative impact of potentially, tacitly, or + explicitly offensive language is a goal worth pursuing. Plus "main" + is a more appropriate name for the primary branch of a project and we + do not lose anything by introducing this change as part of version + 1.0.0, which anyhow requires manual interventions in user + configurations. + ++ Thanks to Manuel Uberti, Jeremy Friesen, and Gitlab user "Eugene" for + their feedback during the process that eventually led to the + development of the 'modus-themes-syntax' customisation option: + <https://gitlab.com/protesilaos/modus-themes/-/issues/105>. + ++ Thanks to André Alexandre Gomes for the feedback in issue 111, which + led to the simplification of the manual's references to Guix: + <https://gitlab.com/protesilaos/modus-themes/-/issues/111>. + ++ Thanks to Nicolas De Jaeghere for noting that BBDB is indirectly + supported: <https://gitlab.com/protesilaos/modus-themes/-/issues/128>. + +Between the refactoring of the code base and all other changes, this has +been yet another period of hard work to deliver on the promise of themes +that are (i) highly accessible and (ii) comprehensive in both their face +coverage and customisation options, while always conforming with the +highest accessibility standard for legible text. + +Special thanks to the MELPA maintainers for all their contributions. +MELPA is an integral part of the wider Emacs community. Thanks, in +particular, to Chris Rayner who has reviewed all my pull requests +hitherto, and to Jonas Bernoulli for checking the latest one (and its +concomitant issue) that introduced the new 'modus-themes' package. + +Thank you, the reader, for your attention and for understanding the +longer term benefits of the refactoring, despite the short term friction +it may have introduced. +#+end_src + +* 0.13.0 +:PROPERTIES: +:CUSTOM_ID: h:b529ec46-2a9f-4844-9760-4708d2ca575b +:END: + +#+begin_src text +Modus Operandi and Modus Vivendi version 0.13.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2020-10-08 + +This entry documents the changes since version 0.12.0 (2020-08-26). +There have been around 150 commits in the meantime, making this the +largest release to date (though sheer volume should not be conflated +with quality, of which there is plenty). + +As always, everything described herein conforms with the overarching +accessibility objective of the themes for a minimum contrast ratio of +7:1 between background and foreground values in their given combinations +(conformance with the WCAG AAA standard). + +Overview +======== + +1. There is a new Info manual that documents the customisation options + as well as every other piece of information pertinent to the themes. + You will find it in the Info pages inside of Emacs. Or browse it + online: <https://protesilaos.com/emacs/modus-themes>. + +2. New customisation options grant users more power to further adapt the + active theme to their preferences. + +3. Extended coverage for even more faces and face groups, adding to the + already comprehensive list of directly supported ones. + +4. Lots of tweaks to improve the use of colour and avoid exaggerations + (well, "exaggerations" is relative, since the prior state was already + carefully designed). + +5. A new page hosts all pictures that demo the themes across a wide + range of scenaria: <https://protesilaos.com/emacs/modus-themes-pictures>. + +6. Similarly, the change log also has its own dedicated web page: + <https://protesilaos.com/emacs/modus-themes-changelog>. + + +New customisation options +========================= + +Note that all customisation options are documented at length in the new +Info manual. What is offered here is not necessarily exhaustive. + + +Diff styles +----------- + +Symbol names ("choice" type): + ++ modus-operandi-theme-diffs ++ modus-vivendi-theme-diffs + +Possible values: + +1. nil (default) +2. desaturated +2. fg-only + +DEPRECATED ("boolean" type): + ++ modus-operandi-theme-subtle-diffs ++ modus-vivendi-theme-subtle-diffs + +This option supersedes older ones while retaining their functionality. + +The default remains unaltered, meaning that the diffs will use fairly +prominent colour-coded combinations for the various elements (e.g. green +text on an unambiguously green backdrop). + +A 'desatured' value will tone down the default aesthetic, giving a less +vibrant feel. + +While 'fg-only' removes almost all coloured backgrounds, opting to apply +colour only to the relevant text (this was the case with the +now-deprecated options). There are some exceptions, like word-wise or +"refined" diffs, which still use coloured backgrounds to convey their +meaning. + + +Modeline styles +--------------- + +Symbol names ("choice" type): + ++ modus-operandi-theme-mode-line ++ modus-vivendi-theme-mode-line + +Possible values: + +1. nil (default) +2. 3d +3. moody + +DEPRECATED ("boolean" type): + ++ modus-operandi-theme-3d-modeline ++ modus-vivendi-theme-3d-modeline + +The default modeline continues to be a two-dimensional rectangle with a +border around it. Active and inactive modelines use different colour +combinations for their main background and foreground. + +Option '3d' produces an effect similar to what you get in a generic +Emacs session, where the active modeline has a pseudo three-dimensional +effect applied to it. This option offers the same functionality as that +of the deprecated variables. + +Option 'moody' is designed specifically for use with the Moody library, +though it can also be used without it. Instead of implementing a box +effect, it applies an overline and underline instead, while also toning +down the inactive modeline. + +Thanks to Nicolas De Jaeghere for the feedback and code samples in issue +80: <https://gitlab.com/protesilaos/modus-themes/-/issues/80> + + +Headline styles +--------------- + +Symbol names ("alist" type): + ++ modus-operandi-theme-headings ++ modus-vivendi-theme-headings + +DEPRECATED ("boolean" type): + ++ modus-operandi-theme-rainbow-headings ++ modus-operandi-theme-section-headings ++ modus-vivendi-theme-rainbow-headings ++ modus-vivendi-theme-section-headings + +Possible values, which can be specified for each heading level (examples +further below): + +0. nil (default fallback option---covers all heading levels) +1. t (default style for a single heading, when the fallback differs) +2. no-bold +3. line +4. line-no-bold +5. rainbow +6. rainbow-line +7. rainbow-line-no-bold +8. highlight +9. highlight-no-bold +10. rainbow-highlight +11. rainbow-highlight-no-bold +12. section +13. section-no-bold +14. rainbow-section +15. rainbow-section-no-bold + +This supersedes and greatly expands upon what the deprecated variables +once offered. It is now possible to (i) benefit from more stylistic +choices, and (ii) apply them on a per-level basis. + +As always, the defaults remain in tact: headings are just rendered in a +bold weight and their colours are not too saturated to offer a plain +text impression that relies on typography to convey its meaning. + +The info manual explains the details. A few examples: + + ;; Per-level styles (t means everything else) + (setq modus-operandi-theme-headings + '((1 . highlight) + (2 . line) + (t . rainbow-line-no-bold))) + + ;; Uniform style for all levels + (setq modus-operandi-theme-headings + '((t . rainbow-line-no-bold))) + + ;; Default style for level 1, while others differ + (setq modus-operandi-theme-headings + '((1 . t) + (2 . line) + (t . rainbow-line-no-bold))) + +Thanks to Adam Spiers for the feedback in issue 81: +<https://gitlab.com/protesilaos/modus-themes/-/issues/81>. Also thanks +to Nicolas De Jaeghere for helping refine relevant stylistic choices: +<https://gitlab.com/protesilaos/modus-themes/-/issues/90>. + + +No link underlines +------------------ + +Symbol names ("boolean" type): + ++ modus-operandi-theme-no-link-underline ++ modus-vivendi-theme-no-link-underline + +Possible values: + +1. nil (default) +2. t + +By default, the themes apply an underline effect to links, symbolic +links, and buttons. Users can now disable this style by setting the new +option to 't'. + +Thanks to Utkarsh Singh for the feedback in issue 94: +<https://gitlab.com/protesilaos/modus-themes/-/issues/94> + + +No mixed fonts +-------------- + +Symbol names ("boolean" type): + ++ modus-operandi-theme-no-mixed-fonts ++ modus-vivendi-theme-no-mixed-fonts + +Possible values: + +1. nil (default) +2. t + +By default, the themes configure some spacing-sensitive faces, such as +Org tables and code blocks, to always inherit from the 'fixed-pitch' +face (documented in the manual). This is to ensure that those +constructs remain monospaced when users opt for something like the +built-in 'M-x variable-pitch-mode'. Otherwise the layout would break. + +The obvious downside with this theme design is that users need to +explicitly configure the font family of 'fixed-pitch' in order to apply +their desired typeface (how to do this is also covered in the manual). +That may be something they do not want to do. Hence this option to +disable any kind of font mixing done by the active theme. Set it to +'t'. + + +Support for new faces or face groups +==================================== + ++ awesome-tray ++ binder ++ cperl-mode ++ eldoc-highlight-function-argument ++ erc escaped colour sequences ++ eshell-syntax-highlighting ++ flycheck-color-mode-line ++ isearch regexp groups (Emacs version >= 28) ++ mpdel ++ objed ++ org 9.4 new faces: 'org-headline-todo' and 'org-table-header' ++ racket-mode ++ typescript-mode + +Thanks to: + ++ Damien Cassou for reporting the issue with mpdel: + <https://gitlab.com/protesilaos/modus-themes/-/issues/99> + ++ Dario Gjorgjevski for reporting the issue with erc: + <https://gitlab.com/protesilaos/modus-themes/-/issues/92> + ++ Markus Beppler for contributing the patch for cperl-mode: + <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/11> + ++ User "Moesasji" for reporting the issue with objed: + <https://gitlab.com/protesilaos/modus-themes/-/issues/79> + + +Refinements to existing faces +============================= + ++ calfw applies colours and styles in a way that makes it consistent + with the rest of the themes' metaphors. + ++ diredfl makes more considerate use of colour. We still apply colour + everywhere (the whole point of this package) but make sure to avoid + exaggerations. + ++ doom-modeline-battery-error face fits better with the rest of the + design. + ++ elfeed search buffers use less intense colours, while still keeping + all elements fairly distinct. The intent is to avoid a "rainbow + effect" in such a dense interface. + ++ elfeed read and unread items are more distinct. + ++ git commit and vc log edit messages benefit from refined colour + combinations for their various constructs. The commit's summary is + now rendered in a bold weight, to better convey the idea that this is + a quasi heading element. + ++ gnus heading colours are more consistent. All information remains + clearly distinct, but we now avoid using colours that are on opposite + sides of the colour spectrum. Basically to keep things distinct + without going over the top. + ++ gnus read and unread items are easier to tell apart. Thanks to user + "Nick" for reporting the issue: + <https://gitlab.com/protesilaos/modus-themes/-/issues/97>. + ++ help-argument-name has a distinct foreground colour, so that it is + easier to spot it in "*Help*" buffers. Its slant is also controlled + by the active theme's customisation option for slanted constructs (nil + by default---check the manual). + ++ helpful-heading now is consistent with other heading styles. Thanks + to Nicolas De Jaeghere for reporting the issue: + <https://gitlab.com/protesilaos/modus-themes/-/issues/90>. + ++ icomplete, ido, orderless are all tweaked to work better under various + circumstances. + ++ info-menu-star uses a red colour to make it easier to select a menu + entry by estimating its number. This face applies to every third + element and is a nice little extra to have. + ++ info quoted strings are configured to always render in 'fixed-pitch', + in line with the themes' design for mixed fonts (remember to check the + relevant customisation option). + ++ line numbers work properly with 'text-scale-adjust'. Thanks to user + "jixiuf" for reporting the issue: + <https://gitlab.com/protesilaos/modus-themes/-/issues/98>. + ++ line-number-current-line no longer applies a bold weight to its text. + This is to avoid a certain "jump effect" while moving between lines, + where the affected numbers grow and shrink in weight as the line + changes (once you see it, you will know what I mean). + ++ line-number-major-tick and line-number-minor-tick do use a bold weight + because they are fixed on the scale. Their colours are also improved + to better complement their intended role (these faces are for Emacs 27 + or higher). + ++ magit-diff-file-heading-selection, magit-diff-hunk-heading-selection + use more appropriate colour combinations. + ++ markdown blockquotes and org quote blocks use a different foreground, + which is colder than the previous one. Just to make sure that they + are not mistaken for inline code. + ++ message headers use less exaggerated colour combinations. The + differences are fairly minor. + ++ message-mml no longer uses a green foreground, as that could + potentially cause confusion with quoted text in some cases. A unique, + albeit less saturated, foreground is used instead. + ++ message-separator uses a more neutral colour combination, while + retaining its overall uniqueness within its context (i.e. mail + composition). + ++ modeline colours are refined to improve the contrast between active + and inactive states. + ++ mu4e-replied-face has a new colour that accounts for colour distance + relative to its context. Thanks to Shreyas Ragavan for reporting the + issue: <https://gitlab.com/protesilaos/modus-themes/-/issues/69>. + ++ org agenda date and structure no longer behave like headings in other + Org buffers. Instead, they have their own styles to better perform + their intended function and to avoid exaggerations. + ++ org agenda dimmed to-do items (which have blocked sub-items) are no + longer assigned a subtle grey background colour. They are instead + rendered with a bold weight and a subtle grey foreground to minimise + distractions. Thanks to Roman Rudakov for reporting this in issue + 101: <https://gitlab.com/protesilaos/modus-themes/-/issues/101>. + ++ org agenda clocked items are configured to extend their background to + the edge of the window. Otherwise they are cut off at the last text + character, which creates inconsistencies while using tags: a tag is + placed to the right so the background extends further than without + them. Based again on the feedback of Roman Rudakov in issue 101: + <https://gitlab.com/protesilaos/modus-themes/-/issues/101>. + ++ org agenda current time no longer uses a background. A bold weight + and a blue foreground are applied instead. The intent is to keep + things clean. This is also covered by Roman Rudakov's feedback in + issue 101: <https://gitlab.com/protesilaos/modus-themes/-/issues/101>. + ++ org-checkbox-statistics-done, org-checkbox-statistics-todo inherit + from org-done and org-todo respectively, instead of defining their own + properties. + ++ org drawers and their data now use 'fixed-pitch' in the interest of + consistency with other metadata-like faces. Thanks (yet again!) to + Nicolas De Jaeghere for reporting the issue: + <https://gitlab.com/protesilaos/modus-themes/-/issues/91>. + ++ org-footnote underlines will now always use the same colour, instead + of applying the one of other coloured constructs (e.g. when the + footnote is inline and part of the text is rendered as verbatim). + ++ org-meta-line is less prominent and, thus, more consistent with other + metadata-related constructs. + ++ org-roam faces are updated to match the current state of the upstream + project. The main colour of org-roam links is now different than that + of standard links in an attempt to differentiate between the two (due + to their unique semantics). If this is not desired, you can evaluate + the following: + + (setq org-roam-link-use-custom-faces nil) + ++ org-todo, org-done, as well as relevant faces such as priorities and + statistics are reviewed to work better with all heading combinations. + Though please read the next section about "adaptive headings", as such + workarounds will no longer be necessary for future stable releases of + Org. + ++ selectrum uses different styles than before to account for its unique + property of overlaying matching characters on top of the current + line's background. We want to avoid scenaria where matches are + difficult to discern and the current line is not clear. + ++ vc modeline states benefit from improved colour choices. Just minor + adjustments to account for the review of the base modeline colours. + ++ vterm base colours now are variants of gray to ensure that some tools, + such as zsh suggestions work properly. Thanks to user "jixiuf" for + reporting this issue and suggesting a possible solution: + <https://gitlab.com/protesilaos/modus-themes/-/issues/93>. + +Contributions to the wider community +==================================== + +Sometimes the themes reveal bugs in other packages. It is of paramount +importance that we report those to the upstream developers, try to help +them reproduce the issue, and, where possible, support them in tracing +the problem's root cause. + +Four such cases during this release: + +1. Adaptive Org headings. Solved upstream and documented on my website: + <https://protesilaos.com/codelog/2020-09-24-org-headings-adapt/>. + Reported and discussed on the themes' issue tracker: + <https://gitlab.com/protesilaos/modus-themes/-/issues/37>. + +2. Alignment of Org tags with proportional fonts. Ongoing thread: + <https://lists.gnu.org/archive/html/emacs-orgmode/2020-09/msg00415.html>. + Reported and discussed on the themes' issue tracker: + <https://gitlab.com/protesilaos/modus-themes/-/issues/85>. + +3. Org priority cookie has extra space. Ongoing thread: + <https://lists.gnu.org/archive/html/emacs-orgmode/2020-09/msg00696.html>. + Reported and discussed on the themes' issue tracker, with feedback + from Roman Rudakov: + <https://gitlab.com/protesilaos/modus-themes/-/issues/95>. + +4. Company overlay pop-up misaligns items. Reported upstream and + acknowledged as a known issue that occurs in certain cases: + <https://github.com/company-mode/company-mode/issues/1010>. + Discussion on the themes' issue tracker, with feedback from Iris + Garcia: <https://gitlab.com/protesilaos/modus-themes/-/issues/96>. + + +Miscellaneous +============= + ++ Belatedly (by about 2 weeks) pushed tag for version 0.12.0. Thanks to + Alex Griffin for bringing this to my attention: + <https://gitlab.com/protesilaos/modus-themes/-/issues/89> + ++ Fixed a bug with how some older customisation options were declared as + obsolete. Thanks to Tassilo Horn for noticing and reporting the + problem: <https://gitlab.com/protesilaos/modus-themes/-/issues/88>. + ++ Fixed a misplaced optional prefix argument in the manual for how to + switch themes using a custom function. Thanks to Manuel Uberti for + catching this omission of mine and reporting it: + <https://gitlab.com/protesilaos/modus-themes/-/issues/84>. + ++ Silenced the Elisp package linter for a spurious error on a single + eldoc face. Thanks to Steve Purcell for the guidance: + <https://github.com/purcell/package-lint/issues/187>. + ++ Defined two new dedicated background colours for exceptional cases. + These are intended for internal use in very special circumstances. + ++ Reword GuixSD to "Guix System" in the list of package formats + currently available. + ++ Reviewed the main blue colours for both themes. While the changes are + practically impossible to discern upon first sight, the process was + far from straightforward. A complete report documents the minutia: + <https://protesilaos.com/codelog/2020-09-14-modus-themes-review-blues/>. + ++ Reviewed the "active" palette subset, typically used in the modelines. + No report was necessary for those, as the changes were fairly simple. + ++ Reviewed the "intense" background colour that comes into effect when + users opt for the customisation option for intense paren-match styles + (check the manual). Both the hue and the saturation have been changed + to better conform with the intended function of this particular entry. + ++ Reviewed the fringe-specific accented backgrounds. Commit 7316e3320 + contains tables that compare the relative luminance of old and new + values. + ++ Improved the advice for setting fonts using 'set-face-attribute'. The + information is in the manual and is also available as a blog entry: + <https://protesilaos.com/codelog/2020-09-05-emacs-note-mixed-font-heights/>. + ++ Rewrote an expression as "(or x y)" instead of "(if x x y)" in one + place. Just goes to show that tweaking the code is also part of the + deal. + ++ Abstracted and simplified heading level properties by using bespoke + theme faces. Makes it easier to keep things consistent across the + various face groups. + ++ Same principle as above for diff-related styles. + ++ Users who prefer to do things their own way or who just wish to + contribute code to the Modus themes may wish to read my "Notes for + aspiring Emacs theme developers": + <https://protesilaos.com/codelog/2020-08-28-notes-emacs-theme-devs/>. + +This has been yet another period of intense work: reviewing faces and +applying colours is never easy, adding new customisation options is +always tricky, and documenting everything takes a lot of time (unless +you do all of those on a whimsy, which hopefully is not the case here). + +Thanks again to everyone who helped improve the themes! +#+end_src + +* 0.12.0 +:PROPERTIES: +:CUSTOM_ID: h:9d9394c1-84b6-4c23-8936-fe4f2f43301d +:END: + +#+begin_src text +Modus Operandi and Modus Vivendi version 0.12.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2020-08-26 + +This entry documents the set of changes since version 0.11.0 +(2020-07-31). There have been around 70 commits in the meatime, though +the sheer number may obfuscate the fact that a lot of work has gone into +this release. + +As always, every change described here conforms with the accessibility +objective of the themes for a minimum 7:1 contrast ratio between +background and foreground values in their given combinations +(conformance with the WCAG AAA standard). + +New customisation options +========================= + +1 Completion Frameworks +----------------------- + +The star of the show has to be the new option that refashions the +aesthetics of completion UIs: Helm, Icomplete, Ido, Ivy, Sallet, +Selectrum. The 'modus-operandi-theme-completions' and +'modus-vivendi-theme-completions' accept the following symbols: + ++ nil (default) ++ moderate ++ opinionated + +Nil means that the overall presentation of the UI follows the patterns +established by its own source code. For example, Ivy uses four distinct +background and foreground combinations of accented colours to highlight +the matching groups. A grey background is added to denote the implicit +match between those groups. So we choose to respect this metaphor, +while applying colours that conform with the accessibility goal of our +project. Whereas Icomplete or Ido use subtle styles to present their +results. Again, we remain faithful to their presentation. + +With 'moderate', we apply nuanced background and foreground combinations +of accented colour values. This will slightly tone down Helm, Ivy, +Sallet, Selectrum, while it will slightly adjust the looks of Icomplete +and Ido. + +Whereas 'opinionated' has a more pronounced effect on the overall +aesthetics of the UI. For the likes of Icomplete and Ido which are +subtle by default, this option will use intense combinations of +background and foreground colours. They are the diametric opposite of +the nil value. Whereas Helm, Ivy, Sallet, Selectrum, will use even more +subtle colours. Again, they are farther away than their default looks. + +These new options supersede the now-deprecated and more limited in scope +variables of prior releases: + ++ modus-operandi-theme-intense-standard-completions ++ modus-vivendi-theme-intense-standard-completions + +Thanks to the following people for their valuable feedback in issue 75: +https://gitlab.com/protesilaos/modus-themes/-/issues/75 + ++ Anders Johansson ++ Manuel Uberti ++ Shreyas Ragavan + +2 Prompts +--------- + +The 'modus-operandi-theme-prompts' and modus-vivendi-theme-prompts' will +change the overall looks of minibuffer and shell prompts ('M-x shell' as +well as 'M-x eshell'). Their possible values are: + ++ nil (default) ++ subtle ++ intense + +Nil will only use a coloured foreground for the prompts' text. Simple +and effective. + +With 'subtle', the default foreground value is retained but is now +complemented by an appropriately tinted background. The effect is more +noticeable than the default, though not by much. + +While 'intense' applies a coloured background and foreground combination +that should clearly stand out from the rest of the context. + +Thanks to Manuel Uberti for sharing feedback in issue 74: +https://gitlab.com/protesilaos/modus-themes/-/issues/74 + +3 Fringe visibility +------------------- + +A new pair of symbols supersedes older variables: + ++ modus-operandi-theme-visible-fringes ==> modus-operandi-theme-fringes ++ modus-vivendi-theme-visible-fringes ==> modus-vivendi-theme-fringes + +While the deprecated options were booleans, the current ones offer a +choice between the following: + ++ nil (default) ++ subtle ++ intense + +Nil means that the fringes have no distinct background of their own. +They still exist per the settings of 'fringe-mode', but can only be +discerned by tracking the negative space between the frame's or window's +edge and the buffer's effective boundaries. + +The 'subtle' value will apply a greyscale background that is fairly +close to the default main background (pure white/black). The fringes +are now visible. + +As its name implies, 'intense' has a more pronounced effect than the +other values. It also uses a greyscale background. + +Review of already supported faces and colours +============================================= + +1 Magit blame styles +-------------------- + +The headers that Magit's blame interface produces were difficult to tell +apart from their context. A set of carefully selected colours now makes +sure that they are always distinct. Some subtle background values are +used, in addition to other typographic elements. + +Thanks to Damien Cassou for reporting this problem and for providing +valuable feedback that informed the final design. Refer to issue 71: +https://gitlab.com/protesilaos/modus-themes/-/issues/71 + +2 Paren match colours +--------------------- + +The face that highlights the matching delimiter when 'show-paren-mode' +(or equivalent) is enabled uses two dedicated colours, whose names are: +'bg-paren-match' and 'bg-paren-match-intense'. Those have been reviewed +to make them more obvious in various contexts and to improve their +overall consistency. + +A report with relative contrast ratios is available on my website: +https://protesilaos.com/codelog/2020-08-09-modus-themes-paren-match/ + +I benefited from valuable feedback from Shreyas Ragavan in issue 70: +https://gitlab.com/protesilaos/modus-themes/-/issues/70 + +3 Mu4e faces +------------ + +Some faces were tweaked to make it easier to distinguish replied, +forwarded, and draft messages from other headers. The changes are +fairly small in scope, but the effect should be that of an overall +improvement. + +Thanks to Shreyas Ragavan for noticing these inconsistencies and for +their continued participation in addressing them. See issue 69: +https://gitlab.com/protesilaos/modus-themes/-/issues/69 + +4 Notmuch message headings +-------------------------- + +A couple of inconsistencies with how notmuch would style email addresses +and folded messages were addressed. The generic 'italic' face was also +tweaked in the process, removing the foreground it would falsely define. + +Thanks to Damien Cassou for bringing these to my attention in issue 72: +https://gitlab.com/protesilaos/modus-themes/-/issues/72 + +5 hl-todo +--------- + +Let the special keywords of 'hl-todo-mode' use an optional slant, just +like code comments do. This is to ensure that they feel part of their +context. + +6 Magit general interface +------------------------- + +Several faces were reviewed in the interest of colour harmony and to +address potential inconsistencies or exaggerations. The most noticeable +change pertains to the log views, as we now use fewer accent values, +reducing whatever unnecessary "rainbow effect" may have existed. + +7 VC commit logs +---------------- + +The presentation of 'vc-print-log' and 'vc-print-root-log' has been +reviewed to reduce the stark contrast between the colours it once used. +While the elements remain distinct, the differences between them are +more subtle, which is preferable when viewing long lists of +similar-looking patterns. + +8 Powerline +----------- + +The active and inactive minibuffers now use appropriate accented +backgrounds or foregrounds for some of their elements. This makes them +better for their intended function. + +Thanks to Shreyas Ragavan and tycho garen for their feedback in issue +73, which was actually about adding support for Spaceline. It uses +Powerline as its dependency, so we eventually had to accommodate both of +them: https://gitlab.com/protesilaos/modus-themes/-/issues/73 + +Shreyas also helped by adding a short note in the README which informs +users of those two packages on how to tweak things when conducting tests +or changing themes. See merge requests 9 and 10: + ++ https://gitlab.com/protesilaos/modus-themes/-/merge_requests/9 ++ https://gitlab.com/protesilaos/modus-themes/-/merge_requests/10 + +9 Latex sectioning +------------------ + +The themes will no longer affect the height of the Latex sectioning +faces. This is because there already exists a variable that scales them +accordingly. + +Thanks to Anders Johansson for providing insights in issue 77: +https://gitlab.com/protesilaos/modus-themes/-/issues/77 + +10 Transient pop-up menu +------------------------ + +Extended support for its new colour-coded faces that follow in the +footsteps of the 'hydra' package for visual semantics. + +11 Miscellaneous +---------------- + +The following faces were refined: + ++ 'org-formula' inherits from 'fixed-pitch' to ensure that it does not + break table layouts when the user opts for a mixed-font setup (such as + with 'M-x variable-pitch-mode'). + ++ 'bongo-elapsed-track-part' uses a more appropriate accented + background. + ++ 'symbol-overlay-default-face' is less intense than before. This is in + response to feedback I received from Manuel Uberti as an aside in + issue 75: https://gitlab.com/protesilaos/modus-themes/-/issues/75 + ++ 'rectangle-preview' uses a slightly accented background, which + distinguishes it from the highlighted region. This is to denote a + different state where the user is typing in some text. + ++ 'diff-hl-change' now uses the more appropriate yellow colour instead + of blue. Yellow denotes "mixed changes" and, therefore, stands + between "removed" (red) and "added" (green). As it so happens, yellow + is a colour that derives by mixing red with green. + +New packages +============ + +The following are now explicitly supported by the themes: + ++ org-table-sticky-header ++ pkgbuild-mode ++ semantic ++ spaceline + +More faces or face groups that are defined: + ++ git-rebase (magit) ++ doom-modeline-debug-visual ++ file-name-shadow ++ the faces used by Emacs 27's 'display-line-numbers-major-tick' and + 'display-line-numbers-minor-tick' ++ table-cell + +Final notes +=========== + +There now exists an HTML version of the README, which will hopefully +make things easier for users: https://protesilaos.com/emacs/modus-themes/ + +Other changes are not user-facing. For example, using 'pcase' instead +of 'cond' to make relevant expressions more succinct. Or defining a +coloured underline in a more straightforward way. No need to document +them at length. + +While this release introduces customisation options, it feels as though +the themes are approaching a stable state. We know what works, we have +a comprehensive colour palette that can meet our evolving needs, and we +have already achieved broad package/face coverage. All while conforming +with the overarching objective of this project for a minimum 7:1 +contrast ratio between background and foreground values in any given +combination we specify. + +I wish to thank everyone who has helped me by testing things and sharing +their thoughts. The people already mentioned herein: + +- Anders Johansson (https://gitlab.com/andersjohansson) +- Damien Cassou (https://gitlab.com/DamienCassou) +- Manuel Uberti (https://gitlab.com/muberti) +- Shreyas Ragavan (https://gitlab.com/shrysr) +- tycho garen (https://gitlab.com/tychoish) +#+end_src + +* 0.11.0 +:PROPERTIES: +:CUSTOM_ID: h:7a453154-3486-45a8-9249-9183ad49ff42 +:END: + +#+begin_src text +Modus Operandi and Modus Vivendi version 0.11.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2020-07-31 + +This entry records the changes since version 0.10.0 (2020-06-24). The +present release covers close to 100 commits, some of which introduce +far-reaching changes. It is not just the quantity that matters. +Sometimes even a minor tweak requires lots of testing and forethought. +This release represents another month of intense work and attention to +detail. + +Palette review of "nuanced" colours +=================================== + +The themes contain a subset of palette variables that have a two-fold +utility: + +1. Provide a subtle coloured background that can be combined with all + foreground colours that are intended for text/code highlighting. + +2. Produce variegated text in cases where complementary information + needs to be displayed alongside some more prominent construct + (e.g. Org table formulas). + +In early July 2020, these colours went through a comprehensive review to +improve their intended use. The complete report is available on my +website: +<https://protesilaos.com/codelog/2020-07-08-modus-themes-nuanced-colours/> + +This formed the preparatory work that enabled several of the changes +documented herein, most noticeable among which is the "Org blocks" +customisation option. + +Customisation options +===================== + +Org blocks +---------- + +1. The symbols 'modus-operandi-theme-distinct-org-blocks' and + 'modus-vivendi-theme-distinct-org-blocks' are DEPRECATED. They are + now REPLACED by the general-purpose 'modus-operandi-theme-org-blocks' + and 'modus-vivendi-theme-org-blocks' respectively. + +2. The aforementioned new symbols allow users to configure different + styles for Org blocks. + + + Option 'greyscale' (which you must quote like this: 'greyscale) + will apply a subtle grey background to the contents of the block, + while it will extend its beginning and end lines to ensure that the + area is distinct from the rest of the buffer. This is the style + you would normally get with the old customisation options. + + + Option 'rainbow' (again, must be quoted) will instead apply a + colour-coded subtle background in the main area of the block. The + exact colour depends on the programming language being used. You + would need to check the source code for how these are currently + mapped (search for "org-src-block-faces"). The basic idea is to + have different colours that make it easier for mixing the + input/output of multiple programming languages. Users who engage + in literate programming may find this particularly useful. Because + the block is already quite apparent, the beginning and end lines + are not extended to the edge of the window, to avoid exaggerations + that could create distractions. + +Variable pitch headings (proportionately-spaced headings) +--------------------------------------------------------- + +The symbols 'modus-operandi-theme-proportional-fonts' and +'modus-vivendi-theme-proportional-fonts' are DEPRECATED. They are now +REPLACED by the more appropriately-named +'modus-operandi-theme-variable-pitch-headings' and +'modus-vivendi-theme-variable-pitch-headings' respectively. + +The intended effect is exactly the same as before, namely, to let +headings in Org and relevant modes use a proportionately-spaced font +regardless of what the default is (typically a monospaced typeface). + +Remember that to configure the exact font family for the generic +'variable-pitch' face, you can use something like this: + + (set-face-attribute 'variable-pitch nil :family "FiraGO") + +Check the README for further details on setting and mixing fonts. + +Faint syntax for programming +---------------------------- + +Users can now enable 'modus-operandi-theme-faint-syntax' or +'modus-vivendi-theme-faint-syntax'. The intended effect is to tone down +all syntax highlighting in programming modes, while always respecting +the overarching objective of these themes for a minimum contrast ratio +of 7:1 (highest accessibility standard for colour contrast---WCAG AAA). + +The default is to use more saturated colours. + +Intense hl-line +--------------- + +Toggling on 'modus-operandi-theme-intense-hl-line' or +'modus-vivendi-theme-intense-hl-line' will apply a more pronounced grey +to the background of faces that highlight the current line. This +affects tools such as the built-in 'hl-line-mode', which is in turn +enabled automatically by lots of other packages, like 'elfeed' and +'mu4e'. + +The default is to use a subtle grey. + +Intense paren-match +------------------- + +Same principle as above. 'modus-operandi-theme-intense-paren-match' and +'modus-vivendi-theme-intense-paren-match' will make the matching +parentheses more intense than the default subtle warm background. This +concerns modes such as that of the 'smartparens' package as well as the +built-in 'show-paren-mode'. + +Refactored the use of bold +========================== + +A major review of the themes now makes it possible to specify the exact +weight of what a "bold" typeface is. This is only meaningful for cases +where a font family has variants such as "semibold". + +Evaluate this, replacing "semibold" with the one your typeface supports: + + (set-face-attribute 'bold nil :weight 'semibold) + +The default is to use a standard bold weight. + +Packages and face groups +======================== + +Refine already-supported faces +------------------------------ + ++ The following packages now use more appropriate colour combinations: + + - diary + - annotate + - transient (magit pop-up menu, though also used elsewhere) + - fountain + - calendar + - mu4e + - markdown-mode + - outline-minor-faces + ++ Other changes: + + - org-agenda has undergone a thoroughgoing review to improve the + semantics of colour for scheduled tasks, deadlines, modeline + filters, current date etc. + + - org and outline-mode headings have been refined to look better with + the "rainbow headings" option that was introduced in an earlier + release (check the README). + + - org-quote now works properly with the "Org blocks" option mentioned + above. + + - org-checkbox-statistics uses the same foreground colour as org-todo, + for the sake of consistency. + + - org-date now always inherits from 'fixed-pitch', to ensure proper + alignment of elements when a mixed fonts setup is used (tools for + achieving this effect are documented at length in the README). The + relevant patch was contributed by Matthew Stevenson. + + - org-meta-line no longer looks like a comment, which helps denote its + special utility (e.g. when evaluating a table's formula). + + - org-warning now uses a variant of red for its text, which works + better in the contexts this face is used (e.g. the agenda or the + export dispatcher). + + - We now apply a slightly more accented colour combination for + 'secondary-selection', which is chiefly used by Org and Calendar in + various contexts. + + - Gnus group level faces make more considerate use of colour to better + denote their significance. + + - Cited text in message buffers has a better sequence of colours. + + - Two new Helm faces are supported. + + - Let 'keycast' use a different border colour when the "3D modeline" + option is enabled (refer to the README for that option). + + - Extend 'hl-todo-keyword-faces' with the "bug" keyword. + + - More intense colour for 'diff-hl-reverted-hunk-highlight'. + + - Tone down the focused modeline's border colour. + + - Define new bespoke faces that the themes use internally. + + - Use more appropriate colours for 'header-line-highlight'. + + - Apply greyscale line highlight for flycheck current line in the + diagnostics buffer, instead of the warmer colour combination it had + before. + + - Tweak text colour difference between MU4E read and unread messages. + +Added support for new packages +------------------------------ + ++ bongo ++ boon ++ dictionary ++ eshell-fringe-status ++ eshell-git-prompt ++ eshell-prompt-extras ++ highlight-tail ++ hl-defined ++ notmuch ++ tty-menu + +Miscellaneous +============= + ++ Expand the README with new documentation and clarify parts of the + existing one. + ++ Update the Wiki page with screenshots and their descriptions (this in + itself is a day's worth of work): + https://gitlab.com/protesilaos/modus-themes/-/wikis/Screenshots + ++ Make the source code of each theme work better with the built-in + 'outline-minor-mode'. Check my video if you need a demo on how I use + this in tandem with 'imenu': + https://protesilaos.com/codelog/2020-07-20-emacs-outline-imenu/ + +Thanks to, in no particular order: + ++ Shreyas Ragavan (https://gitlab.com/shrysr) for introducing me to the + idea that derived the "rainbow" Org blocks and for providing valuable + feedback in several issues. + ++ Matthew Stevenson (https://gitlab.com/matth0204) for contributing the + aforementioned patch for the 'org-date' face. + ++ Manuel Uberti (https://gitlab.com/muberti) for offering valuable + feedback in a number of issues (and special thanks for doing this for + several months now). + ++ Dinko (https://gitlab.com/dinkonin) for noticing a not-so-obvious bug + in the initial implementation of the "rainbow Org blocks" option. + ++ okamsn (https://gitlab.com/okamsn) for providing the necessary + feedback that allowed me to refactor the use of "bold", mentioned + above. + +Refer to the issue tracker (or commit log) for further details: +https://gitlab.com/protesilaos/modus-themes/-/issues +#+end_src + +* 0.10.0 +:PROPERTIES: +:CUSTOM_ID: h:de114a53-7cbd-49aa-bf24-d1f1f0bf342e +:END: + +#+begin_src text +Modus Operandi and Modus Vivendi version 0.10.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2020-06-24 + +This entry records the changes since version 0.9.0 (2020-06-03). The +present release is focused on stability and internal improvements. + +Fixes and adjustments +--------------------- + +Basil L. Contovounesios, aka @basil-conto, (and also a contributor to +core Emacs) sent several patches that do the following: + ++ Fix top-level parentheses so that the results of + 'custom-theme-set-faces' and 'custom-theme-set-variables' are not + passed as arguments to the first 'custom-theme-set-faces'. + ++ Fix the docstrings of the custom 'modus-theme-*' faces. + ++ Simplify the syntax of properties assigned to each face. + ++ Improve the way styles are inherited by Dired and Ibuffer. + +Basil also pointed out an inconsistency with regard to an unwanted +underline effect for the 'doom-modeline-urgent' face in Modus Vivendi. +It was promptly removed. + +From my part, I fixed issues 46 and 51 that concerned the way the +compiler would evaluate each theme's palette. The palette is now +defined as a constant. Further information: + +- https://gitlab.com/protesilaos/modus-themes/-/issues/46 +- https://gitlab.com/protesilaos/modus-themes/-/issues/51 + + +Improvements to existing faces +------------------------------ + +André Alexandre Gomes (@aadcg) provided valuable feedback and +suggestions in issue 50 on the redesign of several 'org-mode' faces. + +The thread is long and contains lots of screenshots: +https://gitlab.com/protesilaos/modus-themes/-/issues/50 + +The changes in outline: + ++ Org checkboxes have a subtle background which gives them a more + pronounced appearance while retaining their overall simplicity. + ++ Org dates use a more saturated variant of cyan than they did before. + It helps distinguish them from their context. Especially true for + dates inside of tables. + ++ Org agenda dates have also undergone a slight review to match the + above. + ++ Org time grid now uses a more appropriate foreground colour, which has + been designed specifically for unfocused context. + ++ Org todo keywords use a more semantically-correct variant of red, + rather than the purple one they had before. + ++ Org statistics' cookies for pending tasks use a red variant as well + rather than the previous yellow one, in the interest of consistency + and to avoid exaggerations. + + +Other internal refinements +-------------------------- + ++ Subtle review of the Modus Vivendi palette. In short, it addresses: + + - Imbalanced levels of luminance and inconsistent differences in hue + between them and their neighbouring colours (e.g. the greens between + them, and the greens next to the yellows in the context of syntax + highlighting). The result was that they would create an undesirable + emphatic 'pop out' effect when placed close to more moderate + colours. + + - Differences in luminance and hue could lead to scenaria where two + colours could be conflated with each other or otherwise fail to + perform their intended function. + + - The complete report is on my website: + https://protesilaos.com/codelog/2020-06-13-modus-vivendi-palette-review/ + ++ Major review of the 'diredfl' faces, in the interest of improved + readability and harmony between the various colours. This benefits + from the palette changes in Modus Vivendi, but also from a similar + review to Modus Operandi that was documented in version 0.9.0. + ++ Refactor the names of dedicates colours for "marking" purposes. These + are used in Dired, Ibuffer, Proced, etc. Then apply them consistently + throughout each theme. + ++ Make sure that 'stripes' uses the same colours as 'hl-line-mode'. + ++ Let symlinks use a more appropriate colour in Dired and Trashed. + ++ Refine the use of colour in 'magit-tag', 'eshell-prompt', + 'message-header-name', 'log-edit-header', 'change-log-function', + 'message-mml', 'message-header-name', 'message-separator'. These are + subtle (i.e. difficult) tweaks that improve the overall presentation + in context. + ++ Make diff indicators not use an unnecessary background when the + user-facing option for "subtle diffs" is enabled (check the README for + the exact name of this option). This ensures consistency between the + indicators and the actual scope of the diffs. + ++ Add support for the 'minibuffer-line' package and extend existing + support of the faces used in the built-in Emacs info pages. + +My thanks to Basil and André for their contributions! +#+end_src + +* 0.9.0 +:PROPERTIES: +:CUSTOM_ID: h:96ccc8b9-2d5e-4857-bf25-4e094e17bfed +:END: + +#+begin_src text +Modus Operandi and Modus Vivendi version 0.9.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2020-06-03 + +This entry records the changes since version 0.8.0 (2020-04-28). The +present release contains about 50 commits, covering a month of active +development. + +All changes are aligned with the primary objective of this project, +which is conformance with the WCAG AAA accessibility standard for colour +contrast. This translates to a minimum contrast ratio of 7:1 between a +given combination of foreground and background colours. The highest +standard of its kind. + +All customisation options that are booleans are off ('nil') by default. +The project's policy is to offer such features on an "opt-in" basis, +while always respecting the principle of least surprise. + +Refer to the README for further information on the exact names of +symbols and the like. + +New customisation options +------------------------- + ++ It is now possible to make the faces of Icomplete, Ido, and a few + other related tools such as 'orderless', use coloured backgrounds to + style their feedback. This is the aesthetic already in effect for + Ivy, Helm, and Selectrum. The default is more subtle, in that it uses + just an accented foreground value without any added background. + ++ Advanced users can now override both the exact values of colour + variables, as well as the mapping of properties/variables to faces. + In practice this means that it is possible to completely change parts + of the theme (or the entirety of it for that matter). It also means + that users can simply access the theme's palette for the sake of + correctly passing the appropriate value to some bespoke face of + theirs. + ++ An extra increment for scaled headings is now available. This should + hold the highest value on the scale. Such variables only take effect + when the user opts for the "scaled headings" option. + +Overview of changes +------------------- + ++ A set of internal reforms were carried through in order to allow the + colour palette to be accessed from user configuration files. This + required a lot of debugging work to make sure the themes compile + properly and performance is not affected. + + - The original idea for this redesign was suggested by Len Trigg in + issue 39: https://gitlab.com/protesilaos/modus-themes/-/issues/39. + Len also provided a real-world implementation of this new option, + which is included in the project's README. + + - André Alexandre Gomes helped figure out the problems caused by the + initial design of this feature. In particular, André identified a + performance penalty as well as errors pertaining to byte + compilation. Everything was eventually resolved. For more see + issue 44: https://gitlab.com/protesilaos/modus-themes/-/issues/44. + ++ Several org-mode faces were reviewed in order to cope well with mixed + font settings. This is about use-cases where the main typeface is + proportionately-spaced, either by default or by some minor mode like + the built-in 'variable-pitch-mode'. The intent of configuring those + faces is to make them always inherit a fixed-pitch (monospace) font + family, in the interest of preserving the alignment of elements. The + idea, suggested code, as well as user feedback were offered by Ben in + issue 40: https://gitlab.com/protesilaos/modus-themes/-/issues/40. + ++ Mixed font settings may have some side-effects depending on user + configurations. This is unavoidable as we cannot control how users + define their fonts. Mark Barton reported one such case, while he was + able to fix it by making use of the suggested typeface definitions. + See issue 42: https://gitlab.com/protesilaos/modus-themes/-/issues/42. + ++ The faces for the 'tab-bar-mode' and 'tab-line-mode' that ship with + Emacs 27 were written anew. Same for those of 'centaur-tabs'. The + ideas for the redesign as well as the overall aesthetic are Ben's, per + issue 41: https://gitlab.com/protesilaos/modus-themes/-/issues/41. + ++ An edge case with Helm's interpretation of colour values for its + ripgrep interface was reported by Manuel Uberti in issue 49: + https://gitlab.com/protesilaos/modus-themes/-/issues/49. It + essentially had to do with the syntax for the regexp engine as read by + the underlying 'rg' executable. Collaboration on that front + eventually led to fixes in Helm itself, committed by its maintainer. + Note that the README for the Modus themes already contains information + on how Helm applies a face to the matches of grep or grep-like + commands. Issue 49 confirmed what was already known in that regard + (i.e. that the "--color=never" command-line option is required to use + the Helm face, else a colour value from the ANSI colour vector is + used---both are supported by the themes). + ++ The faces for Flycheck, Flymake, and Flyspell that would apply an + underline effect were completely rewritten to account for relevant + differences between GUI and TUI Emacs. + + - For GUI Emacs, all affected faces will now just use a colour-coded + wavy underline. Empowered by the introduction of dedicated + linter-related colours in prior commits (for version 0.8.0), we no + longer have to change the foreground value of the offending text in + addition to applying the underline effect. Whereas before the text + would also get repainted, which was too intrusive in most + circumstances. + + - If support for wavy underlines is not available, we assume the + presence of a TUI, which generally is relatively more limited in its + ability to reproduce colours with precision (meaning that the + dedicated linter colour could be distorted, potentially producing + inaccessible combinations). So for those cases we apply a straight + underline combined with a colour-coded foreground for the affected + text. This makes it more intense compared to the GUI equivalent, + but is the necessary course of action to overcome the constraints + imposed by the underlying terminal. + ++ The palette of Modus Operandi underwent lots of subtle changes to make + the background value of hl-line-mode more visible while retaining the + overall style and character of the theme. In principle, you should + not be able to tell the difference, unless presented with a careful + side-by-side comparison. This is the comprehensive report, including + a reproducible org-mode document with all the relevant contrast ratios: + https://protesilaos.com/codelog/2020-05-10-modus-operandi-palette-review/. + ++ Fixed `org-hide' to actually "hide" by using the appropriate colour + value. + ++ Several other face groups received minor tweaks. + ++ The README was improved to better present the available customisation + options and to cover other topics of interest. + ++ Updated the screen shots and their description in the relevant Wiki + page: https://gitlab.com/protesilaos/modus-themes/-/wikis/Screenshots. + +Added support for +----------------- + ++ circe ++ el-search ++ eros ++ golden-ratio-scroll-screen ++ highlight-indentation ++ hyperlist ++ indium ++ journalctl-mode ++ minimap ++ nxml-mode ++ vdiff ++ yasnippet +#+end_src + +* 0.8.0 +:PROPERTIES: +:CUSTOM_ID: h:afa34aec-7079-4c45-8e16-ab4e7cc8cd6a +:END: + +#+begin_src text +Modus Operandi and Modus Vivendi version 0.8.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2020-04-28 + +This entry records the changes since version 0.7.0 (2020-03-30). The +present release contains a little more than a hundred commits, covering +one month of intense work. + +All changes are aligned with the primary objective of this project, +which is conformance with the WCAG AAA accessibility standard for colour +contrast. This translates to a minimum contrast ratio of 7:1 between a +given combination of foreground and background colours. + +All customisation options mentioned herein are off ('nil') by default. +The project's policy is to offer such features on an "opt-in" basis, +while always respecting the principle of least surprise. + +Refer to the README for further information. + + +Four new customisation options +------------------------------ + +The options in outline, with their detailed description below: + ++ Rainbow headings ++ Section headings ++ 3D modeline ++ Subtle diffs + +1. "Rainbow headings" will apply more vivid colours to headings in + 'org-mode' and 'outline-mode'. The gradation is similar to that of a + rainbow's colour spectrum. + + The default is to use colour values that are closer to the grey + scale. + +2. "Section headings" also apply to 'org-mode' and 'outline-mode'. They + will draw an overline over each heading and use a nuanced background + colour that is appropriate for each level. For Org, this option has + some additional effects, where it will render keywords and priority + cookies in a box and add to them a subtle background. This is to + make sure that everything feels consistent (to the extent possible). + + The default is to not use overlines, backgrounds, boxes in any of the + relevant faces. This is consistent with the standard austere + colouration of headings: to not deviate too much from a "plain text" + aesthetic. + +NOTE: "rainbow headings" and "section headings" can work on their own or +be combined together. + +3. "3D modeline" will use a faux unpressed button style for the current + window's modeline (like the standard looks of 'emacs -Q'). The + colours used for the active and inactive modelines are tweaked + accordingly to maximise the effect while retaining the visual + distinction between them. + + The default is to draw the modelines in a two-dimensional style, with + the active one having a more noticeable border around it. + +4. "Subtle diffs" will use colour-coded text for line-wise differences + without applying any appropriately-coded background value or, where + necessary, by using only a subtle greyscale background. This affects + 'diff-mode', 'magit', 'ediff', and 'smerge-mode'. For Magit an extra + set of tweaks is implemented to account for the differentiation + between the focused and unfocused diff hunks. + + Due to their unique requirements, word-wise or refined changes are + always drawn with a colour-coded background, though it is less + intense when this option is enabled. + + The default is to use a colour-coded background and foreground + combination (e.g. light green text on a dark green backdrop) and to + make appropriate adjustments for refined diffs and modes of + interaction such as Magit's focused/unfocused diff states. + + +Other major refinements +----------------------- + ++ Thoroughly revise the colours of 'ediff' and 'smerge-mode', so that + they are aligned with those of 'diff-mode' and 'magit'. This is in + addition to the "subtle diffs" options mentioned in the previous + section. + ++ Review the faces used by Flycheck and Flymake. A wavy/curly underline + is now used in all terminals that support it. The underlined text is + drawn with a more nuanced foreground than before. The previous design + was exaggerating an already clear effect and could make things more + difficult under certain circumstances. + ++ All language checkers, including the aforementioned linter front-ends, + now benefit from a new set of colours that are designed specifically + for this particular purpose. Makes the affected faces feel more + different than their context. + ++ Use dedicated colours for escape sequences, regular expression + constructs, and quoted characters. The goal is to better + differentiate them from their surroundings. + ++ Tweak the colours of 'hydra' to improve the distinction between its + various types of behaviour. + ++ Reduce the overall luminance of the background colours used in the + fringes by the likes of 'flycheck', 'flymake', 'diff-hl', etc. They + should now not stand out more than they should, while retaining their + intended role. + ++ Implement more saturated colours in Elfeed. The previous choices + could make it harder to differentiate the various parts of the + presentation. + ++ Make better use of the customisation options for bold and slanted + constructs where that is allowed. If a face is not tied to the + semantics of these styles then it is drawn without them, unless the + user specifically opts for the relevant customisation options. + + +Added support for packages (A-Z) +-------------------------------- + ++ ag ++ color-rg ++ ctrlf ++ debbugs ++ eglot ++ forge ++ helpful ++ highlight-symbol ++ ibuffer ++ icomplete ++ iflipb ++ magit-imerge ++ man ++ orderless ++ page-break-lines ++ parrot ++ phi-grep ++ phi-search ++ pomidor ++ rcirc ++ spell-fu ++ switch-window ++ swoop ++ tab-bar-mode ++ tab-line-mode ++ trashed ++ tomatinho ++ tuareg ++ vimish-fold ++ visible-mark ++ vterm ++ wcheck-mode ++ winum ++ woman + + +Miscellaneous changes and concluding remarks +-------------------------------------------- + ++ Rewrote large parts of the README to make the customisation options + easier to discover and understand. + ++ Updated the screen shots and their description in the relevant Wiki + page: https://gitlab.com/protesilaos/modus-themes/-/wikis/Screenshots +#+end_src + +* 0.7.0 +:PROPERTIES: +:CUSTOM_ID: h:353114b7-6980-4622-8057-b8cbb8361a8a +:END: + +#+begin_src text +Modus Operandi and Modus Vivendi version 0.7.0 + +By Protesilaos Stavrou <info@protesilaos.com> on 2020-03-30 + +This entry documents the changes since version 0.6.0 (2020-03-01). The +present release is the largest to date containing 110 commits. + +All changes conform with the primary objective of this project, which is +conformance with the WCAG AAA accessibility standard for colour +contrast. This represents a minimum contrast ratio of 7:1 between a +given combination of foreground and background colours. + +All customisation options mentioned herein are off ('nil') by default. +The project's policy is to offer such features on an "opt-in" basis. +Refer to the README or each theme's source code for the names of these +user-facing symbols. + +Major refinements to existing face groups +----------------------------------------- + ++ The headline feature of this release is a refined set of colours for + visualising version-control-system differences ("diffs"). The new + colours are less intense than before and are designed to better convey + the meaning of the constructs they apply to. Affected face groups are + those of 'magit' and 'diff-mode'. A future release will assess how + similar packages, such as 'ediff', can benefit from this work. + ++ The other major set of changes concerns the colours that apply to + fringes (see 'fringe-mode'). A new customisation option allows for a + distinct background for the fringes (courtesy of Anders Johansson in + commit 80fb704). The default uses the same colours as the main + buffer's background. Building on this effort, fringe indicators, such + as those of 'flycheck' now benefit from an entirely new set of + background+foreground colour combinations that are designed + specifically for the fringes. + ++ A new customisation option allows users to render 'org-mode' source + blocks in a distinct background colour. The default is to use the + same background as the rest of the buffer. When this option is + enabled, the background colour for the beginning and end line of such + blocks is extended to the end of the window (using the ':extend t' + attribute for >= Emacs 27). Older Emacs versions already extend to + the end of the window. + ++ The colour combination that shows the matching parentheses or + delimiters has been reviewed. The commit is fairly small and the + changes are immediately noticeable only to the most discerning of + eyes. Still, the considerations informing the review imposed a + rigorous method. Rather than summarise the findings, interested + readers are advised to refer to commit af3a327: it offers a + comprehensive analysis on the matter. + +Added support for packages (A-Z) +-------------------------------- + ++ auctex/tex ++ bm ++ buffer-expose ++ centaur-tabs ++ cider (tentative, feedback is much appreciated) ++ csv-mode ++ dynamic-ruler ++ ebdb ++ elfeed-score ++ flyspell-correct ++ fold-this ++ freeze-it ++ frog-menu ++ git-walktree ++ helm-switch-shell ++ highlight-defined ++ highlight-escape-sequences (hes-mode) ++ highlight-numbers ++ highlight-thing ++ hl-todo ++ ioccur ++ julia ++ kaocha-runner ++ markup-faces (adoc-mode) ++ multiple-cursors ++ num3-mode ++ org-roam ++ org-superstar ++ org-treescope ++ outline-minor-mode ++ paradox ++ rainbow-identifiers ++ rg ++ ripgrep ++ sallet (tentative, feedback is much appreciated) ++ selectrum ++ sesman ++ side-notes ++ skewer-mode ++ stripes ++ symbol-overlay ++ syslog-mode ++ vc-annotate (C-x v g) ++ volatile-highlights ++ web-mode ++ yaml-mode + +Note about VC-annotate +---------------------- + +Quoting from the relevant note in the project's README: + + Due to the unique way `vc-annotate' (`C-x v g') applies colours, + support for its background mode (`vc-annotate-background-mode') is + disabled at the theme level. + + Normally, such a drastic measure should not belong in a theme: + assuming the user's preferences is bad practice. However, it has + been deemed necessary in the interest of preserving colour contrast + accessibility while still supporting a useful built-in tool. + + If there actually is a way to avoid such a course of action, without + prejudice to the accessibility standard of this project, then please + report as much (or contribute as per the information in the + Contributing section). + + +Overview of refinements to already supported packages +----------------------------------------------------- + +In this section the notion of "dedicated colours" pertains to colour +values that are reserved for special faces. They are never used for +syntax highlighting or other common scenaria. + ++ Define new background colours for fringe indicators (as noted in the + first section). Apply them to 'bm', 'diff-hl', 'git-gutter', + 'flycheck' fringe indicators. All such indicators are now made more + visible and work better with the new customisation option for + rendering the fringes in a distinct background. + ++ Define dedicated colours for tab-like interfaces. Currently these + apply only to 'centaur-tabs'. The intention is to eventually + implement them to the tab modes that ship with Emacs 27, as well as + any other package that offers such functionality. + ++ Define dedicated colours for actions that "mark" items. Use them in + 'dired', 'proced', 'gnus'. An accented background is combined with an + accented foreground. The intention is to make the underlying + construct distinct even under circumstances where the mark's + background changes, such as when it intersects with 'hl-line-mode' or + 'stripes': the accented foreground will still be recognisable as a + colour that differs from the main foreground. The use of a bold font + weight further reinforces the intended action. + ++ Refine 'dired' faces to account for the new "mark" styles. + Directories are no longer rendered in a bold weight. + ++ Tweak the colours used in the built-in 'diary' and 'calendar' for + better usability. + ++ Tweak 'deadgrep' colours for consistency with packages that offer + similar functionality. + ++ Tweak 'compilation-line-number' in the interest of consistency with + similar interfaces. + ++ Use a more appropriate colour for 'trailing-whitespace'. It now is a + colour value that was designed specifically as a background. + ++ Expand 'fountain-mode' support by covering its new heading faces. The + headings will be presented in larger font sizes, or using proportional + fonts, should the user enable the relevant theme customisation options + (see README or source code). + ++ Remove bold weight from matching parentheses in 'show-paren-mode' and + 'smartparens'. The temporarily applied bold weight can cause + misalignments while using certain fonts. Also apply the new colours + for matching delimiters, as documented in the first section. + ++ Refine 'outline-mode' colours to be consistent with those of Org's + headings. + ++ Several usability and colour refinements for 'helm' and related + packages in that milieu. + ++ Remove box property from emphasis markers in the mode line. It + created inconsistencies with other faces. + ++ Refine the colours used in Magit logs, `change-log', `log-view'. They + are meant to be more distinct from their context, without drawing too + much attention to themselves. + ++ Minor internal fixes for indentation and the like. + +Miscellaneous changes and concluding remarks +-------------------------------------------- + ++ Add section in the README which documents a legal requirement for all + potential non-trivial code contributions: the need to assign copyright + to the Free Software Foundation. The Modus Themes are now distributed + via the official GNU ELPA repository and copyright over them is + assigned to the FSF. + ++ Add CHANGELOG file which consolidates all tagged release notes such as + this one. + ++ Add new screen shots to the relevant Wiki page, together with detailed + descriptions on what is being demonstrated: + https://gitlab.com/protesilaos/modus-themes/-/wikis/Screenshots + +Special thanks to Manuel Uberti for reporting several issues and +offering feedback where appropriate. I was able to add support for lots +of new packages. While a few among the already supported face groups +underwent tweaks and refinements. The 'helm' ecosystem benefited the +most. + +Thanks to Anders Johansson for the patch that introduced the +fringes-related customisation option. It inspired me to reconsider the +use of this particular area of the interface, which eventually led to +the barrage of commits that refashioned the fringe indicators. A major +win overall. + +Thanks to Jonathan Otsuka for fixing an error of mine on the naming of +some symbols. My apologies for missing it: I will be more careful from +now on. + +Note: both patches were small, requiring no copyright assignment. +Larger contributions are always welcome, though make sure you read the +section in the README with regard to assigning copyright to the Free +Software Foundation. +#+end_src + +* 0.6.0 +:PROPERTIES: +:CUSTOM_ID: h:c8c33ff2-6f75-4642-a27e-ee6e8abc493e +:END: + +#+begin_src text +This release contains lots of refinements and additions. + +Let me start with an administrative point: I have completed the process +of assigning my copy rights to the Free Software Foundation. This +covers every contribution I make to GNU Emacs. In practice, it means +that the Modus themes can now be included in the official ELPA archive +and theoretically be shipped with Emacs itself. The ELPA inclusion is +ongoing. Once it is completed, I will update the docs accordingly. + +The administrative change has no effect on the way this project is +handled. I still am the developer/maintainer and will continue to +improve things further. If you still have questions, feel free to +contact me: https://protesilaos.com/contact + +Moving on to the changes since version 0.5.0 (2020-01-26). + +Added support for: + ++ alert ++ apropos (built-in) ++ dap-mode ++ deft ++ dim-autoload ++ dired-git ++ enhanced-ruby-mode ++ gbd-mi.el (built-in library) ++ helm-ls-git ++ helm-xref ++ imenu-list ++ jira (org-jira) ++ js2-mode ++ jupyter ++ org-pomodoro ++ origami ++ rmail (built-in) ++ vc-print-log (built-in) ++ window-divider-mode (built-in) ++ xref (built-in) + +Refinements to existing faces: + ++ A new subset of "nuanced" accent colours has been introduced. These +are named {red,green,yellow,blue,magenta,cyan}-nuanced. Their purpose +is to be used in contexts where lots of structured information is +presented to the user, but each component does not need to draw too much +attention to itself (e.g. Org's metadata). As always, their contrast +ratio is designed to always be >= 7:1 relative to the backgrounds they +may be combined with. + ++ Greatly improve the support for Gnus, even though most changes are +subtle and are made in the interest of consistency. The group levels +now make use of the "nuanced" palette where appropriate (to denote +levels of lower importance). + ++ Several refinements for Org, including the use of "nuanced" colours +for various metadata tags. The agenda headers will now be scaled +appropriately and use a variable-pitch font if the user sets the +relevant customisation values of the theme they are using (check the +documentation in each theme file or the repo's README). + ++ Lots of refinements for Helm. Some of these were introduced to align +the overall aesthetic with equivalent metaphors in Ivy. Others are +meant to improve the styles of the headers and make various constructs +consistent with their variants in the Helm ecosystem but also with their +non-Helm counterparts (such as xref file names with and without Helm, +but also with Helm's grep). + ++ Improve the colours of buttons in contexts such as M-x customize. +This is especially noticeable in modus-vivendi-theme (the dark theme) +where the buttons are a darker shade of grey rather than the original +lighter one. + ++ Keycast now uses styles that are more consistent with the overall +aesthetic of the Modus themes. This means that the mode line indicators +are blue-ish (blue is generally used for highlights in the mode line, +but also when hovering over an item with the mouse pointer). The pseudo +button effect (colours + 3d) has been removed in favour of a flat look, +in line with the flatness of the mode line itself. Whereas before the +keycast faces where designed to be consistent with the package's +defaults. + +There were also a few minor refinements for: + ++ calendar and diary ++ icomplete ++ mm-uu-extract ++ nobreak-hyphen and nobreak-space ++ org-habit ++ tooltip-mode + +Finally, the Commentary section of each theme has been greatly expanded. +It now includes the user-facing customisation options and the complete +list of supported packages. +#+end_src + +* 0.5.0 +:PROPERTIES: +:CUSTOM_ID: h:dffc2bd4-6597-4be4-88f6-b349be7ebc6e +:END: + +#+begin_src text +This release contains support for several new packages and lots of +refinements for existing ones. A lot of work went into making the +themes more robust by reviewing the inheritance of styles from one +face group to another (in general, the ':inherit' property should not +be used frivolously). Several subtle changes were made to the colour +palette of both themes to ensure consistency, enable more possible +combinations, and avoid potential ambiguity under certain potential +circumstances. + +Overall, this release gives me confidence that the themes have reached +a fairly stable state. What follows is an overview of the changes +since version 0.4.0 (2020-01-02). + +Added support for: + ++ equake ++ flymake ++ focus ++ fountain (fountain-mode) ++ git-lens ++ git-timemachine ++ hi-fill-column ++ highlight-blocks ++ info-colors ++ lsp-mode ++ lsp-ui ++ proced (built-in) ++ regexp-builder (built-in) ++ suggest + +Refinements: + ++ The header line uses its own dedicated colours. Several changes + were made in 'eww', 'info', 'elfeed', 'magit', 'flycheck' to make + sure that any accent value that appears there conforms with the + overarching accessibility objective of the Modus themes (contrast + ratio of >= 7:1, else WCAG AAA). ++ 'ivy' no longer uses a box style for the current line, as that was + not always reliable. Appropriate colours are used instead. ++ 'org-mode' blocks use a foreground value that distinguishes their + opening and closing tags from source code comments. ++ The 'org-ellipsis' face was configured to always inherit the looks + of its respective heading or element, rather than have its own + excessive styling. ++ 'paren-match' has colours that are designed specifically for it. + This is done to retain their utility while making sure they are not + mistaken for some other type of feedback. ++ 'magit' has explicit styles for the mode line process indicators, + instead of inheriting from another face. The intention is to use + foreground values that are designed specifically for use on the mode + line (the minimum contrast ratio requirement). ++ 'erc' faces have been thoroughly reviewed in the interest of better + usability. Its mode line indicators now use appropriate colours. ++ The faces of the 'messages' library have been thoroughly reviewed. + This affects various email interfaces, but also 'elfeed' entry + metadata headings. ++ 'whitespace-mode' no longer has a newline character that stands out. + That kind of emphasis was not necessary, given that the symbol used + is a dollar sign, which is already far more visible than a mid dot. ++ 'font-lock' (generic syntax highlighting) has better colour + combinations for regexp grouping constructs. ++ 'rainbow-delimiters' was given its missing base error face. ++ 'git-commit' comment action uses a slightly different foreground + value than before to better match its context. ++ 'isearch' and 'query-replace' use colours that properly denote each + action's utility. ++ 'visual-regexp' has been reviewed to make the matching groups more + distinct from each other. ++ 'occur' and any other buffer that relies on the 'match' face can now + benefit from the new colour combinations, in that its results cannot + be confused for the active 'isearch' or 'query-replace' or even + their lazily highlighted results (or, indeed, of any other search + tool). ++ 'company' uses faces for its search feedback that are consistent + with other search metaphors. ++ Emacs 27's new ':extend' property is only implemented where + necessary (note that the latest release is version 26.3). +#+end_src + +* 0.4.0 +:PROPERTIES: +:CUSTOM_ID: h:1597e301-f9df-4aac-8ec5-b8ecf34f2930 +:END: + +#+begin_src text +This is an overview of the changes since version 0.3.0 (2019-12-25). + +Add support for: + + + ert + + flycheck-indicator + + mentor + + mu4e-conversation + + powerline-evil + + telephone-line + + vc (built-in version control) + +Refinements to already-supported packages: + + + company-mode (several refinements) + + doom-modeline (major review) + + helm (several tweaks) + + hl-line-mode (use unique background) + + ivy (improve matching line) + + line-number-mode (minor tweaks) + + markdown-mode (comprehensive expansion) + + mode-line (more appropriate styles for the highlight) + + powerline (minor tweaks) + + region (use unique background) + + swiper (improve matching line in main window) + + whitespace-mode (several refinements) + + mu4e (tweak mu4e-modeline-face for consistency) + +Miscellaneous: + + + Fix actual and potential problems with cursor faces that would + distort the use of appropriate background and foreground colours. + The documentation stipulates that the `cursor' face cannot be + inherited by other faces, due to its peculiar nature of only + recognising the background colour. + + Add support for more bold constructs in code. As with all such + options, it is disabled by default, expecting the user to + explicitly opt in. + + Declare additional custom faces. Only meant for internal use. + + Subtle refinements to "active" colour values in both Modus + Operandi and Modus Vivendi. These mostly concern the mode line + (with a few special exceptions), where emphasis has been placed on + the need to provide greater contrast between accent values that + can be used there. + + Minor documentation refinements. +#+end_src + +* 0.3.0 +:PROPERTIES: +:CUSTOM_ID: h:cb0ca8dc-3960-4490-b3c4-27d10cf6ed44 +:END: + +#+begin_src text +Overview of changes since 0.2.0 (2019-12-18): + ++ Add support for the following packages: + + + apt-sources-list + + calfw + + counsel-css + + counsel-notmuch + + counsel-org-capture-string + + cov + + disk-usage + + evil-visual-mark-mode + + geiser + + keycast + + org-journal + + org-noter + + paren-face + + powerline + + vc + + xah-elisp-mode + ++ Explicitly style the following packages (these were already covered, + in terms of the colours they used, but are now targeted directly): + + + calendar + + counsel + + cursor + + package (M-x list-packages) + ++ Minor tweaks to face groups: + + + dired + + compile + ++ Fixes and refinements: + + + Documentation strings will now inherit the option for slanted + constructs (off by default -- see the README about all the user + options). + + Comment delimiters have the same styles as the body of the comment + to avoid inconsistencies when the option for slanted constructs is + enabled. + + The line number that is displayed in the compile log is now + correctly styled. + + Removed duplicate entries for ivy-remote and added ivy-separator. + + Ensure that the minibuffer prompt is always above the minimum + contrast ratio of 7:1, by using a more appropriate shade of cyan. + + Properly reference a couple of variables in Modus Vivendi. + ++ Internal adjustments: + + + Decouple the core dired faces from those of external packages. + + Same for org and org-recur. + ++ Minor documentation updates. +#+end_src + +* 0.2.0 +:PROPERTIES: +:CUSTOM_ID: h:c9746d04-adf4-41b1-9b7c-6caaf17f8816 +:END: + +#+begin_src text +Overview of changes since 0.1.0 (2019-12-09): + ++ Comprehensive review of `org-mode' faces. The use of colour should +now be more consistent with the semantics of each element. These should +also respond better to a variety of combinations, such as when the user +has `hl-line-mode' enabled. The agenda view is the greatest beneficiary +of this review. + ++ Make `mu4e' mode line faces consistent with other elements that may be +placed on the mode line. + ++ Make `gnus' header name/subject more distinct. + ++ Several minor refinements to `ivy' and its extensions. + ++ General usability refinements to `ace-window'. + ++ Minor review of `elfeed' styles, in the interest of improving the +contrast between the elements. + ++ Add support for: + + `persp-mode' (fork of the already supported `perspective') + + `dashboard' + + `evil-mode' + + `evil-goggles' + + `ruler-mode' +#+end_src + +* 0.1.0 +:PROPERTIES: +:CUSTOM_ID: h:e14e612e-6951-4812-bc88-62c498bd5644 +:END: + +#+begin_src text +First stable release of Modus Operandi and Modus Vivendi. +#+end_src diff --git a/elpa/modus-themes-4.3.0/README-elpa b/elpa/modus-themes-4.3.0/README-elpa @@ -0,0 +1,33 @@ +# Modus themes for GNU Emacs + +IMAGES HERE: <https://protesilaos.com/emacs/modus-themes-pictures>. + +Highly accessible themes, conforming with the highest standard for +colour contrast between background and foreground values (WCAG AAA). +They also are optimised for users with red-green colour deficiency. + +The themes are very customisable and provide support for a very wide +range of packages. Their manual is detailed so that new users can get +started, while it also provides custom code for all sorts of more +advanced customisations. + +Since August 2020, the original Modus themes (`modus-operandi`, +`modus-vivendi`) are built into Emacs version 28 or higher. Emacs 28 +ships with `modus-themes` version `1.6.0`. Emacs 29 includes version +`3.0.0`. Emacs 30 provides a newer, refactored version that +thoroughly refashions how the themes are implemented and customized. +Such major versions are not backward-compatible due to the limited +resources at my disposal to support multiple versions of Emacs and of +the themes across the years. + ++ Package name (GNU ELPA): `modus-themes` ++ Official manual: <https://protesilaos.com/emacs/modus-themes> ++ Change log: <https://protesilaos.com/emacs/modus-themes-changelog> ++ Colour palette: <https://protesilaos.com/emacs/modus-themes-colors> ++ Sample pictures: <https://protesilaos.com/emacs/modus-themes-pictures> ++ Git repo on SourceHut: <https://git.sr.ht/~protesilaos/modus-themes> + - Mirrors: + + GitHub: <https://github.com/protesilaos/modus-themes> + + GitLab: <https://gitlab.com/protesilaos/modus-themes> ++ Mailing list: <https://lists.sr.ht/~protesilaos/modus-themes> ++ Backronym: My Old Display Unexpectedly Sharpened ... themes diff --git a/elpa/modus-themes-4.3.0/README.md b/elpa/modus-themes-4.3.0/README.md @@ -0,0 +1,33 @@ +# Modus themes for GNU Emacs + +IMAGES HERE: <https://protesilaos.com/emacs/modus-themes-pictures>. + +Highly accessible themes, conforming with the highest standard for +colour contrast between background and foreground values (WCAG AAA). +They also are optimised for users with red-green colour deficiency. + +The themes are very customisable and provide support for a very wide +range of packages. Their manual is detailed so that new users can get +started, while it also provides custom code for all sorts of more +advanced customisations. + +Since August 2020, the original Modus themes (`modus-operandi`, +`modus-vivendi`) are built into Emacs version 28 or higher. Emacs 28 +ships with `modus-themes` version `1.6.0`. Emacs 29 includes version +`3.0.0`. Emacs 30 provides a newer, refactored version that +thoroughly refashions how the themes are implemented and customized. +Such major versions are not backward-compatible due to the limited +resources at my disposal to support multiple versions of Emacs and of +the themes across the years. + ++ Package name (GNU ELPA): `modus-themes` ++ Official manual: <https://protesilaos.com/emacs/modus-themes> ++ Change log: <https://protesilaos.com/emacs/modus-themes-changelog> ++ Colour palette: <https://protesilaos.com/emacs/modus-themes-colors> ++ Sample pictures: <https://protesilaos.com/emacs/modus-themes-pictures> ++ Git repo on SourceHut: <https://git.sr.ht/~protesilaos/modus-themes> + - Mirrors: + + GitHub: <https://github.com/protesilaos/modus-themes> + + GitLab: <https://gitlab.com/protesilaos/modus-themes> ++ Mailing list: <https://lists.sr.ht/~protesilaos/modus-themes> ++ Backronym: My Old Display Unexpectedly Sharpened ... themes diff --git a/elpa/modus-themes-4.3.0/dir b/elpa/modus-themes-4.3.0/dir @@ -0,0 +1,19 @@ +This is the file .../info/dir, which contains the +topmost node of the Info hierarchy, called (dir)Top. +The first time you invoke Info you start off looking at this node. + +File: dir, Node: Top This is the top of the INFO tree + + This (the Directory node) gives a menu of major topics. + Typing "q" exits, "H" lists all Info commands, "d" returns here, + "h" gives a primer for first-timers, + "mEmacs<Return>" visits the Emacs manual, etc. + + In Emacs, you can click mouse button 2 on a menu item or cross reference + to select it. + +* Menu: + +Emacs misc features +* Modus Themes: (modus-themes). Elegant, highly legible and customizable + themes. diff --git a/elpa/modus-themes-4.3.0/doc/doclicense.texi b/elpa/modus-themes-4.3.0/doc/doclicense.texi @@ -0,0 +1,505 @@ +@c The GNU Free Documentation License. +@center Version 1.3, 3 November 2008 + +@c This file is intended to be included within another document, +@c hence no sectioning command or @node. + +@display +Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. +@uref{https://fsf.org/} + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, La@TeX{} input +format, SGML or XML using a publicly available +DTD, and standard-conforming simple HTML, +PostScript or PDF designed for human modification. Examples +of transparent image formats include PNG, XCF and +JPG@. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, SGML or +XML for which the DTD and/or processing tools are +not generally available, and the machine-generated HTML, +PostScript or PDF produced by some word processors for +output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +The ``publisher'' means any person or entity that distributes copies +of the Document to the public. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section Entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{https://www.gnu.org/licenses/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy's public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. + +@item +RELICENSING + +``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the +site means any set of copyrightable works thus published on the MMC +site. + +``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. + +``Incorporate'' means to publish or republish a Document, in whole or +in part, as part of another Document. + +An MMC is ``eligible for relicensing'' if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole +or in part into the MMC, (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. + +The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. + +@end enumerate + +@page +@heading ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group + Copyright (C) @var{year} @var{your name}. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +@end group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with@dots{}Texts.''@: line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: diff --git a/elpa/modus-themes-4.3.0/doc/modus-themes.info b/elpa/modus-themes-4.3.0/doc/modus-themes.info @@ -0,0 +1,6278 @@ +This is modus-themes.info, produced by makeinfo version 7.0.3 from +modus-themes.texi. + +Copyright (C) 2020-2023 Free Software Foundation, Inc. + + 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.” + +INFO-DIR-SECTION Emacs misc features +START-INFO-DIR-ENTRY +* Modus Themes: (modus-themes). Elegant, highly legible and customizable themes. +END-INFO-DIR-ENTRY + + +File: modus-themes.info, Node: Top, Next: Overview, Up: (dir) + +Modus themes for GNU Emacs +************************** + +Copyright (C) 2020-2023 Free Software Foundation, Inc. + + 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.” + + This manual, written by Protesilaos Stavrou, describes the +customization options for the Modus themes, and provides every other +piece of information pertinent to them. + + The documentation furnished herein corresponds to stable version +4.3.0, released on 2023-09-19. Any reference to a newer feature which +does not yet form part of the latest tagged commit, is explicitly marked +as such. + + Current development target is 4.4.0-dev. + + • Package name (GNU ELPA): ‘modus-themes’ + • Official manual: <https://protesilaos.com/emacs/modus-themes> + • Change log: <https://protesilaos.com/emacs/modus-themes-changelog> + • Color palette: <https://protesilaos.com/emacs/modus-themes-colors> + • Sample pictures: + <https://protesilaos.com/emacs/modus-themes-pictures> + • Git repo on SourceHut: + <https://git.sr.ht/~protesilaos/modus-themes> + • Mirrors: + • GitHub: <https://github.com/protesilaos/modus-themes> + • GitLab: <https://gitlab.com/protesilaos/modus-themes> + • Mailing list: <https://lists.sr.ht/~protesilaos/modus-themes> + • Backronym: My Old Display Unexpectedly Sharpened ... themes + +* Menu: + +* Overview:: +* Installation:: +* Enable and load:: +* Customization options:: +* Advanced customization:: +* Face coverage:: +* Notes on individual packages:: +* Frequently Asked Questions:: +* Contributing:: +* Acknowledgements:: +* GNU Free Documentation License:: +* Indices:: + +— The Detailed Node Listing — + +Overview + +* How do the themes look like:: +* Learn about the latest changes:: + +Installation + +* Install manually from source:: +* Install from the archives:: +* Install on GNU/Linux:: +* Dealing with byte compilation errors:: + +Install on GNU/Linux + +* Debian 11 Bullseye:: +* GNU Guix:: + +Enable and load + +* The require-theme for built-in Emacs themes:: +* Sample configuration with and without use-package:: +* Differences between loading and enabling:: + +Customization options + +* Custom reload theme:: Toggle auto-reload of the theme when setting custom variables +* Disable other themes:: Determine whether loading a Modus themes disables all others +* Bold constructs:: Toggle bold constructs in code +* Italic constructs:: Toggle italic font constructs in code +* Mixed fonts:: Toggle mixing of font families +* Command prompts:: Control the style of command prompts +* Completion UIs:: Choose among several styles for completion UIs +* Org mode blocks:: Choose among plain, gray, or tinted backgrounds +* Heading styles:: Choose among several styles, also per heading level +* UI typeface:: Toggle the use of variable-pitch across the User Interface +* Palette overrides:: Refashion color values and/or semantic color mappings + +Advanced customization + +* Palette override presets:: +* Stylistic variants using palette overrides:: +* More accurate colors in terminal emulators:: +* Range of color with terminal emulators:: +* Preview theme colors:: +* Per-theme customization settings:: +* Get a single color from the palette:: +* Use theme colors in code with modus-themes-with-colors:: +* Do not extend the region background:: +* Add padding to mode line:: +* Remap face with local value:: +* Font configurations for Org and others:: +* Configure bold and italic faces:: +* Custom Org todo keyword and priority faces:: +* Custom Org emphasis faces:: +* Update Org block delimiter fontification:: +* Measure color contrast:: +* Load theme depending on time of day:: +* Backdrop for pdf-tools:: +* Toggle themes without reloading them:: +* A theme-agnostic hook for theme loading:: +* Use more spacious margins or padding in Emacs frames:: +* Custom hl-todo colors:: +* Add support for solaire-mode:: + +Stylistic variants using palette overrides + +* Make the mode line borderless:: +* Make the active mode line colorful:: +* Make the tab bar more or less colorful:: +* Make the fringe invisible or another color:: +* Make links use subtle or no underlines:: +* Make prompts more or less colorful:: +* Make completion matches more or less colorful:: +* Make comments yellow and strings green:: +* Make code syntax use the old alt-syntax style:: +* Make use of alternative styles for code syntax:: +* Make matching parenthesis more or less intense:: +* Make box buttons more or less gray:: +* Make TODO and DONE more or less intense:: +* Make headings more or less colorful:: +* Make Org agenda more or less colorful:: +* Make inline code in prose use alternative styles:: +* Make mail citations and headers more or less colorful:: +* Make the region preserve text colors, plus other styles: Make the region preserve text colors plus other styles. +* Make mouse highlights more or less colorful:: +* Make language underlines less colorful:: +* Make line numbers use alternative styles:: +* Make diffs use only a foreground:: +* Make deuteranopia diffs red and blue instead of yellow and blue:: +* Make the themes look like what the maintainer uses:: + +Face coverage + +* Supported packages:: Full list of covered face groups +* Indirectly covered packages:: + +Notes on individual packages + +* Note on calendar.el weekday and weekend colors: Note on calendarel weekday and weekend colors. +* Note on git-gutter in Doom Emacs:: +* Note on php-mode multiline comments:: +* Note on underlines in compilation buffers:: +* Note on inline Latex in Org buffers:: +* Note on dimmer.el: Note on dimmerel. +* Note on display-fill-column-indicator-mode:: +* Note on highlight-parentheses.el: Note on highlight-parenthesesel. +* Note on mmm-mode.el background colors: Note on mmm-modeel background colors. +* Note for prism:: +* Note on company-mode overlay pop-up:: +* Note on ERC escaped color sequences:: +* Note on powerline or spaceline:: +* Note on SHR colors:: +* Note on SHR fonts:: +* Note on Ement colors and fonts:: +* Note on pdf-tools link hints:: +* Note on the Notmuch logo:: +* Note on goto-address-mode faces:: + +Frequently Asked Questions + +* Is the contrast ratio about adjacent colors?:: +* What does it mean to avoid exaggerations?:: +* Why are colors mostly variants of blue, magenta, cyan?: Why are colors mostly variants of blue magenta cyan?. +* What is the best setup for legibility?:: +* Are these color schemes?:: +* Port the Modus themes to other platforms?:: + +Contributing + +* Sources of the themes:: +* Issues you can help with:: +* Patches require copyright assignment to the FSF:: + +Indices + +* Function index:: +* Variable index:: +* Concept index:: + + + +File: modus-themes.info, Node: Overview, Next: Installation, Prev: Top, Up: Top + +1 Overview +********** + +The Modus themes are designed for accessible readability. They conform +with the highest standard for color contrast between combinations of +background and foreground values. For small sized text, this +corresponds to the WCAG AAA standard, which specifies a minimum rate of +distance in relative luminance of 7:1. + + The Modus themes consist of eight themes, divided into four +subgroups. + +Main themes + ‘modus-operandi’ is the project’s main light theme, while + ‘modus-vivendi’ is its dark counterpart. These two themes are part + of the project since its inception. They are designed to cover a + broad range of needs and are, in the opinion of the author, the + reference for what a highly legible “default” theme should look + like. + +Tinted themes + ‘modus-operandi-tinted’ and ‘modus-vivendi-tinted’ are variants of + the two main themes. They slightly tone down the intensity of the + background and provide a bit more color variety. + ‘modus-operandi-tinted’ has a set of base tones that are shades of + light ochre (earthly colors), while ‘modus-vivendi-tinted’ gives a + night sky impression. + +Deuteranopia themes + ‘modus-operandi-deuteranopia’ and its companion + ‘modus-vivendi-deuteranopia’ are optimized for users with red-green + color deficiency. This means that they do not use red and green + hues for color-coding purposes, such as for diff removed and added + lines. Instead, they implement colors that are discernible by + users with deueteranopia or deuteranomaly (mostly yellow and blue + hues). + +Tritanopia themes + ‘modus-operandi-tritanopia’ and its counterpart + ‘modus-vivendi-tritanopia’ are optimized for users with blue-yellow + color deficiency. The idea is the same as with the deuteranopia + variants: color coding relies only on hues that are accessible to + people with tritanopia or tritanomaly, namely, shades of red and + cyan. + + To ensure that users have a consistently accessible experience, the +themes strive to achieve as close to full face coverage as possible, +while still targeting a curated list of well-maintained packages (*note +Face coverage::). + + The overarching objective of this project is to always offer +accessible color combinations. There shall never be a compromise on +this principle. If there arises an inescapable trade-off between +usability and stylistic considerations, we will always opt for the +former. + + Starting with version 0.12.0 and onwards, the themes are built into +GNU Emacs. + +* Menu: + +* How do the themes look like:: +* Learn about the latest changes:: + + +File: modus-themes.info, Node: How do the themes look like, Next: Learn about the latest changes, Up: Overview + +1.1 How do the themes look like +=============================== + +Check the web page with the screen shots +(https://protesilaos.com/emacs/modus-themes-pictures/). Note that the +themes are highly customizable (*note Customization options::). + + +File: modus-themes.info, Node: Learn about the latest changes, Prev: How do the themes look like, Up: Overview + +1.2 Learn about the latest changes +================================== + +Please refer to the web page with the change log +(https://protesilaos.com/emacs/modus-themes-changelog). It is +comprehensive and covers everything that goes into every tagged release +of the themes. + + +File: modus-themes.info, Node: Installation, Next: Enable and load, Prev: Overview, Up: Top + +2 Installation +************** + +The Modus themes are distributed with Emacs starting with version 28.1. +On older versions of Emacs, they can be installed using Emacs’ package +manager or manually from their code repository. There also exist +packages for distributions of GNU/Linux. + + Emacs 28 ships with ‘modus-themes’ version ‘1.6.0’. Emacs 29 +includes version ‘3.0.0’. Emacs 30 provides a newer, refactored version +that thoroughly refashions how the themes are implemented and +customized. Such major versions are not backward-compatible due to the +limited resources at the maintainer’s disposal to support multiple +versions of Emacs and of the themes across the years. + +* Menu: + +* Install manually from source:: +* Install from the archives:: +* Install on GNU/Linux:: +* Dealing with byte compilation errors:: + + +File: modus-themes.info, Node: Install manually from source, Next: Install from the archives, Up: Installation + +2.1 Install manually from source +================================ + +In the following example, we are assuming that your Emacs files are +stored in ‘~/.emacs.d’ and that you want to place the Modus themes in +‘~/.emacs.d/modus-themes’. + + 1. Get the source and store it in the desired path by running the + following in the command line shell: + + $ git clone https://gitlab.com/protesilaos/modus-themes.git ~/.emacs.d/modus-themes + + 1. Add that path to your known Elisp libraries’ list, by placing this + snippet of Emacs Lisp in your init file (e.g. ‘init.el’): + + (add-to-list 'load-path "~/.emacs.d/modus-themes") + + The themes are now ready to be used: *note Enable and load::. + + +File: modus-themes.info, Node: Install from the archives, Next: Install on GNU/Linux, Prev: Install manually from source, Up: Installation + +2.2 Install from the archives +============================= + +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 update the index, +with ‘M-x package-refresh-contents’. Then all you need to do is type +‘M-x package-install’ and specify the ‘modus-themes’. + + Once installed, the themes are ready to be used: *note Enable and +load::. + + +File: modus-themes.info, Node: Install on GNU/Linux, Next: Dealing with byte compilation errors, Prev: Install from the archives, Up: Installation + +2.3 Install on GNU/Linux +======================== + +The themes are also available from the archives of some distributions of +GNU/Linux. These should correspond to a tagged release rather than +building directly from the latest Git commit. It all depends on the +distro’s packaging policies. + +* Menu: + +* Debian 11 Bullseye:: +* GNU Guix:: + + +File: modus-themes.info, Node: Debian 11 Bullseye, Next: GNU Guix, Up: Install on GNU/Linux + +2.3.1 Debian 11 Bullseye +------------------------ + +The themes are part of Debian 11 Bullseye. Get them with: + + sudo apt install elpa-modus-themes + + They are now ready to be used: *note Enable and load::. + + NOTE that Debian’s package is severely out-of-date as of this writing +2022-07-24 09:57 +0300. + + +File: modus-themes.info, Node: GNU Guix, Prev: Debian 11 Bullseye, Up: Install on GNU/Linux + +2.3.2 GNU Guix +-------------- + +Users of Guix can get the themes with this command: + + guix package -i emacs-modus-themes + + They are now ready to be used: *note Enable and load::. + + +File: modus-themes.info, Node: Dealing with byte compilation errors, Prev: Install on GNU/Linux, Up: Installation + +2.4 Dealing with byte compilation errors +======================================== + +From time to time, we receive bug reports pertaining to errors with byte +compilation. These seldom have to do with faulty code in the themes: it +might be a shortcoming of ‘package.el’, some regression in the current +development target of Emacs, a misconfiguration in an otherwise exotic +setup, and the like. + + The common solution with a stable version of Emacs is to: + + 1. Delete the ‘modus-themes’ package. + 2. Close the current Emacs session. + 3. Install the ‘modus-themes’ again. + + For those building Emacs directly from source, the solution may +involve reverting to an earlier commit in emacs.git. + + At any rate, if you encounter such an issue please report it: we will +either fix the bug on our end if it is truly ours, or help forward it to +the relevant upstream maintainer. Whatever you do, please understand +that a build failure does not mean we are necessarily doing something +wrong. + + *note Issues you can help with::. + + +File: modus-themes.info, Node: Enable and load, Next: Customization options, Prev: Installation, Up: Top + +3 Enable and load +***************** + +NOTE that Emacs can load multiple themes, which typically produces +undesirable results and undoes the work of the designer. Use the +‘disable-theme’ command if you are trying other themes beside the Modus +collection (*note Option for disabling other themes while loading Modus: +Disable other themes.). + + Users of the built-in themes cannot ‘require’ the package as usual +because there is no package to speak of. Instead, things are simpler as +built-in themes are considered safe. All one needs is to load the theme +of their preference by adding either form to their init file: + + (load-theme 'modus-operandi) ; Light theme + (load-theme 'modus-vivendi) ; Dark theme + + Remember that the Modus themes are six themes (*note Overview::). +Adapt the above snippet accordingly. + + Users of packaged variants of the themes must add a few more lines to +ensure that everything works as intended. First, one has to require the +main library before loading one of the themes: + + (require 'modus-themes) + + One can activate a theme with something like the following +expression, replacing ‘modus-operandi’ with their preferred Modus theme: + + (load-theme 'modus-operandi :no-confirm) + + Changes to the available customization options must always be +evaluated before loading a theme (*note Customization Options: +Customization options.). Reload a theme for new changes to take effect. + + This is how a basic setup could look like (*note The require-theme +for built-in Emacs themes: The require-theme for built-in Emacs +themes.): + + ;;; For the built-in themes which cannot use `require'. + (require-theme 'modus-themes) + + ;; Add all your customizations prior to loading the themes. + (setq modus-themes-italic-constructs t + modus-themes-bold-constructs nil) + + ;; Load the theme of your choice. + (load-theme 'modus-operandi) + + ;; Optionally define a key to switch between Modus themes. Also check + ;; the user option `modus-themes-to-toggle'. + (define-key global-map (kbd "<f5>") #'modus-themes-toggle) + + + + ;;; For packaged versions which must use `require'. + + (require 'modus-themes) + + ;; Add all your customizations prior to loading the themes + (setq modus-themes-italic-constructs t + modus-themes-bold-constructs nil) + + ;; Load the theme of your choice. + (load-theme 'modus-operandi :no-confirm) + + (define-key global-map (kbd "<f5>") #'modus-themes-toggle) + + *note Sample configuration with and without use-package::. + +* Menu: + +* The require-theme for built-in Emacs themes:: +* Sample configuration with and without use-package:: +* Differences between loading and enabling:: + + +File: modus-themes.info, Node: The require-theme for built-in Emacs themes, Next: Sample configuration with and without use-package, Up: Enable and load + +3.1 The ‘require-theme’ for built-in Emacs themes +================================================= + +The version of the Modus themes that is included in Emacs CANNOT use the +standard ‘require’. This is because the built-in themes are not +included in the ‘load-path’ (not my decision). The ‘require-theme’ +function must be used in this case as a replacement. For example: + + (require-theme 'modus-themes) + + ;; All customizations here + (setq modus-themes-bold-constructs t + modus-themes-italic-constructs t) + + ;; Maybe define some palette overrides, such as by using our presets + (setq modus-themes-common-palette-overrides + modus-themes-preset-overrides-intense) + + ;; Load the theme of choice (built-in themes are always "safe" so they + ;; do not need the `no-require' argument of `load-theme'). + (load-theme 'modus-operandi) + + (define-key global-map (kbd "<f5>") #'modus-themes-toggle) + + +File: modus-themes.info, Node: Sample configuration with and without use-package, Next: Differences between loading and enabling, Prev: The require-theme for built-in Emacs themes, Up: Enable and load + +3.2 Sample configuration with and without use-package +===================================================== + +What follows is a variant of what we demonstrate in the previous section +(*note Enable and load::). + + It is common for Emacs users to rely on ‘use-package’ for declaring +package configurations in their setup. We use this as an example: + + ;;; For the built-in themes which cannot use `require'. + (use-package emacs + :config + (require-theme 'modus-themes) ; `require-theme' is ONLY for the built-in Modus themes + + ;; Add all your customizations prior to loading the themes + (setq modus-themes-italic-constructs t + modus-themes-bold-constructs nil) + + ;; Maybe define some palette overrides, such as by using our presets + (setq modus-themes-common-palette-overrides + modus-themes-preset-overrides-intense) + + ;; Load the theme of your choice. + (load-theme 'modus-operandi) + + (define-key global-map (kbd "<f5>") #'modus-themes-toggle)) + + + + ;;; For packaged versions which must use `require'. + (use-package modus-themes + :ensure t + :config + ;; Add all your customizations prior to loading the themes + (setq modus-themes-italic-constructs t + modus-themes-bold-constructs nil) + + ;; Maybe define some palette overrides, such as by using our presets + (setq modus-themes-common-palette-overrides + modus-themes-preset-overrides-intense) + + ;; Load the theme of your choice. + (load-theme 'modus-operandi) + + (define-key global-map (kbd "<f5>") #'modus-themes-toggle)) + + The same without ‘use-package’: + + (require 'modus-themes) ; OR for the built-in themes: (require-theme 'modus-themes) + + ;; Add all your customizations prior to loading the themes + (setq modus-themes-italic-constructs t + modus-themes-bold-constructs nil) + + ;; Maybe define some palette overrides, such as by using our presets + (setq modus-themes-common-palette-overrides + modus-themes-preset-overrides-intense) + + ;; Load the theme of your choice: + (load-theme 'modus-operandi :no-confirm) + + (define-key global-map (kbd "<f5>") #'modus-themes-toggle) + + *note Differences between loading and enabling::. + + Note: make sure not to customize the variable +‘custom-theme-load-path’ or ‘custom-theme-directory’ after the themes’ +package declaration. That will lead to failures in loading the files. +If either or both of those variables need to be changed, their values +should be defined before the package declaration of the themes. + + *note Make the themes look like what the maintainer uses:: + + +File: modus-themes.info, Node: Differences between loading and enabling, Prev: Sample configuration with and without use-package, Up: Enable and load + +3.3 Differences between loading and enabling +============================================ + +The reason we recommend ‘load-theme’ instead of the other option of +‘enable-theme’ is that the former does a kind of “reset” on the face +specs. It quite literally loads (or reloads) the theme. Whereas the +‘enable-theme’ function simply puts an already loaded theme to the top +of the list of enabled items, re-using whatever state was last loaded. + + As such, ‘load-theme’ reads all customizations that may happen during +any given Emacs session: even after the initial setup of a theme. +Examples are calls to ‘custom-set-faces’, as well as new values assigned +to the options the Modus themes provide (*note Customization Options: +Customization options.). + + Our tests show that ‘enable-theme’ does not read such variables anew, +so it might appear to the unsuspecting user that the themes are somehow +broken whenever they try to assign a new value to a customization option +or some face. + + This “reset” that ‘load-theme’ brings about does, however, come at +the cost of being somewhat slower than ‘enable-theme’. Users who have a +stable setup and who seldom update their variables during a given Emacs +session, are better off using something like this: + + (require 'modus-themes) + + ;; Activate your desired themes here + (load-theme 'modus-operandi t t) + (load-theme 'modus-vivendi t t) + + ;; Enable the preferred one + (enable-theme 'modus-operandi) + + *note Toggle themes without reloading them::. + + *note Sample configuration with and without use-package::. + + With the above granted, other sections of the manual discuss how to +configure custom faces, where ‘load-theme’ is expected, though +‘enable-theme’ could still apply in stable setups: + + *note Use theme colors in code with modus-themes-with-colors::. + + +File: modus-themes.info, Node: Customization options, Next: Advanced customization, Prev: Enable and load, Up: Top + +4 Customization options +*********************** + +The Modus themes are highly configurable, though they should work well +without any further tweaks. We provide a variety of user options. The +following code block provides an overview. In addition to those +variables, the themes support a comprehensive system of overrides: it +can be used to make thoroughgoing changes to the looks of the themes +(*note Option for palette overrides: Palette overrides.). We document +everything at length in the pages of this manual and also provide +ready-to-use code samples. + + Remember that all customization options must be evaluated before +loading a theme (*note Enable and load::). If the theme is already +active, it must be reloaded for changes to take effect. + + ;; In all of the following, WEIGHT is a symbol such as `semibold', + ;; `light', `bold', or anything mentioned in `modus-themes-weights'. + (setq modus-themes-italic-constructs t + modus-themes-bold-constructs nil + modus-themes-mixed-fonts t + modus-themes-variable-pitch-ui nil + modus-themes-custom-auto-reload t + modus-themes-disable-other-themes t + + ;; Options for `modus-themes-prompts' are either nil (the + ;; default), or a list of properties that may include any of those + ;; symbols: `italic', `WEIGHT' + modus-themes-prompts '(italic bold) + + ;; The `modus-themes-completions' is an alist that reads two + ;; keys: `matches', `selection'. Each accepts a nil value (or + ;; empty list) or a list of properties that can include any of + ;; the following (for WEIGHT read further below): + ;; + ;; `matches' :: `underline', `italic', `WEIGHT' + ;; `selection' :: `underline', `italic', `WEIGHT' + modus-themes-completions + '((matches . (extrabold)) + (selection . (semibold italic text-also))) + + modus-themes-org-blocks 'gray-background ; {nil,'gray-background,'tinted-background} + + ;; The `modus-themes-headings' is an alist: read the manual's + ;; node about it or its doc string. Basically, it supports + ;; per-level configurations for the optional use of + ;; `variable-pitch' typography, a height value as a multiple of + ;; the base font size (e.g. 1.5), and a `WEIGHT'. + modus-themes-headings + '((1 . (variable-pitch 1.5)) + (2 . (1.3)) + (agenda-date . (1.3)) + (agenda-structure . (variable-pitch light 1.8)) + (t . (1.1)))) + + ;; Remember that more (MUCH MORE) can be done with overrides, which we + ;; document extensively in this manual. + +* Menu: + +* Custom reload theme:: Toggle auto-reload of the theme when setting custom variables +* Disable other themes:: Determine whether loading a Modus themes disables all others +* Bold constructs:: Toggle bold constructs in code +* Italic constructs:: Toggle italic font constructs in code +* Mixed fonts:: Toggle mixing of font families +* Command prompts:: Control the style of command prompts +* Completion UIs:: Choose among several styles for completion UIs +* Org mode blocks:: Choose among plain, gray, or tinted backgrounds +* Heading styles:: Choose among several styles, also per heading level +* UI typeface:: Toggle the use of variable-pitch across the User Interface +* Palette overrides:: Refashion color values and/or semantic color mappings + + +File: modus-themes.info, Node: Custom reload theme, Next: Disable other themes, Up: Customization options + +4.1 Option for reloading the theme on custom change +=================================================== + +Brief: Toggle reloading of the active theme when an option is changed +through the Custom UI. + + Symbol: ‘modus-themes-custom-auto-reload’ (‘boolean’ type) + + Possible values: + + 1. ‘nil’ + 2. ‘t’ (default) + + All theme user options take effect when a theme is loaded. Any +subsequent changes require the theme to be reloaded. + + When this variable has a non-‘nil’ value, any change made via the +Custom UI or related functions such as ‘customize-set-variable’ and +‘setopt’ (Emacs 29), will trigger a reload automatically. + + With a ‘nil’ value, changes to user options have no further +consequences: the user must manually reload the theme (*note Enable and +load::). + + +File: modus-themes.info, Node: Disable other themes, Next: Bold constructs, Prev: Custom reload theme, Up: Customization options + +4.2 Option for disabling other themes while loading Modus +========================================================= + +Brief: Disable all other themes when loading a Modus theme. + + Symbol: ‘modus-themes-disable-other-themes’ (‘boolean’ type) + + Possible values: + + 1. ‘nil’ + 2. ‘t’ (default) + + When the value is non-‘nil’, the commands ‘modus-themes-toggle’ and +‘modus-themes-select’, as well as the ‘modus-themes-load-theme’ +function, will disable all other themes while loading the specified +Modus theme. This is done to ensure that Emacs does not blend two or +more themes: such blends lead to awkward results that undermine the work +of the designer. + + When the value is ‘nil’, the aforementioned commands and function +will only disable other themes within the Modus collection. + + This option is provided because Emacs themes are not necessarily +limited to colors/faces: they can consist of an arbitrary set of +customizations. Users who use such customization bundles must set this +variable to a ‘nil’ value. + + +File: modus-themes.info, Node: Bold constructs, Next: Italic constructs, Prev: Disable other themes, Up: Customization options + +4.3 Option for more bold constructs +=================================== + +Brief: Use bold for code syntax highlighting and related. + + Symbol: ‘modus-themes-bold-constructs’ (‘boolean’ type) + + Possible values: + + 1. ‘nil’ (default) + 2. ‘t’ + + The default is to use a bold typographic weight only when it is +required. + + With a non-‘nil’ value (‘t’) display several syntactic constructs in +bold weight. This concerns keywords and other important aspects of code +syntax. It also affects certain mode line indicators and command +prompts. + + Advanced users may also want to configure the exact attributes of the +‘bold’ face. + + *note Configure bold and italic faces::. + + +File: modus-themes.info, Node: Italic constructs, Next: Mixed fonts, Prev: Bold constructs, Up: Customization options + +4.4 Option for more italic constructs +===================================== + +Brief: Use italics for code syntax highlighting and related. + + Symbol: ‘modus-themes-italic-constructs’ (‘boolean’ type) + + Possible values: + + 1. ‘nil’ (default) + 2. ‘t’ + + The default is to not use slanted text forms (italics) unless it is +absolutely necessary. + + With a non-‘nil’ value (‘t’) choose to render more faces in italics. +This typically affects documentation strings and code comments. + + Advanced users may also want to configure the exact attributes of the +‘italic’ face. + + *note Configure bold and italic faces::. + + +File: modus-themes.info, Node: Mixed fonts, Next: Command prompts, Prev: Italic constructs, Up: Customization options + +4.5 Option for font mixing +========================== + +Brief: Toggle the use of monospaced fonts for spacing-sensitive +constructs (affects font families). + + Symbol: ‘modus-themes-mixed-fonts’ (‘boolean’ type) + + Possible values: + + 1. ‘nil’ (default) + 2. ‘t’ + + When set to non-‘nil’ (‘t’), configure some spacing-sensitive faces +like Org tables and code blocks to always inherit from the ‘fixed-pitch’ +face. This is to ensure that certain constructs like code blocks and +tables remain monospaced even when users opt for a mode that remaps +typeface families, such as the built-in ‘M-x variable-pitch-mode’. +Otherwise the layout can appear broken, due to how spacing is done. + + For a consistent experience, user may need to specify the font family +of the ‘fixed-pitch’ face. + + *note Font configurations for Org and others::. + + +File: modus-themes.info, Node: Command prompts, Next: Completion UIs, Prev: Mixed fonts, Up: Customization options + +4.6 Option for command prompt styles +==================================== + +Brief: Control the style of command prompts (e.g. minibuffer, shell, +IRC clients). + + Symbol: ‘modus-themes-prompts’ (‘choice’ type, list of properties) + + Possible values are expressed as a list of properties (default is +‘nil’ or an empty list). The list can include any of the following +symbols: + + • ‘italic’ + • ‘italic’ + • A font weight, which must be supported by the underlying typeface: + • ‘thin’ + • ‘ultralight’ + • ‘extralight’ + • ‘light’ + • ‘semilight’ + • ‘regular’ + • ‘medium’ + • ‘semibold’ + • ‘bold’ + • ‘heavy’ + • ‘extrabold’ + • ‘ultrabold’ + + The default (a ‘nil’ value or an empty list) means to only use a +subtle colored foreground color. + + The ‘italic’ property adds a slant to the font’s forms (italic or +oblique forms, depending on the typeface). + + The symbol of a font weight attribute such as ‘light’, ‘semibold’, et +cetera, adds the given weight to links. Valid symbols are defined in +the variable ‘modus-themes-weights’. The absence of a weight means that +the one of the underlying text will be used. + + Combinations of any of those properties are expressed as a list, like +in these examples: + + (bold italic) + (italic semibold) + + The order in which the properties are set is not significant. + + In user configuration files the form may look like this: + + (setq modus-themes-prompts '(extrabold italic)) + + *note Make prompts more or less colorful::. + + +File: modus-themes.info, Node: Completion UIs, Next: Org mode blocks, Prev: Command prompts, Up: Customization options + +4.7 Option for completion framework aesthetics +============================================== + +Brief: Set the overall style of completion framework interfaces. + + Symbol: ‘modus-themes-completions’ (‘alist’ type properties) + + This affects Company, Corfu, Flx, Icomplete/Fido, Ido, Ivy, +Orderless, Vertico, and the standard ‘*Completions*’ buffer. The value +is an alist of expressions, each of which takes the form of ‘(KEY . +LIST-OF-PROPERTIES)’. ‘KEY’ is a symbol, while ‘PROPERTIES’ is a list. +Here is a sample, followed by a description of the particularities: + + (setq modus-themes-completions + '((matches . (extrabold underline)) + (selection . (semibold italic)))) + + The ‘matches’ key refers to the highlighted characters that +correspond to the user’s input. When its properties are ‘nil’ or an +empty list, matching characters in the user interface will have a bold +weight and a colored foreground. The list of properties may include any +of the following symbols regardless of the order they may appear in: + + • ‘underline’ to draw a line below the characters; + + • ‘italic’ to use a slanted font (italic or oblique forms); + + • The symbol of a font weight attribute such as ‘light’, ‘semibold’, + et cetera. Valid symbols are defined in the variable + ‘modus-themes-weights’. The absence of a weight means that bold + will be used. + + The ‘selection’ key applies to the current line or currently matched +candidate, depending on the specifics of the user interface. When its +properties are ‘nil’ or an empty list, it has a subtle gray background, +a bold weight, and the base foreground value for the text. The list of +properties it accepts is as follows (order is not significant): + + • ‘underline’ to draw a line below the characters; + + • ‘italic’ to use a slanted font (italic or oblique forms); + + • The symbol of a font weight attribute such as ‘light’, ‘semibold’, + et cetera. Valid symbols are defined in the variable + ‘modus-themes-weights’. The absence of a weight means that bold + will be used. + + Apart from specifying each key separately, a catch-all list is +accepted. This is only useful when the desired aesthetic is the same +across all keys that are not explicitly referenced. For example, this: + + (setq modus-themes-completions + '((t . (extrabold underline)))) + + Is the same as: + + (setq modus-themes-completions + '((matches . (extrabold underline)) + (selection . (extrabold underline)))) + + *note Make completion matches more or less colorful::. + + +File: modus-themes.info, Node: Org mode blocks, Next: Heading styles, Prev: Completion UIs, Up: Customization options + +4.8 Option for org-mode block styles +==================================== + +Brief: Set the overall style of Org code blocks, quotes, and the like. + + Symbol: ‘modus-themes-org-blocks’ (‘choice’ type) + + Possible values: + + 1. ‘nil’ (default) + 2. ‘gray-background’ + 3. ‘tinted-background’ + + Option ‘nil’ (the default) means that the block has no background of +its own: it uses the one that applies to the rest of the buffer. In +this case, the delimiter lines have a gray color for their text, making +them look exactly like all other Org properties. + + Option ‘gray-background’ applies a subtle gray background to the +block’s contents. It also affects the begin and end lines of the block +as they get another shade of gray as their background, which +differentiates them from the contents of the block. All background +colors extend to the edge of the window, giving the area a rectangular, +“blocky” presentation. If the begin/end lines do not extend in this +way, check the value of the Org user option +‘org-fontify-whole-block-delimiter-line’. + + Option ‘tinted-background’ uses a colored background for the contents +of the block. The exact color value will depend on the programming +language and is controlled by the variable ‘org-src-block-faces’ (refer +to the theme’s source code for the current association list). For this +to take effect, the Org buffer needs to be restarted with +‘org-mode-restart’. + + Code blocks use their major mode’s fontification (syntax +highlighting) only when the variable ‘org-src-fontify-natively’ is +non-‘nil’.