Modus themes 1.0.0 (backward-incompatible changes)
Just published version
1.0.0 of the Modus themes. The release notes
are reproduced below. Please read them carefully as there are some
breaking changes that require manual intervention in user init files.
Feel welcome to contact me if you need to.
Modus themes version 1.0.0
By Protesilaos Stavrou email@example.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
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).
The code base has been refactored. The two themes, Modus Operandi (light) and Modus Vivendi (dark), derive from the same source.
The refactoring makes it possible to distribute the two themes as part of a single package. You can find
modus-themeson MELPA, with other archives and core Emacs following suit soon thereafter (the Modus themes are built into Emacs since their version 0.12.0).
modus-vivendi-themepackages 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.
To avoid surprises, the refactored code is in the
mainbranch which becomes the default henceforth. The
masterbranch, from where all prior releases were built, is thus deprecated. Existing installs of
modus-vivendi-thememust 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.elmust make sure that they pull from the
mainbranch. This may also be the case for other such tools, though I have not had the time to test them all.
- Users of
The refactoring introduces a unified customisation framework. Now all user-facing variables are named
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
The themes now provide common user-facing functions.
modus-themes-load-vivendican 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-toggleinteractively 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-colorreturns the colour value of a symbol in the alists that hold the themes’ palettes. The alists are
modus-themes-coloralways 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-altsoccupies 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-operandiand the second is for
modus-themes-wcag-formulaimplements the WCAG formula to measure a colour value’s relative luminance. While
modus-themes-contrastapplies 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).
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-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:
- nil (default)
(supersedes options for “faint syntax” and “comments”)
- nil (default)
(supersedes options for “no underlines”)
- nil (default)
(supersedes options for “intense paren match”)
- nil (default)
modus-themes-diff has a new option to choose from:
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
(remember that the list of supported packages is already comprehensive)
Adam Spiers for bringing
macrostepto 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 calendarare 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-modenow 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-modehas 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-isearchcommand 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-posframeis more noticeable. Thanks to Pete Kazmier: https://gitlab.com/protesilaos/modus-themes/-/issues/126.
fringeface no longer returns a nil background, which allows
dap-ui-controls-modeto 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-builderare less intrusive.
All the following now inherit from basic font-lock faces and thus benefit from options such as
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-faceuses a cyan hue instead of magenta.
magit-header-line-keyuses 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-datenow respects the
modus-themes-no-mixed-fontsoption. Thanks to user “fleimgruber” for reporting the issue: https://gitlab.com/protesilaos/modus-themes/-/issues/124.
org-property-valueuses a slightly different shade of cyan.
dim-autoloadwill always look like a regular comment.
italicface 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
boldface—just apply the same idea to the
button(as with all links).
Several comment-related faces beyond the basic ones work with
modus-themes-syntaxwhen that has an effect on the colour of comments. The faces are:
transient-valueis 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:
Theme-related contributions to the wider community
log-view-commit-bodyfor 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-errorface for Emacs 28.1: https://lists.gnu.org/archive/html/bug-gnu-emacs/2020-11/msg01328.html.
org-dispatcher-highlightface 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.
The new default
mainbranch 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-syntaxcustomisation 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
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.