Protesilaos Stavrou

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 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:

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:

New faces for already supported groups:

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:

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!

Next:
Previous:
See all: Code blog entries