Modus themes 1.5.0 for GNU Emacs
Just published version
1.5.0 of the Modus
themes. The detailed release
notes are reproduced below.
For any questions pertaining to this publication, feel welcome to contact me.
A patch to update the files that are shipped with Emacs28 will be sent upstream later today (I need a break after taking several hours to write this log). The modus-themes package in GNU ELPA fetches its contents from emacs.git, so expect an update shortly thereafter.
Modus themes version 1.5.0
By Protesilaos Stavrou firstname.lastname@example.org 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.
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-promptsby Philip Kaludercic in merge request 43: https://gitlab.com/protesilaos/modus-themes/-/merge_requests/43
modus-themes-mode-lineby Philip Kaludercic in merge request 40: https://gitlab.com/protesilaos/modus-themes/-/merge_requests/40.
modus-themes-lang-checkersby Philip Kaludercic in merge request 46: https://gitlab.com/protesilaos/modus-themes/-/merge_requests/46
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-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-syntaxhas 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:
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-commentsproperty can be added as well.
Consult the doc string or the manual for the technicalities and code samples.
modus-themes-hl-lineno 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)
modus-themes-paren-matchnow has styles that include an
underlineproperty. Those extend the old options, such as:
(bold intense underline)
modus-themes-headingshave an improved set of styles for the “no text color” aesthetic. Those involve the
monochromeproperty, 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
tvalue can be passed. In the previous version of the themes, it was possible to use
nilfor 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))
modus-themes-linksprovide several new possible styles, due to an expanded set of properties that includes, among others,
background. The documentation covers the details.
modus-themes-lang-checkerscan 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.
modus-themes-org-agendaprovides 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-agendasupersedes the old variable that was specific to the Org habit graph:
modus-themes-org-habit. There now is a
habitkey 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-agendaor 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-agendawith 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.
modus-themes-inhibit-reloadcontrols 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
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.
modus-themes-italic-constructsis 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.
modus-themes-scale-5is renamed to
modus-themes-scale-titleto 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
Documented how to configure the colours that are applied to the names of the days in the
M-x calendarinterface. The relevant variable is
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
Faces and face groups
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.
New faces for already supported groups:
shr-h6of 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-buttonas 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
next-errorface. 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
whitespace-lineface 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.
transient-argumentto improve its uniqueness in its context and to better comply with the expectation of hydra-style colour coding, as noted right above.
org-agenda-doneface 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-codeface, so that it is consistent with
org-verbatimas 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-pitchface, 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
[ Recall that the option
modus-themes-no-mixed-fontscan disable this feature. Also note that the
mixed-fontspackage, 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-agendavariable, 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
highlightface. 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-contextface when users assign a
bg-onlyvalue to the
modus-themes-diffsvariable. 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-promptface, though that could potentially lead to undefined faces if the comint library was not loaded. Whereas the
modus-themes-promptguarantees 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-inactiveface. It would create problems in some cases, such as in Custom buffers for multiple choice options.
calendar-weekday-headerto 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
Issue 198 on
[ Note that
modus-themes-hl-linenow accepts a list of properties as described in the opening sections of this entry. ]
Issue 218 on
Recalibrated the value of the colour
bg-hl-line-intensein 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
Introduced a new
modus-themes-facesgroup 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!