Major changes to the Modus themes (modus-operandi, modus-vivendi)

[Protesilaos Stavrou <info@protesilaos.com>]

> branch: master
> commit 8fb33bae32e39f597317eb4857447bb0ea1a4de3
> Author: Protesilaos Stavrou <info@protesilaos.com>
> Commit: Basil L. Contovounesios <contovob@tcd.ie>
> 
>     Pull Modus themes version 1.2.3 from upstream
> 
> branch: master
> commit de602dd7cf76b001244964aa5bbef4d9e08ea62b
> Author: Protesilaos Stavrou <info@protesilaos.com>
> Commit: Basil L. Contovounesios <contovob@tcd.ie>
> 
>     Update Modus themes to their version 1.2.0

Hello everyone,

A few months ago the themes 'modus-operandi' and 'modus-vivendi' became
part of Emacs.  These "Modus themes" are designed to meet the highest
accessibility standard for legibility (WCAG AAA), which is quantified as
a minimum 7:1 rate of contrast in relative luminance between any given
combination of background and foreground colours.  In short: every piece
of text we support should be readable.

The version that was in Emacs until recently was 0.13.0.  In trunk we
now provide the latest release: 1.2.3.  As this is a major transition,
it is pertinent to warn existing users about some breaking yet necessary
changes, as well as inform them about the current state of affairs.


1 Customisation options
-----------------------

In the past the themes were maintained as standalone files.  This meant
that customisations were specific to each theme.  For example:

    (setq modus-operandi-bold-constructs t)
    (setq modus-operandi-slanted-constructs t)

    (setq modus-vivendi-bold-constructs t)
    (setq modus-vivendi-slanted-constructs t)

This was inconvenient for users of both items, while maintaining
separate files was becoming increasingly difficult for development.  The
new version derives the two themes from a common source and thus unifies
their customisation options.  The above variables are replaced by those:

    (setq modus-themes-bold-constructs t)
    (setq modus-themes-slanted-constructs t)

Same principle for all customisations, of which there are plenty (not
everything is a boolean).

The values that could be passed to some older variables have been
revised.  For example, changing the fringe's background intensity used
to be a boolean but now is a choice.  Please consult the themes' manual:

    (info "(modus-themes) Top")

Or go directly to:

    (info "(modus-themes) Customization Options")


2 Palette overrides
-------------------

While all customisation options are unified, there remains one
exception: the alists 'modus-themes-operandi-color-overrides' and
'modus-themes-vivendi-color-overrides'.  Those are specific to the item
they reference.

Both variables are intended for "do-it-yourself" (DIY) cases where the
user wishes to replace some colour values with their own (e.g. to change
the main background colour of 'modus-operandi' from white to a light
ochre).

Again, this topic is expanded upon in the manual and there even are
palette subsets furnished therein that retain the accessibility target,
if one does indeed wish to refashion the themes.


3 Shared functions
------------------

[ All of the following are discussed at length in the manual. ]

Users of both themes can now bind the command 'modus-themes-toggle': it
switches between the two items if either of them is active, else it
prompts with completion for one among them.

To retrieve a single value from the palette of the active Modus theme
one can use 'modus-themes-color'.  There is also a variant called
'modus-themes-color-alts'.  Consult their doc strings.

The macro 'modus-themes-with-colors' can be employed to access all of
the active theme's palette.

The function 'modus-themes-contrast' measures the relative luminance
between two colour values expressed in hexadecimal RGB notation.  It
implements the 'modus-themes-wcag-formula'.[1] Comparing two colours
returns a number which is between 1 and 21.  Our target is 7 or higher.
This is useful on its own, like this:

    (modus-themes-contrast "#ffffff" "#000000")

But also for formulas in Org tables (using 'org-mode' or 'orgtbl-mode'):

    #+begin_src emacs-lisp
    (defalias 'L 'modus-themes-contrast)
    #+end_src

    |         | #ffffff | #f0f0f0 |
    |---------+---------+---------|
    | #8f0075 |    8.66 |    7.60 |
    | #5317ac |   10.07 |    8.83 |
    | #0031a9 |   10.44 |    9.16 |
    #+TBLFM: $2='(L $1 @1$2);%0.2f :: $3='(L $1 @1$3);%0.2f

[1]: <https://www.w3.org/TR/WCAG20-TECHS/G18.html>.


4 Further reading
-----------------

The CHANGELOG of the themes is not distributed with Emacs (development
is still done externally).  Please consult the recent entries on my
website (no javascript required):

+ 1.0.0 :: <https://protesilaos.com/codelog/2020-12-05-modus-themes-1-0-0/>.
+ 1.1.0 :: <https://protesilaos.com/codelog/2021-01-24-modus-themes-1-1-0/>.
+ 1.2.0 :: <https://protesilaos.com/codelog/2021-03-04-modus-themes-1-2-0/>.

These amount to around 7500 words, describing changes that unfolded over
the course of ~400 commits.  Though the aforementioned should be enough
to get you started.


5 Packaging
-----------

Thanks to everyone who participated in bug#45068.

Thanks, in particular, to Basil L. Contovounesios who improved the new
'require-theme' function that the Modus themes rely on, as well as for
addressing some packaging-related shortcomings in my code.  Those were
necessary to make this change happen.

[ Any remaining mistakes are my own. ]

My next task is to prepare a patch for elpa.git so that it remains in
sync with emacs.git.

Thank you for your attention!
Protesilaos or "Prot"

-- 
Protesilaos Stavrou
protesilaos.com