Released Modus themes 0.13.0

Just published version 0.13.0 of the Modus themes. The release notes are reproduced below. This is the largest release to date and also the first one since the themes were incorporated in upstream Emacs.

Packages may take a while to get the update, so please be patient. Contact me in case something is amiss.


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/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/modus-themes-pictures>.

6. Similarly, the change log also has its own dedicated web page:
   <https://protesilaos.com/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!