Tags

Modus themes version 2.1.0

By Protesilaos Stavrou <info@protesilaos.com> on 2022-02-17

The present entry records the changes made to the project since the
publication of version 2.0.0 on 2021-12-24.  There have been more than
110 commits in the meantime (and this log is close to 5000 words).

All modifications of colour combinations mentioned herein are made 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 for relative colour
luminance).  Edits also account for colour-coding that is optimised for
the needs of users with red-green colour deficiency (deuteranopia).

To access the URL of the manual visit this web page:
<https://protesilaos.com/emacs/modus-themes>.  Or read it in the Emacs
Info reader by evaluating this form:

    (info "(modus-themes) Top")

The 'modus-operandi' and 'modus-vivendi' themes are built into Emacs-28
(next stable release) or later, and are available on GNU ELPA as well as
other archives.  Emacs-28 ships version 1.6.0, while the current
'master' branch (i.e. Emacs-29) and, by extension, GNU ELPA include the
latest tagged release.

Commands
========

The following produce a buffer that previews the colour palette of the
given theme ('modus-operandi' or 'modus-vivendi').

* 'modus-themes-list-colors' prompts for a theme before producing the
  preview.

* 'modus-themes-list-colors-current' uses the current Modus theme.

These commands are useful to anyone who wants to reference a named
colour from the themes or copy a colour value, such as for the purposes
of user-level customisation (as documented at length in the manual
across several use-cases and with the inclusion of custom code).

The commands are not bound to any key.

Customisation options
=====================

* Implemented the 'modus-themes-markup' variable, which supersedes the
  now-deprecated 'modus-themes-intense-markup'.  The new user option
  accepts a list of properties (symbols).  It affects constructs such as
  Org's =verbatim=, ~code~, and {{{macro}}}.  By default, when this user
  option is either nil or an empty list, the affected constructs only
  have a foreground colour (e.g. Org verbatim is magenta).  Properties
  that change this style are:

  1. 'italic' for an added slant to the text.
  2. 'bold' for a heavier weight.
  3. 'background' to add a background colour.
  4. 'intense' to amplify the colouration (especially of 'background').

  As with all user options which accept a list of properties, the order
  of the symbols is no significant.  In user configurations it may look
  like this:

      (setq modus-themes-markup '(background intense bold))

  [ Read the manual for bold and italic fonts.  We do not hardcode a
    :weight or :slant, instead giving the user the option to set their
    own values.  The defaults are what you would normally expect from
    "bold" and "italic". ]

  Thanks to Rudolf Adamkovič for reporting some problems with the old
  design in issue 274:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/274>.

* Added the 'modus-themes-box-buttons' which affects all pseudo
  graphical buttons, such as those found in Custom UI buffers or EWW web
  pages which include search forms and the like.  The variable accepts a
  list of properties as its value.  By default (nil or empty list),
  buttons have a grey background and the familiar 3D effect.  Valid
  properties are:

  1. 'flat' to remove the 3D effect.
  2. 'accented' to shift the colouration away from grey.
  3. 'faint' to reduce the overall colouration (e.g. grey becomes white).
  4. 'variable-pitch' to apply a proportionately spaced font.
  5. 'underline' to draw a line instead of applying a 3D or flat box
     (particularly useful for those who use Emacs in a terminal emulator).
  6. The symbol of a font weight, such as 'bold', 'semibold', 'light' or
     any one among those included in the 'modus-themes-weights' constant
     (the underlying font family has to support the given weight).
  7. A number, expressed as a floating point (e.g. 0.9), which adjusts
     the height of the button’s text to that many times the base font
     size.  The default height is the same as 1.0, though it need not be
     explicitly stated.

  The order in which those symbols appear in the list is not
  significant.  If 'underline' and 'flat' are both specified, the former
  takes precedence.  In user init files the form may look like this:

    (setq modus-themes-box-buttons '(variable-pitch flat semilight 0.9))

  Thanks to Daniel Mendler for suggesting this user option and providing
  the relevant feedback in issue 282:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/282>.

* Expanded the 'modus-themes-mail-citations' with an 'intense' variant.
  For example:

      (setq modus-themes-mail-citations 'intense)

  The default is a moderately coloured style.  Other variants include
  'faint' for subtle colouration and 'monochrome' for an all-grey look.

* Reviewed the 'modus-themes-completion' option and harmonised all the
  face specifications it governs.  The variable now accepts a fourth
  stylistic variant in 'super-opinionated': it is like the 'opinionated'
  one though some details are even more pronounced.  Other noteworthy
  items:

  [ Remember to read the doc string of 'modus-themes-completions', which
    explains the grouping of the completion UIs. ]

  - The (setq modus-themes-completions 'moderate) style is more-or-less
    the same across all completion UIs.  The highlight applied to the
    current line is a bespoke shade of blue, the characters are less
    saturated than before and their hues are different, though the
    overall effect should still feel "sufficiently colourful, but not
    overdone".

  - The (setq modus-themes-completions nil) is the same as before.
    However:

      - The current line in Ivy now uses a shade of blue that is
        specific to completion UIs instead of an intense cyan
        background.  This is for theme-wide consistency.

      - Helm's current line has the same bespoke blue for its current
        line instead of another shade of blue it was using before.

  - The (setq modus-themes-completions 'opinionated) should be the same
    as before, notwithstanding the aforementioned tweaks to Ivy/Helm.

  - The (setq modus-themes-completions 'super-opinionated) for
    Icomplete, Vertico, Selectrum, Mct uses the same blue for the
    current line as is the default of Ivy and Helm.

  Miscellaneous:

  - The relevant private helper functions were rewritten.

  - We declare a few faces to help streamline certain styles.

  - Ivy action keys now inherit from 'modus-themes-key-binding'.  We
    generally try to make all keys look the same, except when that would
    be detrimental to the usability of the given context/interface.

  - Some Ivy faces are simplified or otherwise tweaked to fit in with
    the rest of the theme.

  Thanks to Rudolf Adamkovič for the feedback about Vertico in issues
  214 and 278 which prompted me to review all completion UIs:

  - <https://gitlab.com/protesilaos/modus-themes/-/issues/214>
  - <https://gitlab.com/protesilaos/modus-themes/-/issues/278>

* Adjusted the applicable hues in some 'modus-themes-syntax' variants.  In
  particular:

  - The strings' hue has more hints of blue when 'modus-themes-syntax'
    includes the 'green-strings' property.  Such as:

      (setq modus-themes-syntax '(green-strings))
      (setq modus-themes-syntax '(alt-syntax green-strings))
      (setq modus-themes-syntax '(alt-syntax green-strings faint))
      (setq modus-themes-syntax '(alt-syntax green-strings faint yellow-comments))

  - Strings are more orange/yellow than red when 'modus-themes-syntax'
    includes the 'alt-syntax' property but NOT the 'green-strings'.  For
    example:

      (setq modus-themes-syntax '(alt-syntax))
      (setq modus-themes-syntax '(alt-syntax yellow-comments))
      (setq modus-themes-syntax '(alt-syntax yellow-comments faint))

  - Backslashes for regexp constructs are coloured appropriately to look
    distinct from the rest of the string and from the escaped construct in
    all cases.

* Removed background colours from the the default style of Org block
  delimiters.

  As I explained in Emacs bug#52587,[1] Org has code that overrides
  themes which prefer not to extend the block delimiter faces to the
  edge of the window (as we would like to do by default).  This
  practically means that we cannot have backgrounds for those lines and
  keep them limited to the stretch of area covered by their text.

  As such, the default for Org block delimiter lines now is a gray
  foreground with no distinct background colour.  The user option
  'modus-themes-org-blocks' provides "blocky" alternatives that use
  background colours---those extend to the edge of the window.

  [1] <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=52587#46>

* Deleted the compatibility layer for all user options that used to
  accept symbols in the past but now expect a list of symbols.  The
  manual contains a snippet with all customisation options for those who
  do not want to read all the relevant doc strings.  Evaluate this:

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

  Or visit: <https://protesilaos.com/emacs/modus-themes#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f>.

  The original plan was to remove those during the transition to version
  2.0.0 (about a month ago) though I changed my mind thinking they would
  not pose a longer-term problem.

  New information by Mark Bestley in issue 272 shows that this kind of
  complexity can lead to errors:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/272#note_826725412>.

  So it is better to keep things simple and ask users to configure all
  user options based on the up-to-date documentation.

  Also thanks to Saša Janiška for the feedback in issue 272.

New packages, faces, or face groups
===================================

* all-the-icons-dired.

* all-the-icons-ibuffer.

* 'child-frame-border' face (Emacs 28).

* 'citar' package.  Thanks to Rudolf Adamkovič for the feedback in issue
  280: <https://gitlab.com/protesilaos/modus-themes/-/issues/280>.

* 'elisp-shorthand-font-lock-face' (Emacs 29).  Read the manual by
  evaluating:

      (info "(elisp) Shorthands")

* 'ement' (ement.el) Matrix client, though it is not listed in any
  archive yet: <https://github.com/alphapapa/ement.el>.

  Thanks to Samuel Culpepper for the feedback in issue 279:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/279>.

  Also check the Ement issue tracker on the matter:
  <https://github.com/alphapapa/ement.el/issues/53>.

* 'mct' package.

* 'menu' face (built-in) which is used in the menu-bar when Emacs runs
  without a graphical toolkit.

* 'pgtk-im-0' face (Emacs 29).  This is shown as a single-character-long
  block when you type the Compose key followed by the composable
  characters.

* 'pyim' (an input method for CJK characters).  Thanks to Yuanchen Xie for
  the contribution in merge request 57:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/57>.
  The patch is small and is thus excluded from the requirement for
  copyright assignment to the FSF (remember that the themes are built
  into Emacs and any major contribution needs such copyright
  assignment---read the relevant entry in the themes' manual).

* 'slime' and 'sly' packages.  Thanks to John Haman for the feedback
  which was done via email due to some problems with the web UI on
  GitLab (this information is shared with permission).  Please note that
  I am not familiar with Common Lisp and could not test these
  thoroughly.  Any mistakes or omissions are my own.

  Concerning the web UI, there is a fully functional mirror of the
  themes on GitHub, while email is always an option.  Use whatever works
  for you to report an issue or send a patch.

* 'textsec' package (Emacs 29).

New indirectly supported packages
---------------------------------

These inherit from base faces and look good enough already or use
appropriate colours from the Modus themes:

* dtache
* org-remark

Changes to supported faces or face groups
=========================================

* Stopped making key bindings look like boxes.  We revert to the old
  style we were using before the introduction of the 'help-key-binding'
  face (Emacs 28).

  By default Emacs 28 or higher will render all key bindings it
  identifies with a box around them.  The idea is to make them look like
  keys on a keyboard, which I never really liked because without
  generous padding you get a very tight space between the character and
  the box's borders which can look weird at small point sizes (Emacs
  faces do not have padding in the same way CSS does).

  I tried following the default style for a few months and have concluded
  that it is not good enough for our purposes (my preferences
  notwithstanding):

  - The box attribute does not work in terminal emulators.  This means
    that keys only get a subtle grey background and the default
    foreground, which can be hard to make them stand out from their
    surrounding text if the font height is small and/or the keybinding is
    short (e.g. a single character).

  - The box and grey background combination limits our options when we
    need to colour-code different types of keys.  For example, the
    'which-key' package can show TAB as T and applies to it a different
    face to make the distinction obvious.  In that case, the presence of
    the tight box makes the use of a bold weight inappropriate: the
    character and the box's borders seem to overlap.  While the grey
    background limits our choice of colour as, for instance, yellow
    never looks good against it.  Same principle for interfaces that can
    have colour-coded keys like 'transient' and 'hydra', where we lose
    much-needed flexibility.

* Adjusted the brightness of the 'which-key-special-key-face'.  This is
  the face that applies to special keys.  For example:

      (setq which-key-special-keys '("SPC" "TAB" "RET" "ESC" "DEL"))

* Made 'transient' faces which are supposed to be de-emphasise certain
  elements inherit the 'shadow' face.  This is an implicit customisation
  option, as it allows the user to adjust the foreground value of all
  "less important" constructs simply by changing the 'shadow' face.

* Covered the 'transient-purple' face (these are like the colour-coding
  of 'hydra').

* Tweaked the 'transient-argument' and 'transient-value' faces to make
  things look a bit more consistent with the other transient faces.
  This is to avoid potential conflicts with the highlighted key
  bindings, especially when transient uses hydra-style colour-coded
  keys.

* Applied the same metaphors for key bindings to 'marginalia-key'
  ('marginalia' package) and 'embark-keybinding' ('embark' package).
  They inherit the 'modus-themes-key-binding' when possible.  The only
  exception is with (setq modus-themes-completions nil) where conflicts
  may arise between the key's style and matching characters of the
  ongoing completion session.

  Thanks to Rudolf Adamkovič for pointing out the inconsistency in issue
  278: <https://gitlab.com/protesilaos/modus-themes/-/issues/278>.

* Refrained from treating LaTeX sections as headings.  This is because
  unlike Org/Outline/Markdown Latex is basically source code, so the
  sectioning does not work the same way it does for those lightweight
  markup/outlining modes.

  Furthermore, font-latex.el defines 'font-latex-fontify-sectioning'
  which can be used to control the scale of those sections.  It makes
  sense for the themes to not interfere with that design and just allow
  users to customise things uniformly regardless of the active theme.

  Thanks to Gustavo Barros for the detailed feedback in issue 265:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/265>.

* Reviewed the hues of 'all-the-icons' and related packages.

* Applied the correct style to 'info-menu-header', meaning that it now
  only uses a bold weight as it is not a real heading, instead of being
  affected by the user option 'modus-themes-headings'.

* Included new 'telega-entity-type-spoiler' face.  Thanks to bit9tream
  for informing me about it in issue 271:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/271>.  The
  conclusion:

      Tricky though perhaps dull

      I understand this is not an interesting topic and it probably is
      too difficult to relate to the various data points without
      visualising them and comparing the before and after
      states. Furthermore, data can be deceptive and I have always
      maintained that theme development stands at the intersection of
      science and art (at least for the purposes of conforming with the
      rigorous accessibility standards of the Modus themes).

      That granted, I wanted to shed light on the “behind the scenes”
      work that is not immediately obvious when one checks a diff that
      introduces some seemingly trivial tweaks like '#49d239'->'#49c029'
      or '#7fcfff'->'#8fbfff'.

* Tweaked the hues of all graph colours, which are used in the
  'org-habit' table.  The changes are subtle and should improve the
  overall usability of the graph.  For the technicalities, read:
  <https://protesilaos.com/codelog/2022-01-02-review-modus-themes-org-habit-colours/>.

  Also thanks to Rudolf Adamkovič for reporting the problem with white
  text on yellow background in issue 270:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/270>.

* Styled the 'markdown-highlighting-face'.  This is the face used for
  text in between double equals signs when the user option
  'markdown-enable-highlighting-syntax' is non-nil.

* Amplified the overall colouration of Eldoc's current argument.  It is
  a yellow foreground with a tinted background.  The blue foreground
  which was applied before could be hard to tell apart in some cases,
  especially because it is a common colour that is used elsewhere in the
  themes.  Whereas the warmer hues are easier to discern, especially
  while relying only on peripheral vision.

  Thanks to Rudolf Adamkovič for the feedback in issue 275:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/275>.

* Instructed Geiser to use the same style for its argument as Eldoc
  (edited the faces 'geiser-font-lock-autodoc-current-arg' and
  'geiser-font-lock-autodoc-identifier').

* Made the 'keycast-key' face work when 'modus-themes-mode-line' has a
  padding value (read the latter doc string or consult the manual).

* Refined the 'magit' faces for bisect, reflog, sequence, and signature
  views.  They get a bold weight and, where appropriate, are made to
  comply with the 'modus-theems-deueteranopia' option (meaning that
  greens turn into blues).

* Recoloured 'elfeed' tags from a shade of cyan to magenta, in the
  interest of theme-wide consistency but also to make them easier to
  tell apart from the name of the feed.  Also updated the faces used in
  the header-line to look better in context.

* Removed the hardcoded ':slant italic' from the 'italic' face, which is
  consistent with how we do not hardcode ':weight bold' in the 'bold'
  face.

  Such a design allows users to configure those faces and have the
  desired slant/weight (and even font family) apply consistently
  throughout the theme.  Read the manual for further details:
  <https://protesilaos.com/emacs/modus-themes#h:2793a224-2109-4f61-a106-721c57c01375>.

  Thanks to user derek-upham for pointing out the inconsistency in issue
  21 over at the GitHub mirror:
  <https://github.com/protesilaos/modus-themes/issues/21>.

* Improved the styles that apply to compilation buffers and related.
  The overarching intent was to reduce the excess colouration, without
  upsetting expectations and affecting the overall presentation.

  Thanks to Rudolf Adamkovič for the feedback in issue 277:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/277>.

  Note that compilation buffers apply an underline by default.  The
  manual explains how to change that:
  <https://protesilaos.com/emacs/modus-themes#h:420f5a33-c7a9-4112-9b04-eaf2cbad96bd>.

* Ensured a consistent style for the 'highlight' face across all
  contexts (typically used for mouse hover effects).  The mode line has
  an exception when its style includes an accented background (per
  'modus-themes-mode-line').

  Thanks to Rudolf Adamkovič for the feedback in issue 214:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/214>.

* Changed the foreground of 'mode-line-emphasis' from blue to purple, in
  order to avoid potential (albeit unlikely) confusion with other
  indicators.

* Desaturated the 'man' and 'woman' foreground value of the bold
  constructs and tweaked other faces to avoid potential inconsistencies.
  Thanks to Daniel Mendler for the feedback:
  <https://gitlab.com/protesilaos/modus-themes/-/commit/8080eb1c6c0020ba82e8abaa933d6686327bc616#note_841424489>.

* Removed certain exaggerations from widgets as seen in the Custom UI
  and EWW.  Specifically:

  - 'widget-field' does not need to ':extend', as that typically does
    not look good.

  - 'custom-state' gets a warmer colour to convey its message more
    effectively.

  - 'eww-form-text' no longer uses a ':box' because that breaks when the
    widget occupies more than one line.

  - 'eww-form-textarea' can now inherit from 'eww-form-text'.

  Thanks to Daniel Mendler for the feedback on the style of those faces in
  issue 284: <https://gitlab.com/protesilaos/modus-themes/-/issues/284>.

The manual
==========

* Clarified the wording of 'shr' fonts, which affect 'eww', 'elfeed',
  'ement', and possibly others.

* Wrote section on custom Org emphasis faces.  It includes code samples.

* Answered a Frequently Asked Question on whether the Modus themes are
  "colour schemes"---they are not and it is important to understand why.

* Addressed another Frequently Asked Question about porting the themes
  to other platforms or editors.  Relevant blog posts which explain how
  complex the issue is and why porting requires the same attention to
  detail as this project:

  - <https://protesilaos.com/codelog/2022-01-03-modus-themes-port-faq/>.
  - <https://protesilaos.com/codelog/2022-01-23-base16-modus-themes/>.

* Improved the sample code in the section about the backdrop of PDF
  files while using 'pdf-tools'.  Thanks to Utkarsh Singh for the patch,
  which was sent via email.

* Provided sample code on an alternative style for Ediff.

  There was a discussion with Philip Kaludercic in issue 273 about making
  this a defcustom: <https://gitlab.com/protesilaos/modus-themes/-/issues/273>.

  I first entertained the notion and did set up a branch for testing
  purposes.  However, I ultimately decided that such a course of action
  would establish a bad precedent because then every conceivable stylistic
  tweak could, in principle, become a user option.  Furthermore, the
  potential defcustom would introduce too much complexity as Ediff would
  have to continue to behave as other diffs (per 'modus-themes-diffs') if
  the user did not want the alternative style.

  As such, documenting how a user can achieve this is the right choice.

* Fixed internal link in the manual.  Thanks to Rudolf Adamkovič for
  reporting the problem in issue 277:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/277>.

Miscellaneous
=============

* Covered workaround for improving the accuracy of colour reproduction
  in terminal emulators.  The results are still not as good as the
  graphical version of Emacs, though they are considerably better than
  before.  Thanks to gitrj95's issue 18 at the GitHub mirror, which
  prompted me to research this topic:
  <https://github.com/protesilaos/modus-themes/issues/18>.

* Helped report a bug in the PGTK build of Emacs where a new emacsclient
  window with the 'modus-vivendi' face would not show the cursor:
  <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=53073>.  Thanks to
  contributed to the discussion on issue 7 over at the GitHub mirror:
  <https://github.com/protesilaos/modus-themes/issues/7>

* Shifted the hue of the intense 'hl-line' from a grey-cyan to a more
  vivid blue by reducing the relative contribution of the green channel
  of light.

  The change affects these styles:

      (setq modus-themes-hl-line '(accented intense))
      (setq modus-themes-hl-line '(accented intense underline))

  Thanks to Rudolf Adamkovič for suggesting a more vivid colour in issue
  214: <https://gitlab.com/protesilaos/modus-themes/-/issues/214>.

* Recalibrated the 'modus-vivendi' named colour 'bg-paren-match'.

  I wanted to increase its distance relative to the main background,
  just to be sure that it is easier to spot.  This is achieved by moving
  the hueness from the yellow to the magenta side of the spectrum.

  Overall, the change is subtle and has no major impact on the contrast
  ratio relative to the main background and foreground (we need to
  consider both due to the specifics of show-paren-mode (and related)).

  The results (#5f362f is the old, #6f3355 the new):

      |         | #000000 | #ffffff | #000000 | #ffffff |
      |---------+---------+---------+---------+---------|
      | #5f362f |    2.06 |   10.22 |   37904 |  333060 |
      | #6f3355 |    2.28 |    9.21 |   58282 |  291037 |

  The TBLFM formula for this table (org-mode notation):

      $2='(Λ $1 @1$2);%.2f :: $3='(Λ $1 @1$3);%.2f :: $4='(Δ $1 @1$4) :: $5='(Δ $1 @1$5)

  The Greek letters mean:

      (defalias 'Λ #'modus-themes-contrast)
      (defalias 'Δ #'color-distance)

* Expanded the "special" subset of the palette with faint variants of
  the four backgrounds.  These are reserved for special circumstances,
  as the name implies.  Below are the contrast values (see
  'modus-themes-contrast').

      Modus Operandi main accept colours against faint special backgrounds:

      |         | #f0f1ff | #ebf5eb | #fef2ea | #faeff9 |
      |---------+---------+---------+---------+---------|
      | #a60000 |    7.15 |    7.17 |    7.29 |    7.16 |
      | #972500 |    7.26 |    7.28 |    7.40 |    7.28 |
      | #a0132f |    7.13 |    7.15 |    7.27 |    7.14 |
      | #7f1010 |    9.44 |    9.47 |    9.63 |    9.47 |
      | #702f00 |    8.94 |    8.97 |    9.12 |    8.96 |
      | #7f002f |    9.64 |    9.67 |    9.83 |    9.66 |
      | #005e00 |    7.20 |    7.23 |    7.34 |    7.22 |
      | #315b00 |    7.13 |    7.15 |    7.27 |    7.15 |
      | #145c33 |    7.18 |    7.20 |    7.32 |    7.20 |
      | #104410 |   10.09 |   10.12 |   10.29 |   10.12 |
      | #30440f |    9.56 |    9.59 |    9.75 |    9.58 |
      | #0f443f |    9.76 |    9.79 |    9.96 |    9.79 |
      | #813e00 |    7.14 |    7.17 |    7.28 |    7.16 |
      | #70480f |    7.14 |    7.17 |    7.28 |    7.16 |
      | #863927 |    7.13 |    7.15 |    7.27 |    7.15 |
      | #5f4400 |    8.10 |    8.12 |    8.26 |    8.12 |
      | #5d5000 |    7.17 |    7.19 |    7.31 |    7.19 |
      | #5e3a20 |    8.91 |    8.94 |    9.09 |    8.93 |
      | #0031a9 |    9.31 |    9.34 |    9.49 |    9.33 |
      | #2544bb |    7.14 |    7.16 |    7.28 |    7.16 |
      | #0000c0 |   10.64 |   10.67 |   10.85 |   10.66 |
      | #003497 |    9.66 |    9.70 |    9.86 |    9.69 |
      | #0f3d8c |    9.06 |    9.09 |    9.24 |    9.09 |
      | #001087 |   13.15 |   13.20 |   13.42 |   13.19 |
      | #721045 |    9.99 |   10.02 |   10.19 |   10.01 |
      | #8f0075 |    7.72 |    7.75 |    7.88 |    7.74 |
      | #5317ac |    8.98 |    9.01 |    9.16 |    9.00 |
      | #752f50 |    8.22 |    8.25 |    8.38 |    8.24 |
      | #7b206f |    8.22 |    8.25 |    8.38 |    8.24 |
      | #55348e |    8.26 |    8.29 |    8.42 |    8.28 |
      | #00538b |    7.18 |    7.20 |    7.32 |    7.19 |
      | #30517f |    7.18 |    7.20 |    7.32 |    7.20 |
      | #005a5f |    7.13 |    7.15 |    7.27 |    7.15 |
      | #005077 |    7.76 |    7.79 |    7.91 |    7.78 |
      | #354f6f |    7.49 |    7.52 |    7.64 |    7.51 |
      | #125458 |    7.69 |    7.72 |    7.85 |    7.71 |

      Modus Vivendi main accept colours against faint special backgrounds:

      |         | #0e183a | #001f1a | #241613 | #251232 |
      |---------+---------+---------+---------+---------|
      | #ff8059 |    7.01 |    7.01 |    7.07 |    7.00 |
      | #ef8b50 |    7.01 |    7.00 |    7.07 |    7.00 |
      | #ff9077 |    7.85 |    7.85 |    7.93 |    7.85 |
      | #ffa0a0 |    8.91 |    8.91 |    9.00 |    8.91 |
      | #f5aa80 |    9.04 |    9.04 |    9.13 |    9.04 |
      | #ff9fbf |    9.06 |    9.05 |    9.14 |    9.05 |
      | #44bc44 |    7.04 |    7.04 |    7.11 |    7.04 |
      | #70b900 |    7.13 |    7.13 |    7.20 |    7.12 |
      | #00c06f |    7.24 |    7.24 |    7.31 |    7.24 |
      | #78bf78 |    7.87 |    7.86 |    7.94 |    7.86 |
      | #99b56f |    7.60 |    7.59 |    7.67 |    7.59 |
      | #88bf99 |    8.23 |    8.22 |    8.30 |    8.22 |
      | #d0bc00 |    8.98 |    8.98 |    9.07 |    8.98 |
      | #c0c530 |    9.31 |    9.31 |    9.40 |    9.30 |
      | #d3b55f |    8.71 |    8.71 |    8.79 |    8.71 |
      | #d2b580 |    8.81 |    8.80 |    8.89 |    8.80 |
      | #cabf77 |    9.28 |    9.27 |    9.36 |    9.27 |
      | #d0ba95 |    9.20 |    9.20 |    9.29 |    9.20 |
      | #2fafff |    7.18 |    7.18 |    7.25 |    7.18 |
      | #79a8ff |    7.32 |    7.32 |    7.39 |    7.31 |
      | #00bcff |    7.96 |    7.96 |    8.04 |    7.96 |
      | #82b0ec |    7.74 |    7.74 |    7.81 |    7.74 |
      | #a0acef |    7.97 |    7.96 |    8.04 |    7.96 |
      | #80b2f0 |    7.89 |    7.88 |    7.96 |    7.88 |
      | #feacd0 |    9.94 |    9.93 |   10.03 |    9.93 |
      | #f78fe7 |    8.29 |    8.29 |    8.37 |    8.29 |
      | #b6a0ff |    7.82 |    7.81 |    7.89 |    7.81 |
      | #e0b2d6 |    9.51 |    9.50 |    9.60 |    9.50 |
      | #ef9fe4 |    8.88 |    8.88 |    8.96 |    8.87 |
      | #cfa6ff |    8.72 |    8.71 |    8.80 |    8.71 |
      | #00d3d0 |    9.28 |    9.27 |    9.36 |    9.27 |
      | #4ae2f0 |   11.09 |   11.09 |   11.20 |   11.09 |
      | #6ae4b9 |   11.08 |   11.07 |   11.18 |   11.07 |
      | #90c4ed |    9.34 |    9.34 |    9.43 |    9.33 |
      | #a0bfdf |    9.10 |    9.09 |    9.18 |    9.09 |
      | #a4d0bb |   10.18 |   10.17 |   10.27 |   10.17 |

* Add docs on color overrides through blending.  Thanks to Alex Griffin
  for the contribution in issue 269 and the subsequent patch in merge
  request 56 (the patch is exempt from copyright assignment):

  - <https://gitlab.com/protesilaos/modus-themes/-/issues/269>.
  - <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/56>.

* Fixed typo in the ':group' value of some faces defined in
  modus-themes.el.  Thanks to Gustavo Barros for reporting it in issue
  266: <https://gitlab.com/protesilaos/modus-themes/-/issues/266>

* Updated copyright statement in all .el files to use the same wording
  as all other files that are built into Emacs.

* Made all sorts of tweaks and refinements to doc strings and nodes in the
  manual.

Thanks again to everyone involved!  This has been yet another cycle of
intense work which further iterated on an already solid base.

Modus themes version 2.0.0

By Protesilaos Stavrou <info@protesilaos.com> on 2021-12-24

This entry covers the changes made to the project since the publication
of version 1.7.0 on 2021-11-18.  There have been more than 90 commits in
the meantime.  This is a major upgrade with some backward-incompatible
changes, even though most work was done behind the scenes (i.e. not in
git commits but local testing) to guarantee the relevance of all
user-facing styles, code practices, et cetera.

All modifications of colour combinations mentioned herein are made 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 for relative colour
luminance).  Edits also account for colour-coding that is optimised for
the needs of users with red-green colour deficiency (deuteranopia).

To access the URL of the manual visit this web page:
<https://protesilaos.com/emacs/modus-themes>.  Or read it in the Emacs
Info reader by evaluating this form:

    (info "(modus-themes) Top")

The 'modus-operandi' and 'modus-vivendi' themes are built into Emacs-28
(next stable release) or later, and are available on GNU ELPA as well as
other archives.  Emacs-28 ships version 1.6.0, while the current
'master' branch (i.e. Emacs-29) and, by extension, GNU ELPA include the
latest tagged release.

A fully fledged org-mode file with the annotated task list for Modus
themes version 2.0.0 is supplied as complementary material to the
present entry.  It should be annexed below this text on the announcement
page: <https://protesilaos.com/codelog/2021-12-24-modus-themes-2-0-0/>.

Customisation options
=====================

There are some breaking changes that were necessary to improve the code
base and make things easier as well as more efficient for end users.
Please read carefully and apologies in advance for whatever
inconvenience.

* The 'modus-themes-variable-pitch-headings' no longer has any effect.
  Instead, users can specify a 'variable-pitch' property to the list
  they pass to the 'modus-themes-headings' or 'modus-themes-org-agenda'
  (examples below).

* All 'modus-themes-scale-*' options are removed.  Scaling of headings
  is now handled directly by the user options 'modus-themes-headings'
  and 'modus-themes-org-agenda' (code samples below).

* The 'modus-themes-headings' option now accepts a floating point (see
  function 'floatp') that represents the multiplier relative to the base
  font size.  This can be used to scale headings accordingly.  Since
  this option can target individual heading levels (for 1 through 8),
  users can now implement their desired scale with greater precision.
  Whereas before it was limited to the first four levels, admittedly for
  no good reason.

  The newly introduced 'variable-pitch' property can also be applied on
  a per-level basis (making it easy to combine with existing properties,
  such as a custom weight, for maximum control).  Example:

      ;; This is an alist: read the manual or its doc string.
      (setq modus-themes-headings
            '((1 . (variable-pitch light 1.6))
              (2 . (overline semibold 1.4))
              (3 . (monochrome overline 1.2))
              (4 . (overline 1.1))
              (t . (rainbow 1.05))))

* The 'modus-themes-org-agenda' follows the same design as the
  'modus-themes-headings' where appropriate.  Headings that can be
  scaled accept a floating point, while those that may be rendered in a
  proportionately spaced font accept the 'variable-pitch' property.  In
  addition, a custom font weight is also supported in the relevant
  places (just as with 'modus-themes-headings').  Overall, the interface
  can now be tailored to the user's preferences with greater precision.

      ;; This is an alist: read the manual or its doc string.
      (setq modus-themes-org-agenda
            '((header-block . (variable-pitch light 1.6))
              (header-date . (bold-today grayscale underline-today 1.2))
              (event . (accented varied))
              (scheduled . uniform)
              (habit . traffic-light)))

* The 'modus-themes-scale-small' that was used in the Org agenda
  interface has been removed.  No replacement is provided, as the
  downsizing had the undesired effect of breaking the otherwise neat
  alignment of elements on the grid.

* The 'modus-themes-mode-line-padding' option has been removed.
  Instead, users can specify a natural number (positive integer)
  directly in the list of properties passed to the
  'modus-themes-mode-line' variable.  This has no effect when the
  'moody' property is also set, because the Moody library applies its
  own padding.  For example:

      (setq modus-themes-mode-line '(borderless accented 4))

  Though not related to changes on our end, users of Emacs 29 must now
  set 'x-use-underline-position-properties' to nil for padding to work
  properly (due to other adjustments upstream).  This relates to Emacs
  bug#52324 we had reported:
  <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=52324>.

* All deuteranopia styles are consolidated in a single toggle:
  'modus-themes-deuteranopia'.  The 'modus-themes-success-deuteranopia'
  is thus rendered obsolete and superseded, while the individual
  deuteranopia-friendly styles for diffs ('modus-themes-diffs') and the
  Org agenda's habit graph ('modus-themes-org-agenda') are altogether
  removed.  As opposed to top-level forms, there is no clean way to
  notify the user of the deprecation of individual values of a user
  option.

* The "foreground only" style has been altogether removed from the user
  option 'modus-themes-diffs'.  It never was up to the aesthetic
  standard of the themes even though the colours met the minimum 7:1
  contrast ratio.  There is a new section in the manual which documents
  how to implement such a style with user-level configurations.  Short
  version:

      (defun my-modus-themes-custom-faces ()
        (modus-themes-with-colors
          (custom-set-faces
           `(modus-themes-diff-added ((,class :background unspecified :foreground ,green))) ; OR ,blue for deuteranopia
           `(modus-themes-diff-changed ((,class :background unspecified :foreground ,yellow)))
           `(modus-themes-diff-removed ((,class :background unspecified :foreground ,red)))

           `(modus-themes-diff-refine-added ((,class :background ,bg-diff-added :foreground ,fg-diff-added)))
           ;; `(modus-themes-diff-refine-added ((,class :background ,bg-diff-added-deuteran :foreground ,fg-diff-added-deuteran)))
           `(modus-themes-diff-refine-changed ((,class :background ,bg-diff-changed :foreground ,fg-diff-changed)))
           `(modus-themes-diff-refine-removed ((,class :background ,bg-diff-removed :foreground ,fg-diff-removed)))

           `(modus-themes-diff-focus-added ((,class :background ,bg-dim :foreground ,green))) ; OR ,blue for deuteranopia
           `(modus-themes-diff-focus-changed ((,class :background ,bg-dim :foreground ,yellow)))
           `(modus-themes-diff-focus-removed ((,class :background ,bg-dim :foreground ,red)))

           `(modus-themes-diff-heading ((,class :background ,bg-alt :foreground ,fg-main)))

           `(diff-indicator-added ((,class :foreground ,green))) ; OR ,blue for deuteranopia
           `(diff-indicator-changed ((,class :foreground ,yellow)))
           `(diff-indicator-removed ((,class :foreground ,red)))

           `(magit-diff-added ((,class :background unspecified :foreground ,green-faint)))
           `(magit-diff-changed ((,class :background unspecified :foreground ,yellow-faint)))
           `(magit-diff-removed ((,class :background unspecified :foreground ,red-faint)))
           `(magit-diff-context-highlight ((,class :background ,bg-dim :foreground ,fg-dim))))))

      ;; This is so that the changes persist when switching between
      ;; modus-operandi and modus-vivendi
      (add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces)

Removed support for packages
============================

The following are no longer supported by the themes.  The reasons vary
in each case, though they boil down to (i) the package being obsoleted,
or (ii) the package's faces inheriting from base faces that we already
support (e.g. font-lock).  Each case was carefully considered as part of
the comprehensive review of all packages supported by the themes, though
chances are that some mistake was made regardless.  If you believe a
package should not have been removed, please report as much.

* ag
* apt-sources-list
* apt-sources-list
* buffer-expose
* counsel-org-capture-string
* define-word
* diredc
* disk-usage
* easy-kill
* flyspell-correct
* git-gutter{,fringe}+
* git-lens
* git-walktree
* highlight-blocks
* highlight-defined
* highlight-escape-sequences
* highlight-symbol
* highlight-tail
* hyperlist-mode
* isl (isearch-light)
* minibuffer-line
* mu4e-conversation
* no-emoji
* objed
* parrot
* phi-search
* pkgbuild-mode
* rainbow-identifiers
* sallet
* spell-fu
* spray
* swoop
* vdiff
* volatile-highlights

Changes to supported faces or face groups
=========================================

* Eliminated any possible exaggerations in wgrep faces.  Those no longer
  use coloured backgrounds.  Instead they have colour-coded foreground
  colours as well as a bold weight (they ultimately inherit from the
  'bold' face, which is a "hidden" customisation option, as explained in
  the manual).

* Forced Org block delimiters to not extend their background by default
  (though check 'modus-themes-org-blocks').  That was the intended
  design all along, but now it needs to be made explicit.  See, for
  example, bug#52587 for Emacs:
  <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=52587>

* Revised the 'org-sexp-date' face so that it no longer looks like
  'org-date'.  Dates are clickable buttons: they work like links, so
  they have an underline by default and are subject to the
  'modus-themes-links' user option.  Whereas the 'org-sexp-date' is not
  applied to interactive elements and must thus be visually distinct.

  This face is used for diary-style entries in Org files.  For example:

      %%(diary-anniversary 2000 12 25) NAME %d%s birthday

* Rewrote several Auctex/Tex faces to inherit from base faces where
  relevant (e.g. 'bold', 'success') as well as from font-lock faces.  In
  the latter case, the end-result makes Auctex/Tex subject to the
  'modus-themes-syntax' option.  These refinements promote theme-wide
  consistency without detracting from the established styles.

* Improved Git (Magit) commit faces for warnings or errors.  This
  concerns two cases:

  1. The summary line exceeds the recommended limit of 50 characters.
     This now uses a yellow foreground colour which contrasts well with
     the summary line's new blue hue (blue and yellow are complementary
     for our purposes, meaning that they have good contrast in hueness).

  2. The second line (the one right below the summary) has text that
     should not be there.  This one is coloured in a shade of red, which
     again contrasts well with blue.

  Thanks to Damien Cassou for noticing in issue 261 that the previous
  style of applying tinted backgrounds did not work well when
  'hl-line-mode' was enabled ('hl-line-mode' overrides backgrounds and
  so the warnings/errors where not always obvious):
  <https://gitlab.com/protesilaos/modus-themes/-/issues/261>.

* Added support for the new 'magit-branch-warning' face that we helped
  upstream define: <https://github.com/magit/magit/issues/4550>.  It
  disambiguates warnings in Magit status buffers from the generic and
  often inappropriate for such a context 'font-lock-warning-face'.

* Simplified all the Apropos faces.  They no longer look like buttons or
  links as that makes the presentation of 'M-x apropos' very busy.
  Instead, they now only have a foreground colour.

* Updated support for org-roam faces by removing old entries and
  covering new ones.

* Replaced old company-mode faces with their new aliases:

  - company-scrollbar-bg => company-tooltip-scrollbar-thumb
  - company-scrollbar-fg => company-tooltip-scrollbar-track

* Made 'org-column-title' inherit from 'fixed-pitch' when the user
  option 'modus-themes-mixed-fonts' is non-nil.  This is needed to line
  up columns correctly.  Thanks to Björn Lindström for the contribution
  in merge request 52:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/52>.

* Forced the 'org-colview' faces to use the same height, even when
  headings are scaled (see 'modus-themes-headings').  This ensures that
  the columns are aligned properly and text fits on the same row.
  Thanks to Björn Lindström for the contribution in merge request 53:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/53>.

* Refrained from applying a bold weight to the Org date selection
  indicator in the calendar. The use of bold has the potential to create
  problems with the alignment of dates for certain typefaces that do not
  have a proper bold variant.  Also, there is no need for added emphasis
  given that we already use a prominent background colour.

* Made 'M-x org-table-header-line-mode' or the third-party package
  'org-table-sticky-header' use colours that fit better with those of
  tables.

* Removed explicit styling of the 'magit-branch-current' face because
  its definition checks if the ':box' attribute can be set and if not, it
  uses ':inverse-video'.  Useful for terminal emulators.

* Expanded support for the 'mode-line-active' face for Emacs29.  The
  face upstream basically adds proportionately spaced fonts (the
  'variable-pitch' face) to the mode line.  The themes can already use
  that if the user option 'modus-themes-variable-pitch-ui' is non-nil.
  Thanks to Manuel Uberti for the feedback in issue 257:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/257>.

* Implemented some stylistic refinements for ERC and Rcirc to ensure
  theme-wide consistency (e.g. timestamps are a shade of cyan).

* Tweaked adoc-mode faces for stylistic theme-wide consistency.

* Refashioned all the git faces of Treemacs so that they are more
  consistent with other such contexts or uses.  The new styles also
  conform with the 'modus-themes-deuteranopia' option.

Miscellaneous
=============

* Ended the wanton use of internal functions in places that did not
  require them.  Instead, the themes define faces that evaluate such
  functions once and pass their results to the relevant entries.  Cases
  include:

    - Symlink and/or broken link faces in contexts such as Dired,
      Eshell, Helm, Trashed.

    - Tabbed interfaces (tab-bar, tab-line, centaur-tabs).

    - Verbatim markup or that of inline code in Org, Markdown, Asciidoc,
      etc.

    - The optional use of 'variable-pitch' for User Interface elements
      (see 'modus-themes-variable-pitch-ui').

* Refined the dedicated diff background colours of modus-vivendi that
  are used when the user option 'modus-themes-deuteranopia' is non-nil.
  The changes improve the distinction between all red and yellow
  constructs in contexts where they appear together (e.g. smerge-mode).
  Basically, yellows will look more bright, while reds appear as
  brown. The corresponding blues are toned down a bit to be consistent
  with the other colours.  Consequently, the standard shades of green
  for added lines (when 'modus-themes-deuteranopia' is nil) are
  recalibrated to combine well with all other values.

* Made several faces return an 'unspecified' value instead of nil for
  their unused attributes under certain circumstances.  This is to guard
  against third-party code that unconditionally expects a non-nil value.

* Omitted {over,under}line attributes from the mode line when the
  'padded' property is added to the 'modus-themes-mode-line' user
  option.  Those are not necessary in that context.  Thanks to Illia
  Ostapyshyn for the contribution in merge request 54:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/54>

* Rewrote several internal functions in the interest of consistency and
  clarity.

* Deleted two user options that were long obsolete: (i)
  'modus-themes-org-habit' has been superseded by
  'modus-themes-org-agenda' since version 1.5.0 of the themes and (ii)
  'modus-themes-intense-hl-line' has been replaced by
  'modus-themes-hl-line' since version 1.3.0.

* Removed parentheses from headings in the manual as they are invalid
  characters for some version of Texinfo.  See Emacs bug#52126:
  <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=52126>.

* Updated all doc strings so that quoted lists yield valid syntax in
  Help buffers; syntax that can be directly evaluated (otherwise Emacs
  prettifies straight quotes as curly ones, which break the code).
  Thanks to Christian Tietze for bringing this issue to my attention:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/248#note_753169268>.

* Rewrote all sections of the manual to document the current state of
  the project as pertains to valid user options, explicitly supported
  face groups, and so on.

Modus themes version 1.7.0

By Protesilaos Stavrou <info@protesilaos.com> on 2021-11-18

The present entry records the changes made to the project since the
release of version 1.6.0 on 2021-09-29.  There have been more than 60
commits since then.

Every modification pertaining to colour combinations referenced herein
is 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).
Edits also account for colour-coding that is optimised for the needs of
users with red-green colour deficiency (deuteranopia).

To access the URL of the manual visit this web page:
<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 (next stable release), and
are available on GNU ELPA as well as other archives.  This release is
the first one that is included with Emacs 29, or else the 'master'
branch in emacs.git.

Customisation options
=====================

+ The 'modus-themes-no-mixed-fonts' has been deprecated and replaced by
  the 'modus-themes-mixed-fonts'.  This is a breaking change for users
  who want to use "mixed fonts": they must set the new variable to
  non-nil.

  As the name implies, the new variable changes the meaning of the
  feature to make it opt-in by default.  This is consistent with the
  principle of least surprise, as users may not know why some fonts look
  different than others in certain cases.

  Thanks to Christian Tietze for clarifying the doc string of this new
  user option in merge request 51:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/51>.

  For context, "mixed fonts" refers to a design where spacing-sensitive
  constructs, such as code blocks and Org tables, inherit from the
  'fixed-pitch' face to remain monospaced (and properly aligned) at all
  times.  Depending on the user's configurations, the 'fixed-pitch' face
  may not use the typeface that the user expects.

  The manual provides information on how to set the desired fonts by
  editing the 'default', 'fixed-pitch', and 'variable-pitch' faces.

+ The new 'modus-themes-mode-line-padding' can be used to control the
  apparent padding of the mode line when the user option
  'modus-themes-mode-line' includes the 'padded' property.  The padding
  must be a positive integer (otherwise the code would be needlessly
  complex to guard against values that make the mode line look awkward,
  like anything lower than -3 or maybe even -2).

  Thanks to Guilherme Semente and Manuel Uberti for the feedback in
  issue 245: <https://gitlab.com/protesilaos/modus-themes/-/issues/245>.

  Note that the out-of-the-box style of the themes has a padding of 1
  (technically a ':line-width' of 1 for the ':box' attribute), whereas
  the default style of Emacs has it at -1.  This is a design choice to
  avoid an overlap between the outer boundaries of a font's glyphs and
  the borders of the mode line, when using certain common typefaces at
  various point sizes.  Such an overlap can hinder readability.

  The manual contains a new Do-It-Yourself (DIY) section with detailed
  code samples on how to apply a negative value.

+ The new 'modus-themes-intense-markup' option can be set to non-nil to
  make constructs such as inline code and verbatim text more colourful.
  This has a general utility, though its consideration was prompted by a
  phenomenon reported by Stefan Kangas in issue 238 where the overlay of
  the 'hl-line-face' overrides the subtle background these constructs
  use and can thus make them virtually indistinguishable from ordinary
  text: <https://gitlab.com/protesilaos/modus-themes/-/issues/238>.

  Such is the standard behaviour of 'hl-line-mode' and there is nothing
  a theme can (or rather "should") do about it.  Thanks to Stefan Kangas
  for the feedback.

+ The 'modus-themes-headings' option can now accept and apply an exact
  font weight such as 'semibold' or 'light'.  (The list of available
  weights is the value of the 'modus-themes--heading-weights' internal
  variable.)  This supersedes the now-deprecated 'no-bold' property:
  'no-bold' is henceforth understood as the presence of a 'regular'
  weight.

  Recall that this user option is an alist and can be used to target
  heading levels individually, which further reinforces the utility of
  this new property.

  Thanks to Christian Tietze for suggesting this idea in issue 248:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/248>.  And
  thanks to Daniel Mendler for refining its implementation in commit
  54bfd62, which was sent as a patch file (yes, we accept those and I
  actually prefer them over a web app's UI).

+ The 'modus-themes-org-agenda' has seen improvements to its 'event' key
  (this is an alist that has multiple keys).  It now accepts a 'varied'
  property which differentiates between (i) plain timestamp entries and
  (ii) entries that are generated from either the diary or a symbolic
  expression.  The 'varied' property combines with the other available
  properties to particularise their effects.  Consult the doc string or
  the manual for the technicalities.

  Thanks to Gustavo Barros for the detailed commentary in issue 241:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/241>.

+ The 'modus-themes-lang-checkers' now accepts a 'faint' property.  This
  has the effect of toning down the colours in use.  By default, the
  only colour is that of the underline, though more can be added by
  combining the properties accepted by this user option.  Consult its
  doc string or the manual for further details.

  Thanks to Morgan Smith for suggesting the idea in issue 239:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/239>.

Add support for new packages or face groups
===========================================

+ 'company-tooltip-deprecated' face.  Thanks to Roman Rudakov for the
   feedback in issue 247: <https://gitlab.com/protesilaos/modus-themes/-/issues/247>.

+ 'corfu-default' face.  Thanks to Daniel Mendler (Corfu's developer)
  for the feedback in issue 254:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/254>.

+ 'image-dired' package (Emacs 29).  Thanks to Stefan Kangas for making it
  happen in emacs.git and for the feedback in issue 250:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/250>.

+ 'nano-modeline' package.

+ 'vertico-quick' package.  Thanks to Nicolas De Jaeghere for the
  contribution in merge request 48:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/51>.

Changes to existing faces or face groups
========================================

+ Added support for the new Org agenda faces that improve the
  contextuality of various views.  We implemented those upstream for Org
  version 9.5 in close cooperation with Gustavo Barros.  Thanks to
  Gustavo for the detailed feedback in issue 241:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/241>.  The
  thread about the patch upstream:
  <https://list.orgmode.org/87lf7q7gpq.fsf@protesilaos.com/>

+ Refined Org agenda date faces in the interest of consistency and in
  accordance with the aforementioned change.  Thanks again to Gustavo
  Barros for the discussion in issue 241.

+ Applied the 'shadow' face more consistently across all contexts where
  only a subtle foreground value is expected.  This design choice makes
  it possible for users to manually edit the foreground colour of
  'shadow' to something even more subtle than the 'fg-alt' palette
  variable we use, which maps to a gray colour (e.g. they could use
  "gray50").

+ Implemented a subtle background colour to the 'widget-inactive' face.
  This makes it easier to discern inactive buttons, checkboxes, and the
  like, in contexts such as the Customize User Interface.  Thanks to
  Stefan Kangas for the feedback in issue 242:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/242>.

+ Tweaked 'file-name-shadow' to also use italics (inherit from the
  'italic' face) in order to be more easy to distinguish it from
  ordinary text in the minibuffer.

  Recall that the manual documents the meaning of inheriting from the
  'bold' and 'italic' faces instead of hardcoding a bold weight and an
  italic slant, respectively.  In short: users can change the weight to
  what they want (e.g. semibold) and/or use distinct font families.

+ Amplified the style of Version Control (VC) warnings and errors to let
  them draw more attention to themselves (because these indicators need
  to be acted upon).

+ Recoloured the 'custom-group-tag' face to make it fit better in its
  context and be consistent with the rest of the themes' established
  patterns.

+ Made marks for selection in Dired, Ibuffer, and related, conform with
  the 'modus-themes-success-deuteranopia' option.  This means that they
  use blue colours when the option is non-nil, instead of their default
  shades of green.

+ Adjusted the box width of key bindings for Emacs 28 or higher.  They
  should no longer cause any alignment issues.  This style is now used
  throughout the themes, including in transient views (e.g. Magit) which
  were the exception before.  Thanks to Manuel Uberti and Kevin Fleming
  for the feedback in issue 232:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/232>.

Miscellaneous
=============

+ Wrote a brief description of every user option in the manual.  Also
  covered its type, as in boolean, alist, et cetera.

+ Corrected the mode line border width for one combination of properties
  in the 'modus-themes-mode-line' option.  This should now have the same
  height as all others:

      (setq modus-themes-mode-line '(accented borderless))

+ Ensured that mode line attributes would not be set to nil, but kept at
  an 'unspecified' value instead, where relevant.  This avoids problems
  with [faulty] code that unconditionally depends on something that does
  not exist, as in the following while ':box' is nil:

      (face-attribute 'mode-line :box)

+ Expanded, reworded, or otherwise improved the manual, based on the
  aforementioned.

Thanks once again to everyone involved!

Modus themes version 1.6.0

By Protesilaos Stavrou <info@protesilaos.com> on 2021-07-15

This entry records the changes made to the project since the release of
version 1.5.0 on 2021-07-15.  There have been around 70 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/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.  This release
is the final one for the emacs-28 branch, as that gets cut as the next
stable release of GNU Emacs.  Future releases will target Emacs 29 once
that becomes the new 'master' branch.

Customisation options
=====================

[ Themes need to be reloaded for changes to take effect. ]

+ Introduced the new 'modus-themes-tabs-accented' boolean option.  When
  set to non-nil, it renders the background of all tab interfaces in a
  shade of blue.  Those interfaces are tab-bar (built-in), tab-line
  (built-in), and Centaur tabs.

  - The background "accented" colour is the same as the one used for
    mode lines when 'modus-themes-mode-line' is configured accordingly.

+ Tweaked the 'modus-themes-mode-line' to accept a 'padded' symbol as
  part of the list of properties it can read.  This will increase the
  spacing around the mode lines' text, making the line taller overall
  but also more spacious.

  Thanks to Manuel Uberti for making the proposal and providing feedback
  in issue 228: <https://gitlab.com/protesilaos/modus-themes/-/issues/228>.

+ Added the 'modus-themes-scale-small' which complements the existing
  scale values with one that is meant to be smaller than the base
  height.  This option is reserved for special cases and is currently
  only used as an opt-in feature in the Org agenda.

+ Expanded the 'modus-themes-org-agenda' with more parameters:

  - The current date can now also be underlined.
  - Date headings can be scaled/enlarged in size.
  - Events, like those of the Diary or sexp entries, can be customised.

  Consult the manual or the variable's doc string for the details.

+ Removed the obsoleted aliases 'modus-themes-slanted-constructs' and
  'modus-themes-scale-5'.  Those are superseded by the more
  appropriately named 'modus-themes-italic-constructs' and
  'modus-themes-scale-title'.

  Thanks to Nicolas De Jaeghere for the patch in merge request 47:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/47>.

Faces and face groups
=====================

+ Make the 'prodigy' faces for red/green/yellow inherit from the faces
  'error'/'success'/'warning', respectively.  This is done to (i) avoid
  duplication and (ii) ensure that the green/success colour coding is
  consistent with the goal of the themes to empower users with red-green
  colour deficiency.  The boolean option that changes all such greens to
  shades of blue is 'modus-themes-success-deuteranopia'.

+ Assigned the ':extend' attribute to the 'org-code' face.  This is
  necessary when the Org source contains lines that start with a colon
  sign.  Those are interpreted as code blocks.  For example:

      :  #+BEGIN_SRC emacs-lisp
      :    (defun in-interval (bounds el)
      :      (and (>= el (car bounds)) (<= el (cadr bounds))))
      :  #+END_SRC

  With the ':extend' in place, the background stretches to the edge of
  the window, thus giving those lines a uniform rectangular shape.  For
  inline uses of 'org-code', the background should remain limited to the
  span of the text.

+ Broadened support for 'marginalia' faces in two phases.

  - The first pertained to the file permissions that are shown when
    completing against file paths.  Their style is similar to what
    'dired+' or the 'direfl' packages provide, however we have taken
    care to optimise the interface for the purposes of completion
    UIs---where things can look like Dired, we make them alike, but
    where they must differ, we differentiate the designs accordingly.
    There can be no compromises or arbitrary constraints.

    Also read: <https://github.com/minad/marginalia/pull/91>.

  - The second batch covered all sorts of extra classes that provide
    granular control over the appearance of Marginalia instances.
    Refinements also had to be made to already-supported faces for the
    sake of achieving consistency across the various Marginalia
    interfaces.

    Also read: <https://github.com/minad/marginalia/pull/92>.

+ Refined 'diredfl' and 'dired+' faces.  For the various "priv" faces,
  the intent is to increase the difference in hueness between adjacent
  file permissions (the changes are minor, but they do change the
  overall result).  Numbers are toned down so that they do not clash
  with dates.  The file suffix no longer uses cyan to stand out more in
  detailed views.

+ Made 'icomplete-selected-match' (Emacs28) more legible by aligning its
  presentation with metaphors that are estaslished across the
  modus-themes.  Thanks to Kévin Le Gouguec (peniblec) for noting the
  inconsistency with the new face upstream and for writing the patch for
  it in merge request 50:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/50>.
  Also thanks to Manuel Uberti for confirming that things would look
  consistent in the comments' section of that merge request.

+ Fixed faulty inheritance for the 'web-mode-keyword-face'.  It should
  now properly copy the attributes of 'font-lock-keyword-face'.

+ Made inheritance of the new 'help-key-binding' (Emacs28 key) the
  default for all faces that need to style key bindings.

  In Emacs 28 all key bindings are automatically displayed with the face
  'help-key-binding' which uses some new face attributes to draw a
  cleaner box around it.  Given that the themes must work with earlier
  versions of Emacs, we cannot inherit it unconditionally so we added
  the relevant conditionality.  It is nice to offer this feature to
  those who use the themes on Emacs 28.  Older versions retain the
  previous style of a blue colour coupled with a bold weight.

  The exception to this rule is the transient.el faces (this is the
  pop-up window used by Magit, among others---transient.el is now built
  into Emacs).  The box effect creates unpredictable misalignments, so
  we default to the old key binding style for those.

  Thanks to Manuel Uberti and Kevin Fleming for their feedback in issue
  232: <https://gitlab.com/protesilaos/modus-themes/-/issues/232>.

+ Added support for the new 'notmuch-jump-key' face.  I contributed this
  face in commits c37c9912, 5cc106b0 to the Notmuch git repo:
  <https://git.notmuchmail.org/git/notmuch>.

+ Updated the 'bookmark-face' (Emacs28) as it has been changed upstream
  to be a fringe indicator instead of an in-buffer, line-wide background
  highlight.

+ Aligned Ediff faces with other 'modus-themes-diffs' styles.  Before we
  would differentiate a "focus state", though that is now considered
  surplus to requirements.  The notion of a "focus state" only make
  sense in Magit which applies variegated colour-coding to diff hunks
  based on their state.  Whereas non-active Ediff changes are grayed
  out, so there is no need for further colour-coding nuances.  The most
  noticeable change is with:

      (setq modus-themes-diffs 'bg-only)

  As noted in the commit message of 64c74ae (from 2021-09-04):

      If users think this change is for the worse, we can always define a
      helper function like this:

          (defun modus-themes--ediff-style (bgonly default)
            "Diff style for Ediff.
          BGONLY and DEFAULT depend on the value of `modus-themes-diffs'.
          The former is more subtle."
            (if (eq modus-themes-diffs 'bg-only)
                (list bgonly)
              (list default)))

      And apply it thus:

          `(ediff-current-diff-A ((,class :inherit ,@(modus-themes--ediff-style
                                                      'modus-themes-diff-removed
                                                      'modus-themes-diff-focus-removed))))

  No feedback was received towards that end in about a month, so we
  consider the change to be acceptable, without prejudice to the
  possibility of future updates.

+ Unified the styles of 'org-agenda-calendar-sexp', 'org-agenda-diary',
  and 'org-agenda-calendar-event'.  This is not a user-facing change but
  an internal refactoring to avoid repetition.  It also makes things
  easier for the implementation of the 'modus-themes-org-agenda' (as
  mentioned above).

+ Ensured that the 'bookmark-menu-bookmark' face inherits from the
  'bold' face.  By default it hardcodes the bold weight, whereas we
  instruct it to inherit the 'bold' face.  A user can thus change the
  ':weight' of that face to whatever they want, like semibold,
  extrabold, etc.  We do this throughout the themes for bold and
  italics---consider it a "hidden feature" of sorts.  Check the manual
  for more on the matter:

      (info "(modus-themes) Configure bold and italic faces (DIY)")

+ Provided support for tab-bar groups (Emacs28).  Specifically the faces
  'tab-bar-tab-group-current' and 'tab-bar-tab-group-inactive'.

  Thanks to Adam Porter (alphapapa) for the feedback in issue 8 over at
  the Github mirror: <https://github.com/protesilaos/modus-themes/issues/8>.

+ Decoupled the 'stripes' face from that of 'hl-line-face'.  This is
  because the stripes are not meant to change depending on the value of
  the user option 'modus-themes-hl-line'.

+ Revised the red shade of "flagged" entries in mu4e and notmuch.  Those
  are now consistent with Gnus.  The shade of red that was used before
  was closer to the orange side of the spectrum whereas the current has
  hints of blue (a cherry colour) and thus combines better with the cyan
  and blue that prevail in those interfaces.  These are fine margins,
  though the effect is noticeable regardless.

+ Configured the new 'ansi-color' faces (Emacs28) which are used by
  shells and terminals (among others).  Thanks to Manuel Uberti for
  reporting the changes to upstream Emacs in issue 236:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/236>.

+ Expanded support for EMMS faces, pertaining to its browser views.
  Thanks to Feng Shu (tumashu) for bringing those to my attention in
  issue 11 over at the Github mirror:
  <https://github.com/protesilaos/modus-themes/issues/11>.

+ Styled the new 'tab-line-tab-modified' face (Emacs28).  It should now
  use a faint red colour to denote changes to the underlying file.
  Thanks to Adam Porter (alphapapa) for bringing it to my attention in
  issue 12 over at the Github mirror:
  <https://github.com/protesilaos/modus-themes/issues/12>.

+ Configured the single face that the 'cursor-flash' package has to
  offer.  Thanks to Manuel Uberti for the feedback in issue 231:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/231>.

+ Included 'elpher' in the list of supported packages by means of
  covering the heading faces it implements.

+ Recalibrated certain dedicated colours for inactive tabs and tweaked
  tab faces to (i) marginally improve the default aesthetic and (ii)
  harmonise it with the style of 'modus-themes-tabs-accented'.

+ Removed the foreground attribute from all markup faces that are meant
  to denote emphasis in italics.  That is because such faces are
  typically composed with others, so we do not wish to inadvertently
  override any other colour that would otherwise have taken effect.

+ Wrote the faces for upstream Org that improve the contextuality of
  various agenda views (included in version 9.5).  This was done in
  close collaboration with Gustavo Barros who offered detailed feedback
  in issue 208 (which also led to the creation and eventual expansion of
  the 'modus-themes-org-agenda' user option):
  <https://gitlab.com/protesilaos/modus-themes/-/issues/208>.

  Four new faces improve certain styles and offer more flexibility for
  some Org agenda views: 'org-agenda-date-weekend-today',
  'org-imminent-deadline', 'org-agenda-structure-secondary',
  'org-agenda-structure-filter'.  They inherit from existing faces in
  order to remain backward-compatible.

  Quoting from <https://list.orgmode.org/87lf7q7gpq.fsf@protesilaos.com/>:

      + The 'org-imminent-deadline' is useful to disambiguate generic
        warnings from deadlines.  For example, a warning could be
        rendered in a yellow colored text and have a bold weight,
        whereas a deadline might be red and styled with italics.

      + The 'org-agenda-structure-filter' applies to all tag/term
        filters in agenda views that search for keywords or patterns.
        It is designed to inherit from 'org-agenda-structure' in
        addition to the 'org-warning' face that was present before (and
        removes the generic 'warning' face from one place).  This offers
        the benefit of consistency, as, say, an increase in font height
        or a change in font family in 'org-agenda-structure' will
        propagate to the filter as well.  The whole header line thus
        looks part of a singular design.

      + The 'org-agenda-structure-secondary' complements the above for
        those same views where a description follows the header.  For
        instance, the tags view provides information to "Press N r" to
        filter by a numbered tag.  Themes/users may prefer to
        disambiguate this line from the header above it, such as by
        using a less intense color or by reducing its height relative to
        the 'org-agenda-structure'.

      + The 'org-agenda-date-weekend-today' provides the option to
        differentiate the current date on a weekend from the current
        date on weekdays.

Other patches I have made to, inter alia, emacs.git and org.git with
regard to faces are documented in previous change log entries.

Documentation
=============

+ Removed references to old versions of the themes from before their
  refactoring in version 1.0.0.  Those old packages no longer exist.
  Users must install the 'modus-themes' and then load either of
  'modus-operandi' or 'modus-vivendi'.

+ Included various extensions of the Vertico package in the list of
  indirectly supported packages.  Those define faces which either
  inherit from basic ones that we already support or use colours that
  are consistent with our accessibility target.

+ Referenced 'side-hustle', 'tide', 'bufler' as an indirectly supported
  packages for the same reasons.

+ Simplified time-stamp local variables that are used in modus-themes.el
  to show the time the file was edited.  We apply 'time-stamp-pattern'
  instead of setting multiple time-stamp variables.  Thanks to Stephen
  Gildea for the patch, which was sent to me via email (yes, you can
  always do that).

+ Updated the manual's "acknowledgements" section to name all new
  contributors to code/ideas/feedback.

+ Furnished information on how to configure the 'highlight-parentheses'
  package and extend its faces for use with the themes.  The entry
  provides a complete Elisp implementation.

+ Improved the code samples for the prism.el setup that users may wish
  to set up by themselves.  The new lists of colours work better when
  Prism's colouration is limited to a small set of hues.

+ Deleted trailing whitespace in the manual which had adverse effects
  when trying to compile the modus-themes.org over at emacs.git.  Thanks
  to Philip Kaludercic for the patch in merge request 49:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/49>.

Thanks again to everyone involved.  Looking forward to see the Modus
themes, version 1.6.0, as part of the next stable release of Emacs.

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

+ 'modus-themes-prompts' by Philip Kaludercic in merge request 43:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/43>

+ 'modus-themes-mode-line' by Philip Kaludercic in merge request 40:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/40>.

+ 'modus-themes-lang-checkers' by Philip Kaludercic in merge request 46:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/46>

+ 'modus-themes-org-agenda'
+ 'modus-themes-links'
+ 'modus-themes-headings'
+ 'modus-themes-hl-line'
+ 'modus-themes-paren-match'
+ 'modus-themes-region'
+ 'modus-themes-syntax'

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:

+ '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>.

+ 'css-mode'

New faces for already supported groups:

+ 'shr-h1', 'shr-h2', 'shr-h3', 'shr-h4', 'shr-h5', 'shr-h6' of 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-button' as 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
--------------------------

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

+ Issue 196 on 'modus-themes-no-mixed-fonts'
  <https://gitlab.com/protesilaos/modus-themes/-/issues/196>.

+ Issue 198 on 'modus-themes-hl-line'
  <https://gitlab.com/protesilaos/modus-themes/-/issues/198>

  [ Note that 'modus-themes-hl-line now accepts a list of properties as
    described in the opening sections of this entry. ]

+ Issue 218 on 'modus-themes-diffs'
  <https://gitlab.com/protesilaos/modus-themes/-/issues/218>.

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!

Modus themes version 1.4.0

By Protesilaos Stavrou <info@protesilaos.com> on 2021-05-25

This entry records the changes made to the project since the release of
version 1.3.0 on 2021-04-17.  There have been around 100 commits in the
meantime, as is the norm.

If you are coming from older versions, please consult the change log
entry for version 1.0.0 with regard to the breaking changes that were
introduced.

Every colour-related modification is always done in accordance 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 (the WCAG AAA standard).

URL of the official manual: <https://protesilaos.com/modus-themes>.  Or
read it with Emacs' Info reader by evaluating this form:

    (info "(modus-themes) Top")

Remember that the themes are built into Emacs version 28 (current
development target), and are available on GNU ELPA, as well as other
archives.

Customisations variables
------------------------

+ Redefined the style of 'fg-only' that 'modus-themes-diffs' accepts, so
  that it no longer uses a red-green colour coding, but applies a
  red-blue distinction instead.  The symbol 'fg-only' is a deprecated
  alias for the more descriptive 'fg-only-deuteranopia'.

  This is done because green text on a light background is one of the
  worst combinations for the purposes of legibility, as it does not
  stand out in its context and thus forces undesirable compromises.
  Whereas red and blue work well in this case, while making the style
  accessible to users with red-green colour deficiency (deuteranopia).
  To avoid inconsistencies between Modus Operandi and Modus Vivendi, we
  replace green with blue in both themes.  A full report is available in
  issue 183 which was created on April 21, 2021:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/183>.

+ Introduced the boolean 'modus-themes-success-deuteranopia' which
  replaces all instances of green with blue in contexts where a
  red-green colour coding is in effect (e.g. Org TODO vs DONE keywords,
  isearch current match...).

+ Implemented 'modus-themes-mail-citations' to control the colouration
  of cited text in email-related buffers, such as Gnus or message.el.
  It accepts values nil, 'faint', and 'monochrome'.  By default (the nil
  value) the text of citations cycles through blue, green, red, yellow
  depending on the level of depth.

+ Expanded the set of options for 'modus-themes-mode-line' to encompass
  the values 'borderless-accented', 'borderless-accented-3d', and
  'borderless-accented-moody'.  Those are variations of existing styles.
  The complete list:

  - nil (default)
  - 3d
  - moody
  - borderless
  - borderless-3d
  - borderless-moody
  - accented
  - accented-3d
  - accented-moody
  - borderless-accented
  - borderless-accented-3d
  - borderless-accented-moody

+ Renamed the non-nil values that 'modus-themes-org-blocks' accepts from
  'grayscale', 'rainbow' to 'gray-background' and 'tinted-background',
  respectively.  The new symbols better describe their effect on Org
  source blocks, namely, that they affect the background of the block
  rather than the foreground.  The old symbols will still work but are
  considered deprecated aliases of the newer ones.

+ Altered the intensity of the 'modus-themes-hl-line' option
  'accented-background' to a more noticeable shade of cyan/teal.  The
  old style was too subtle to have the desired effect.  The value
  'underline-accented' is not affected by this change, as it still uses
  the same subtle background it did before in combination with a more
  pronounced underline colour.

+ Deleted all deprecation warnings that concerned the transition from
  version 0.13.0 of the themes to 1.0.0.  Those had been in effect for
  several months, spanning four tagged releases.

Faces or face groups
--------------------

+ Reconsidered the use of colour in all email-related citation faces to
  avoid exaggerations and reduce complexity.  Colour values have been
  tweaked to tone down their overall intensity, while the number of
  colours has been reduced to four.  Gnus and Mu4e have faces for more
  levels of citation depth, though those will simply repeat the
  four-colour cycle.

+ Made the 'message-mml' face look consistent with the rest of the
  buffer while composing an email by changing its foreground colour from
  a yellow to a cyan variant.

+ Refined several faces in the Notmuch group in the interest of harmony:

  - Individual message headers in 'notmuch-show-mode' use bold text in
    addition to their existing subtle background to better stand out in
    their context. The face is 'notmuch-message-summary-face'.

  - Tags are no longer set unconditionally to a bold typographic weight.
    They become such for unread threads in 'notmuch-search-mode'
    buffers, as well as for headers of 'notmuch-show-mode'.

  - Removal and addition of tags is now denoted by a strike-through and
    an underline effect, respectively, whereas before they both used
    underlines with the only difference being their colour.

  - The subject line in 'notmuch-search-mode' buffers uses the main
    foreground instead of a dimmed one.  The field of matching authors
    has a tweaked foreground to keep the tabular view easy to read.

  - All cryptography-related faces are simplified to not show a coloured
    background but only use a foreground colour instead.

+ Removed direct support for 'counsel-notmuch' as it already inherits
  from the relevant notmuch faces.  The package is thus considered
  indirectly supported.

+ Refrained from setting a background to the 'csv-separator-face' as it
  would inevitably colourise the negative space in the tabular view
  created by 'csv-align-mode'.  A red text colour is used instead, even
  though this is not common practice: it is easier to spot for small,
  single characters, such as a comma or a semicolon that is meant to
  have a special meaning.  Thanks to Kevin Fleming for reporting the
  problem and for offering feedback on the choice of colour in issue
  194: <https://gitlab.com/protesilaos/modus-themes/-/issues/194>.

+ Distinguished between ordinary links and widget buttons by removing
  the underline from the latter (the 'widget-button' face) and altering
  the shade of its foreground colour.  Such widgets are used in Emacs'
  Custom interfaces and can also be found in the default Notmuch "hello"
  buffer that runs 'notmuch-hello-mode'.

+ Tweaked the Ediff current faces to be consistent with 'diff-mode' and
  related.  In practice, this only applies when 'modus-themes-diffs' is
  set to a value of 'fg-only-deuteranopia', as it adds a dim background
  to the current diff hunk.  All other styles of 'modus-themes-diffs'
  look the same as before while using Ediff.

+ Simplified the faces of 'corfu' to match the current state of the
  upstream project.  Thanks to Daniel Mendler (its developer) for
  reporting this in issue 184:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/184>.

+ Refined all Eshell faces so that the output of 'ls' is consistent with
  the overall aesthetic of the themes.  Also made 'eshell-prompt'
  inherit from 'comint-highlight-prompt' to look the same as other such
  prompts (all are configurable by 'modus-themes-prompts').

+ Revised 'eshell-prompt-extras' and 'eshell-git-prompt' to use colours
  and typographic weight that better match the style of the various
  configurations they offer.

+ Simplified 'eshell-syntax-highlighting' to inherit from the standard
  Eshell faces, where appropriate.

+ Adjusted the colour of 'centaur-tabs-active-bar-face' and removed the
  bespoke 'fg-tab-accent' colour from 'modus-themes-operandi-colors' and
  'modus-themes-vivendi-colors' that was only used by it (and which
  should have never been introduced to begin with).

+ Updated the 'tab-bar-groups' faces to match changes upstream.  Thanks
  to Fritz Grabo (its developer) for the patch in merge request 35:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/35>.

+ Changed the Ibuffer title and group faces to better differentiate
  between group titles and special or non-file-visiting buffers.  Thanks
  to Nicolas De Jaeghere for the patch in merge request 37:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/37>.

+ Ensured that all faces that denote a "success" state, or which are
  expected to be coloured in green in a red-green binary, can use an
  appropriate blue colour (or colour combination that involves blue)
  instead when 'modus-themes-success-deuteranopia' is set to a non-nil
  value.

+ Added support for the new 'bookmark-face' in Emacs version 28.  This
  means that the built-in bookmark.el library is directly supported by
  the themes.  This face can be disabled by setting 'bookmark-fontify'
  to nil.  Thanks to Mark Barton for reporting the presence of this new
  face and for providing feedback on its style in issue 189:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/189>.

+ Aligned 'hes-mode' ('highlight-escape-sequences') with the standard
  font-lock faces for regexp grouping.  This means that it conforms with
  changes to the 'modus-themes-syntax' variable.

+ Reconfigured the 'org-quote' face to adapt its style depending on the
  value of 'modus-themes-org-blocks'.  The default is a subtle blue/cold
  foreground colour against the main background.  When a value of
  'gray-background' is assigned to 'modus-themes-org-blocks', the text's
  colour becomes that of the main foreground in order to maintain a good
  level of legibility.  Thanks to Rudolf Adamkovič for the feedback in
  issue 190: <https://gitlab.com/protesilaos/modus-themes/-/issues/190>.

+ Refashioned the 'show-paren-match-expression' face to make it apply a
  bespoke background colour and not override the expression's foreground
  colours.  This face is used by 'show-paren-mode' when the
  customisation variable 'show-paren-style' is set to the 'expression'
  value.  Thanks to Rudolf Adamkovič for the feedback in issue 191:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/191>.

+ Made headings level 8 use a fine shade of magenta by default instead
  of gray (notwithstanding user changes to 'modus-themes-headings').
  This should have a negligible difference in Org or Outline buffers,
  but is more noticeable when editing Elisp in Emacs28 while also using
  'outline-minor-mode' and with 'outline-minor-mode-highlight' set to
  'override'.  That is because several top-level forms use that heading
  level with those configurations.

Documentation (the manual)
--------------------------

+ Incorporated a sample configuration block with all customisation
  variables and with comment annotations of their available options, in
  an attempt to make it easier for users to discover what the themes
  provide.

+ Replaced all instances of "modeline" with "mode line" for consistency
  with the Emacs style.  Thanks to Rudolf Adamkovič for the patch that
  started this process in merge request 33:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/33>.

+ Wrote note on setting mode line faces that indicate the state of
  'god-mode'.  Thanks to Rudolf Adamkovič for the feedback in issue 187:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/187>.  Also
  thanks to Rudolf for updating the applicable hook in merge request 34:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/34>.

+ Listed 'org-mode' variables that affect fontification in blocks:
  'org-src-fontify-natively', 'org-fontify-whole-block-delimiter-line',
  and 'org-fontify-quote-and-verse-blocks'.  This complements the
  already documented variables 'org-fontify-whole-heading-line' and
  'org-fontify-done-headline' that pertain to headings.

+ Included note on fontifying inline Latex expressions in Org buffers.
  Thanks to Rudolf Adamkovič for the feedback in issue 190:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/190>.

+ Elaborated on the use of 'face-remap-add-relative' by means of sample
  code that cycles through arbitrary colours for the 'region' face.
  This is filed under the "Do It Yourself" (DIY) section.

+ Provided a DIY method for adapting the fontification of Org source
  block delimiter lines to the value of 'modus-themes-org-blocks'.

+ Expanded the DIY entry on overriding the saturation of the active
  theme's colours with a method that combines the programmatic approach
  with manual overrides.  The user can thus specify the colour values
  they want to override and let the rest be handled by Elisp.

+ Introduced a section with answers to Frequently Asked Questions (FAQ)
  about the design of the themes as well as recommendations on how to
  ensure optimal reading conditions or start thinking about them.  The
  questions are:

  - Is the contrast ratio about adjacent colors?
  - What does it mean to avoid exaggerations?
  - Why are colors mostly variants of blue, magenta, cyan?
  - What is the best setup for legibility?

Miscellaneous
-------------

+ Removed superfluous code from internal functions and adapted their
  indentation to make them easier to read.

+ Recalibrated some values in 'modus-themes-vivendi-colors' to ensure
  consistency in luminance with other colours that are used in their
  context.  Those are subtle changes that can only be discerned in
  side-by-side comparisons of the before and after states.  Thanks to
  André Alexandre Gomes for the feedback in issue 193:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/193>.

+ Changed the saturation and hueness of the bespoke 'fg-comment-yellow'
  in 'modus-themes-operandi-colors' and 'modus-themes-vivendi-colors' to
  better contrast with its context, while still keeping its luminance
  consistent with its role as a colour for comments in code.  This is
  used when 'modus-themes-syntax' is configured appropriately (read its
  doc string or consult the manual).

+ Attempted to add explicit support for the faces of the built-in
  pulse.el library, but ultimately opted against them as the doc string
  of 'pulse-highlight-face' advises against customising it, even though
  it is not clear from the source code in emacs.git what the problem
  could be.  We shall reconsider this case for the next release cycle.
  Thanks to Gustavo Barros for the feedback on several aspects of this
  topic in issues 185 and 200:

  - <https://gitlab.com/protesilaos/modus-themes/-/issues/185>
  - <https://gitlab.com/protesilaos/modus-themes/-/issues/200>

+ Took the feedback of John Haman in issue 199 as a reminder to complete
  the set of possible values for the 'modus-themes-mode-line' variable:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/199>.

Modus themes version 1.3.0

By Protesilaos Stavrou <info@protesilaos.com> on 2021-04-17

This entry records the changes introduced to the project since the
publication of version 1.2.0 (2021-03-04).  There have been around 100
commits in the meantime, as is the norm with all releases hitherto.

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 (the WCAG AAA standard).

As the official manual is referenced several times throughout this log,
make sure to store its URL: <https://protesilaos.com/modus-themes>.  Or
read it from Emacs' Info reader by evaluating this form:

    (info "(modus-themes) Top")

If you are coming from older versions, please consult the change log
entry for version 1.0.0 with regard to the breaking changes that were
introduced.

Remember that the themes are built into Emacs28, and are available on
GNU ELPA, as well as other archives.

Customisation options
---------------------

+ The old 'modus-themes-intense-hl-line' boolean variable has been
  replaced by 'modus-themes-hl-line', which provides several options for
  how to style the current line of 'hl-line-mode'.  To retain the old
  effect, one must do this:

      ;; Replacement for (setq modus-themes-intense-hl-line t)
      (setq modus-themes-hl-line 'intense-background)

  The list of possible values:

    1. nil (default)
    2. intense-background
    3. accented-background
    4. underline-neutral
    5. underline-accented
    6. underline-only-neutral
    7. underline-only-accented

  The doc string of 'modus-themes-hl-line' as well as the manual
  describe the specifics.  Thanks to Manuel Uberti for the feedback in
  commit b020592:
  <https://gitlab.com/protesilaos/modus-themes/-/commit/b020592e1a96d6e00d7d03faf9c293ec6081d49c>.

+ The 'modus-themes-mode-line' variable now accepts three new "accented"
  styles that complement the existing set:

    1. nil (default)
    2. 3d
    3. moody
    4. borderless
    5. borderless-3d
    6. borderless-moody
    7. accented
    8. accented-3d
    9. accented-moody

+ The 'modus-themes-region' is extended with two new options of an
  "accent" background:

    1. nil (default)
    2. no-extend
    3. bg-only
    4. bg-only-no-extend
    5. accent
    6. accent-no-extend

+ The default value of 'modus-themes-headings' for per-level styles can
  now be set to nil.  This fixes an inconsistency between the fallback
  value, which accepted nil, and the per-level styles which did not.
  Thanks to Mauro Aranda for reporting this in issue 163:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/163>.

  Please read the manual for the specifics of this variable, as it is an
  alist that accepts several possible combinations.

Updates to the manual
---------------------

+ Rewrote the sections that cover the aforementioned customisation
  options.

  - For 'modus-themes-mode-line', we had to revise the recommendation
    for setting 'face-near-same-color-threshold' to 45000.  That value
    is appropriate for the 'moody' and 'borderless-moody' options.
    Whereas for 'accented-moody' the number should be raised to 70000.
    Thanks to Nicolas De Jaeghere for providing this piece of
    information:
    <https://gitlab.com/protesilaos/modus-themes/-/commit/ab6ba698269f012ec880b690282264649bfb3b0d#note_551342198>

+ Rephrased the GNU Free Documentation License quote to match the style
  of other manuals that are also built into Emacs.

+ Documented 'org-mode' variables that affect the looks of various
  fontification styles.

+ Simplified the 'kbd' macro that is declared in modus-themes.org to
  allow GNU ELPA's build system to parse the file for Emacs 26.

+ Documented existing support for 'tab-bar-mode' and 'tab-line-mode'.

+ Wrote a note on how to configure the 'dimmer.el' library by Neil
  Okamoto, in order to guarantee consistent results with the themes.
  The key is to use the RGB colour space instead of CIELAB.

+ Included note on shr.el fonts and how those are used by EWW and
  Elfeed.

+ Added a "Do-It-Yourself" (DIY) section on how to remap buffer-local
  faces.

+ Detailed a DIY method to make the buffer-local backdrop of a pdf-tools
  page use a distinct colour than the default white for Modus Operandi.
  Extended the same principle to Modus Vivendi and described how to
  adapt to theme changes (such as via 'modus-themes-toggle').  Thanks to
  Utkarsh Singh for providing feedback on this topic in issue 175:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/175>.

+ Elaborated on DIY techniques to programmatically override the
  saturation of all colours specified by the active Modus theme.  Thanks
  to user pRot0ta1p for the feedback in issue 166:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/166>.

Support for packages
--------------------

These are added to the already comprehensive list of explicitly
supported packages:

+ corfu
+ embark

+ pandoc-mode.  Thanks to Farasha Euker for the feedback in issue 171:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/171>.

+ tab-bar-groups
+ telega
+ vertico

Also added support for the 'help-key-binding' face which is part of
Emacs 28.

Changes to already supported faces or face groups
-------------------------------------------------

+ Renamed all internal faces that the themes defined from
  "modus-theme-*" to "modus-themes-*".

+ Refashioned all Ediff faces in the process of a major review of this
  tools' overall design.  The manifold changes are:

  - All inactive diffs respect the underlying fontification
    (e.g. programming syntax highlighting).  Before they would override
    it with a gray foreground.

  - All inactive diffs have been toned down, as their background is a
    finer shade of gray than the prominent one that was used before.

  - There no longer is a visual distinction between even and odd
    inactive diffs (by means of different shades of gray).  We are of
    the opinion that such subtleties, whose utility is marginal at best,
    have no place in themes that are designed for accessibility.

  - All bespoke gray colour combinations that were only intended for
    those inactive diffs have thus been removed from each theme's
    palette.

  - Active diffs follow the same style as diff-mode, to ensure
    theme-wide consistency (all diff styles are controlled by the
    variable 'modus-themes-diffs').

  This topic was discussed at length (with screenshots) in issue 169:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/169>.  Thanks to
  peniblec and Nicolas De Jaeghere for their feedback.

+ Made 'smerge-markers' and 'vdiff-closed-fold-face' look like the
  headings in 'diff-mode' in the interest of consistency, especially
  while configuring the 'modus-themes-diffs' variable.

+ Ensured consistency between all faces that pertain to key bindings in
  contexts where the hint to the key is active, in that pressing the key
  performs the action (e.g. Magit's transient buffers, which-key,...).
  The 'help-key-binding' for Emacs 28 is not included in this group,
  because it applies in cases where the keys are not active, such as in
  Help buffers.

+ Refined 'epa-validity-disabled' and 'epa-validity-high' faces.  The
  former no longer uses a background, as that was considered an
  exaggeration.  While the latter is cast in a cyan hue instead of green
  for greater clarity (this relates to the general push to optimise for
  red-green colour deficiency, which means to only use green where it is
  absolutely necessary and, in such cases, to provide for a blue-ish
  alternative, as with the 'deuteranopia' value that can be assigned to
  'modus-themes-diffs').

+ Reworked 'ace-window', 'avy', and 'magit-blame' faces to ensure that
  their overlays do not inherit the face properties of underlying text,
  such as a different font family or height.  Thanks to Nicolas De
  Jaeghere for the multiple merge requests and the concomitant feedback:

  - <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/27>.
  - <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/29>.
  - <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/30>.
  - <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/31>.
  - <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/32>.

  Also thanks to Damien Cassou for reporting an intermediate problem
  with 'avy' in issue 177; a problem that was eventually addressed by
  Nicolas De Jaeghere in merge request 31 (cited above):
  <https://gitlab.com/protesilaos/modus-themes/-/issues/177>.

+ Optimised the colour combinations used by 'avy' to improve the
  distinction between consecutive characters.

+ Reduced the brightness of EWW certificate faces, as they would attract
  disproportionate attention to themselves.

+ Reworked all EWW text field and button faces to look more like what
  they are supposed to.

+ Removed the slant and distinct foreground from the 'org-quote' face,
  as they would interfere with emphasis within the quote block.  Thanks
  to Farasha Euker for the feedback in issue 171:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/171>.

+ Reduced the intensity in colouration of 'org-code' and 'org-macro' in
  order to avoid exaggerations and prevent their compounding effect in
  technical documents that include a high concentration of those faces.
  They still retain their overall character and continue to look like
  variants of 'org-verbatim'.

+ Extended support for Selectrum's new 'selectrum-quick-keys-highlight'
  and 'selectrum-quick-keys-match'.

+ Adjusted a few bongo faces for improved consistency and a more
  pleasant result overall.  Quote from commit 07224cda08:

      Refine bongo faces for consistency

      The previous design was meant to keep the track fields distinct
      from each other.  However the use of yellow was not good
      aesthetically: it does not fit with the rest of the theme.

      Upon further experimentation, I realised that the album field
      (yellow) is only present when the artist and title fields are also
      available: first is the title, then the artist, and finally the
      album.  This is true even with 'bongo-join-inserted-tracks' set to
      a non-nil value.  So changing the face from yellow to a neutral
      value is safe.

      The other two faces are adapted to look better in the new context.

+ Made more command prompt faces respond to changes in the variable
  'modus-themes-prompts'.  This concerns faces from the groups cider,
  circe, erc, indium, rcirc.

+ Refashioned typescript faces, making them more prominent by default,
  while also exposing them to the value of 'modus-themes-syntax'.

+ Revised the style of 'info-colors-ref-item-command'.  This makes
  commands look the same as functions, which is technically correct.  It
  also predicates the exact style on the value of the variable
  'modus-themes-syntax'.

+ Made all enh-ruby-mode faces adapt to 'modus-themes-syntax'.  Same for
  julia.

+ Reconfigured all ztree faces for stylistic consistency.  The
  'ztreep-diff-model-add-face' now responds to the 'deuteranopia' value
  that can be passed to 'modus-themes-diffs'.

+ Appended the ':extend t' attribute to 'gnus-summary-cancelled' and
  'gnus-summary-selected'.  These are only noticeable on Emacs 28
  following commit 88409b21c2 in emacs.git.

+ Tweaked all faces of 'highlight-changes-mode' to better deliver on the
  intent of that mode.

+ Opted to unconditionally render all 'dired-async' faces in a bold
  typographic weight, instead of basing them on a non-nil value for
  'modus-themes-bold-constructs'.  Also changed 'dired-async-message' to
  a blue foreground, which further improves the themes' performance for
  red-green colour deficiency.

+ Adjusted the colours of some 'notmuch-crypto-*' faces to better convey
  their meaning.

+ Removed remaining conditional logic for underline styles in some
  spell- and linter- related faces to ensure that all such cases are
  controlled by the variable 'modus-themes-lang-checkers' (building on
  work that had been done in the past).

+ Stopped changing 'keycast-key' to match the modeline style, as that
  diluted the meaning of the variable 'modus-themes-mode-line'.

+ Tweaked calendar and diary faces for stylistic effect, except for the
  'diary' face which has been converted from a green to a blue variant
  for the purposes of coping with cases of red-green colour deficiency.

Miscellaneous
-------------

+ Clarified the changes in the backward-incompatible transition from
  version 0.13.0 of the themes to >= 1.0.0.  Thanks to Damien Cassou for
  reporting the absence of easy-to-find information in issue 174:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/174>.

+ There were three point releases after 1.2.0 which refined certain
  aspects of the themes' packaging so that they could work both as
  built-in themes for Emacs as well as in package format via the likes
  of GNU ELPA.  Those issues were eventually resolved by Basil
  L. Contovounesios:

  - Issue 162: <https://gitlab.com/protesilaos/modus-themes/-/issues/162>.
  - Emacs bug#45068: <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=45068#218>.

+ Rewrote the 'modus-themes-headings' variable's declaration to improve
  its presentation in Custom interfaces.  Thanks to Mauro Aranda for
  submitting the patch for commit 1c60927ebd.

+ Applied the ':format' keyword to all 'defcustom' forms, based on the
  aforementioned patch.  This should make all options look better in the
  various Custom interfaces.  Thanks to Mauro Aranda for the feedback in
  issue 163: <https://gitlab.com/protesilaos/modus-themes/-/issues/163>.

+ Refined the colour values 'bg-alt' and 'bg-dim' in 'modus-vivendi' to
  improve their instantiation on Textual User Interfaces.  In
  particular, recalibrated the blue channel of light so that when the
  TUI cannot render the colour directly, it defaults to a gray value
  instead of a dark blue.

+ Added a "Last-Modified" meta header to modus-themes.el, with gets
  updated automatically and uses a timestamp.  This helps users who
  track the themes' git repo directly.  Thanks to Togan Muftuoglu for
  the feedback in issue 168:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/168>.

+ Expanded the palette of each theme with accent values that are
  reserved for use in the tab-bar.  Those are used by the newly
  supported 'tab-bar-groups' package.

+ Recalibrated a few colour combinations to improve their resulting
  legibility.  The changes should not be noticeable to the untrained
  eye.  Interested parties can consult commit 349ea4a943.

+ Tweaked the hueness of the 'yellow-active' colour of 'modus-operandi'.

Thanks once again to everyone involved!

Modus themes version 1.2.0

By Protesilaos Stavrou <info@protesilaos.com> on 2021-03-04

This entry records the changes introduced to the project since the
publication of version 1.1.0 (2021-01-24).  There have been close to 100
commits in the meantime.

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 (the WCAG AAA standard).

As the official manual is referenced several times throughout this log,
make sure to store its URL: <https://protesilaos.com/modus-themes>.  Or
read it from Emacs' Info reader by evaluating this form:

    (info "(modus-themes) Top")

If you are coming from older versions, please consult the change log
entry for version 1.0.0 with regard to the breaking changes that were
introduced.

Prior notice: Upgrading the themes in Emacs28 and GNU ELPA
----------------------------------------------------------

Emacs28, the current development target, now includes a 'require-theme'
function.  It is a prerequisite to upgrading the Modus themes to their
current version.  Prior to the definition of that function, the themes
could not transition from their 0.13.0 version to >=1.0.0.  Special
thanks to Basil L. Contovounesios for making it happen, as well Mauro
Aranda and Eli Zaretskii for their feedback and support.

Expect the Modus themes in upstream Emacs to be updated shortly after
the publication of this document.

GNU ELPA currently ships version 0.12.0 of the two standalone packages
'modus-operandi-theme' and 'modus-vivendi-theme'.  This will change in
the immediate future, as a new 'modus-themes' package will succeed them.
That new package will be built directly from emacs.git, as it must now
become a ':core' entity instead of being listed as an ':external' one.

Again, expect a patch to be applied to elpa.git shortly after this
document goes live.

Customisation options
---------------------

[ All variables and their values are documented in the themes' manual.
  The default value is always nil. ]

+ The new boolean 'modus-themes-subtle-line-numbers' variable will make
  the effect of 'display-line-numbers-mode' more subtle when set to a
  non-nil value.  It removes the underlying background of the unfocused
  lines while toning down their foreground.

+ The 'modus-themes-diffs' variable now accepts a 'deuteranopia' value.
  This optimises for red-green colour deficiency in all modes that show
  diffs (diff-mode, ediff, Magit...).  In practice, all instances of
  green are replaced with appropriate blue hues.  For more on the
  matter, read the report which also includes pictures:
  <https://protesilaos.com/codelog/2021-02-25-modus-themes-diffs-deuteranopia/>.

+ The 'modus-themes-syntax' variable now reads 'faint-yellow-comments'
  as a valid value.  This has the same scope as the existing 'faint'
  value with the added effect of assigning a yellow tint to comments: it
  tones down the saturation of colours that apply to code syntax
  (standard font-lock faces and others inheriting from them).

+ The 'modus-themes-links' variable is expanded to accept the new value
  of 'neutral-underline-only': it removes the foreground from the link
  and draws a neutral gray underline below it.

Refinements to existing packages or face groups
-----------------------------------------------

+ Refashioned all faces that pertain to emails, including Gnus, Mu4e,
  Notmuch, and the standard 'message.el' library.  This concerns the
  colours that apply to the message header keys and their values, as
  well as quote levels.

  - Introduced more contrasting hues for headings and made more
    considerate use of bold typography.  The new colour combinations are
    better suited for the task of delivering a sense of structure;
    structure that is at once effective and subtle.

  - Applied less intense colours throughout all quotation levels.

  - Revised the sequencing of hues in quotation levels to allow distinct
    levels to stand out more without relying on excessive saturation.

  - Aligned the styling of Notmuch header dates with their counterparts
    in other similar contexts, in pursuit of theme-wide consistency.

+ Rewrote the faces of EBDB to achieve a better sense of structure.

+ Refined the colour combinations of change-log and log-view buffers to
  make it easier to discern distinct elements.

+ Tweaked the colours of certain Elfeed constructs to improve the
  overall presentation of its search buffers.

+ Changed the colour combinations of 'M-x re-builder' to amplify the
  distinction between the matching regexp groups while still reducing
  their overall intensity.

+ Reconfigured the 'diff-changed' face to always extend its background
  to the edge of the window.  Such "changed" lines are visible in
  'diff-mode' buffers when the command 'diff-unified->context' is
  invoked.

+ Tweaked the colour combinations of ancillary faces in diff buffers
  when the variable 'modus-themes-diffs' is set to the value 'fg-only'.
  In particular:

  - Removed the subtle background from the diff hunk headings and changed
    their colour to ensure good visibility---guarantees a sense of
    structure.

  - Made the context lines inherit the default foreground colour (pure
    black/white), so that it contrasts better with red, green, and
    yellow text.

  - Applied an accented foreground to the diff header.  This is to
    ensure that it is not mistaken for a diff hunk's context.

  All these guarantee that the foreground-only highlights in line-wise
  differences draw more attention to themselves.

+ Aligned all the standard hi-* faces with their default aesthetics.
  Those are used by commands such as 'highlight-symbol-at-point'.
  Thanks to Philip K. for the valuable feedback in issue 157:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/157>.

+ Removed obsolete Consult faces and added new ones, so as to remain in
  sync with the latest developments in that project.  Thanks to Daniel
  Mendler (Consult's maintainer) for reporting the inconsistency in
  issue 155: <https://gitlab.com/protesilaos/modus-themes/-/issues/155>.

  - 'consult-preview-line' now retains fontification on the current
    line, instead of applying its own foreground.

  - 'consult-narrow-indicator' is refashioned to be colour-coded in a
    consistent way with 'consult-async-split', as both denote the
    delineation of a given scope.

  - 'consult-imenu-prefix' contrasts better with text on its current
    line, while it adapts to possible customisations performed on the
    Consult front.

+ Expanded the coverage of 'marginalia' faces to two include
  'marginalia-char' and 'marginalia-type'.  This is done in the interest
  of internal consistency between the elements of this set, as their
  defaults were also accessible (they inherit from standard faces that
  we already support).

+ Opted to render the Notmuch logo in a neutral gray backdrop.  This was
  deemed necessary as the logo is an immutable image file that consists
  of black and white strokes.  Black and white are the main background
  values of 'modus-vivendi' and 'modus-operandi' respectively, which
  could lead to confusion.  The neutral gray ensures that the logo is
  visible at all times.  Thanks to Utkarsh Singh for the feedback in
  issue 122: <https://gitlab.com/protesilaos/modus-themes/-/issues/122>.

+ Refined the dedicated colour values used for diff hunk headings, as
  seen in diff-mode buffers or Magit.  The new colours yield text that
  is easier to read by slightly toning down the combined intensity of
  background+foreground.

+ Removed the subtle background of 'diff-header' and 'diff-file-header'.
  The header's foreground and textual representation suffice to render
  it distinct in its context.

+ Tweaked 'org-agenda-structure' and 'org-scheduled' to enhance the
  usability of Org Agenda buffers.

  - Made 'org-agenda-structure' use the largest possible height that we
    expose to users: 'modus-themes-scale-5'.

  - Re-calibrated the hueness of 'org-scheduled' and amplified its
    saturation, in order to better convey the meaning of a scheduled
    task.

  Thanks to Morgan Smith for the valuable feedback in issue 153:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/153>.

+ Tweaked the faces of the 'bongo' package to enhance the
  distinctiveness of the constructs they style.

+ Adjusted the overall aesthetic of calendar faces in the interest of
  theme-wide consistency.

+ Aligned the visual metaphors of 'org-code' with those of 'org-macro'
  and 'org-verbatim', by ensuring that a subtle background is present
  behind the affected text, while the foreground conforms with the norms
  of the 'modus-themes-no-mixed-fonts' customisation option.

+ Made quoted text in Info buffers look the same as 'org-verbatim' and
  Markdown's inline code.

+ Instructed the faces of 'info-colors' to inherit from appropriate
  font-lock faces.  This guarantees that everything works as intended
  with the various values of 'modus-themes-syntax'.

+ Refined the language tag of Markdown fenced blocks so that it does
  attract unwarranted attention while delivering on its intended
  purpose.

+ Rendered explicit the slant of ace-window hints, guaranteeing that it
  does not inherit from the underlying text.  Thanks to Nicolas De
  Jaeghere for the patch:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/27>.

  [ Some more changes have been discussed, but those require tweaks to
    the upstream package. ]

+ Ensured that the 'org-tree-slide-header-overlay-face' never draws an
  overline when the variable 'modus-themes-headings' includes a relevant
  setting for heading level 1.  Such as with the following example (all
  customisation options are documented in the themes' manual):

    (setq modus-themes-headings
          '((1 . section)
            ...))

+ Extended support for the new 'tab-line-tab-inactive-alternate' face as
  that occurs in Emacs28 (current development target).  It comes into
  effect when the variable 'tab-line-tab-face-functions' includes a
  value of 'tab-line-tab-face-inactive-alternating'.

Newly supported packages
------------------------

+ bbdb :: Thanks to Nicolas De Jaeghere in issue 128:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/128>.

+ mmm-mode :: Thanks to Davor Rotim for the feedback in issue 161:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/161>.

+ quick-peek :: Thanks to Burgess Chang for the feedback in issue 151:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/151>

+ selectrum-prescient :: This new package was brought to my attention by
  Manuel Uberti.  The intent is to phase out the faces in Selectrum,
  namely 'selectrum-primary-highlight', 'selectrum-secondary-highlight',
  though those will still be supported by the Modus themes for the
  foreseeable future.

+ shortdoc

+ spray

+ terraform-mode :: Thanks to Kevin Fleming for the feedback in issue
  159: <https://gitlab.com/protesilaos/modus-themes/-/issues/159>.

+ vc-dir (Emacs28)

Theme-related contributions to the wider community
--------------------------------------------------

+ Contributed the faces for 'vc-dir' in Emacs28 and applied them to all
  VC backends: <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=46358> and
  <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=46745>.

+ Contributed a new face and some related tweaks to Emacs'
  'shortdoc.el': <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=46748>.

+ Added faces to the 'tab-bar-echo-area.el' package:
  <https://github.com/fritzgrabo/tab-bar-echo-area/pull/2>.

+ Reported issue that led to the review of the header face in
  'org-tree-slide': <https://github.com/takaxp/org-tree-slide/issues/38>.

+ Helped refine the faces of the 'rlist.el' package:
  <https://gitlab.com/mmemmew/rlist/-/commit/386f506d0110bebedd3a48ff972adba96e2232eb>.

Documentation updates
---------------------

+ Wrote about the indirect support for the 'goggles' package.  I had
  helped write its faces, as was documented in the changelog for version
  1.1.0 of the themes.  Thanks to Manuel Uberti for bringing this to my
  attention in issue 158:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/158>.

+ Explained that any changes to 'custom-theme-load-path' and/or
  'custom-theme-directory' should be performed before the themes are
  loaded.  Thanks to Adrian Manea for the feedback in issue 156:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/156>.

+ Included the symbol 'bg-only' in the 'modus-themes-diffs' section of
  the manual.  Thanks to user "iSeeU" for reporting the omission:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/154>.

+ Expanded the manual's entry on the semantics of the optional heading
  scale used by the themes (the variables 'modus-themes-scale-[1-5]').
  The values 1-4 apply to regular headings, with 4 being the largest on
  the scale.  While 'modus-themes-scale-5' is reserved for special
  headers, such as Org '#+title:' or the Org Agenda's structure.  Recall
  that those variables only come into effect if the boolean variable
  'modus-themes-scale-headings' is set to a non-nil value (it is nil by
  default).

+ Made several changes to the 'modus-themes.org' file in an effort to
  improve the accuracy of the generated Texinfo markup.  Thanks to Glenn
  Morris and Richard Stallman for their valuable feedback in
  <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=45143>.

+ Recorded a note in the manual on the intended colouration of
  backgrounds applied by 'mmm-mode'.  It explains what the constraints
  are from an accessibility standpoint and how users can configure
  things locally for more colourful, yet inaccessible, backgrounds.
  Thanks to Davor Rotim for the valuable feedback in issue 161:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/161>.

+ Refined the manual's note on prism.el, simplifying the code samples
  and clarifying the commentary.

+ Wrote indices for concepts, variables, functions, which are rendered
  in the Info manual.

+ Elaborated on the possibility---and relative merits---of implementing
  a theme-agnostic hook for advanced face configurations, as opposed to
  relying on 'modus-themes-after-load-theme-hook'.  Thanks to Daniel
  Mendler for the valuable feedback in issue 131:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/131>.

Miscellaneous
-------------

+ Rewrote the documentation string of the 'deftheme' declaration of
  'modus-operandi' and 'modus-vivendi'.

+ Provided links to the Info nodes that discuss each of the 'defcustom'
  declarations.

+ Wrote doc strings for every custom face that the themes define.

1.1.1

Refer to tag 1.1.0 for a complete change log.

Modus themes version 1.1.0

By Protesilaos Stavrou <info@protesilaos.com> on 2021-01-24

This entry records the changes introduced to the project since the
publication of version 1.0.0 (2020-12-05).  There have been around 150
commits in the meantime, qualifying this as one of the largest releases
to date.

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).

As the official manual is referenced several times, make sure to store
its URL: <https://protesilaos.com/modus-themes>.

If you are coming from older versions, please consult the change log
entry for version 1.0.0.

Overview
--------

+ We have brought back the options that were present in version 0.13.0
  or earlier which allowed users to override colors for either---or
  both---of Modus Operandi and Modus Vivendi.  Compared to the old
  mechanism, the new one is more robust and should work regardless of
  whether users run byte compiled code or not.  This is considered and
  advanced, "do-it-yourself" pathway to theme customisation.  It is
  discussed at length in the manual.

+ The new 'modus-themes-with-colors' macro makes it possible to read
  palette variables from the active theme and, thus, pass them to
  arbitrary functions or variables.  Again, this is part of the advanced
  customisations that are covered in the manual.

+ Several of the existing customisation options provide new stylistic
  variants, further expanding their utility.  While there are some new
  customisations altogether.  Combined with the above, we provide the
  infrastructure that allows the themes to adapt gracefully to a variety
  of circumstances and cover a broad range of demands.

+ More packages are added to the already comprehensive list of supported
  face groups.

+ Some of the supported faces have benefited from further, albeit
  subtle, refinements, demonstrating our commitment to consistency as
  well as our attention to detail.

+ Two reports on such "further refinements" were published on the code
  log section of protesilaos.com: <https://protesilaos.com/codelog>.

+ We have more people contributing to the project (and assigning
  copyright to the FSF---as the themes are part of Emacs) and newer
  users reporting issues.  Also, there is anecdotal evidence from
  several sources on an increased interest to make new or existing faces
  accessible by default (such as by copying colour combinations from the
  themes).

New customisation options
-------------------------

+ The existing 'modus-themes-mode-line' variable now supports three new
  borderless styles: 'borderless', 'borderless-3d', 'borderless-moody'.

  - The 'borderless' value uses the same colors as the default (nil
    value), but removes the border effect.  This is done by making the
    box property use the same color as the background, effectively
    blending the two and creating some padding.

  - The 'borderless-3d' and 'borderless-moody' approximate the '3d' and
    'moody' options respectively, while removing the borders.  However,
    to ensure that the inactive modelines remain visible, they apply a
    slightly more prominent background to them than what their
    counterparts do (same inactive background as with the default).

  The complete list of options:

    1. nil (default)
    2. 3d
    3. moody
    4. borderless
    5. borderless-3d
    6. borderless-moody

+ 'modus-themes-lang-checkers' provides several styles for spell
  checkers and code linters with regard to how they underline text.  The
  default (nil) is to use a colour-coded wavy underline, without
  changing the foreground of the affected text.  Other options include
  the ability to set a straight underline and to control the saturation
  of the foreground, while one also provides for a change in the
  background of the text in question.  The valid symbols are as follows
  (read the manual for more on the matter):

    1. nil (default)
    2. straight-underline
    3. subtle-foreground
    4. subtle-foreground-straight-underline
    5. intense-foreground
    6. intense-foreground-straight-underline
    7. colored-background

+ The 'modus-themes-org-habit' lets users pick between three styles for
  the 'org-habit' table: (1) nil (the default), which uses a total of
  eight colours, (2) 'simplified' which reduces the effective colours to
  four, while applying less saturated hues, and (3) 'traffic-light'
  which bring the colour count to three, thus blending the "clear" and
  "ready" states for workflows where the distinction between is not
  useful.

  Please read the manual for a more detailed description of those
  variants.

  Thanks to Gustavo Barros for suggesting the idea, providing user
  feedback on stylistic choices, as well as sharing insights on the
  workflow that made the 'traffic-light' style possible:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/135>.

+ 'modus-themes-variable-pitch-ui' when set to a non-nil value applies a
  proportionately spaced typeface (controlled by the 'variable-pitch'
  face) to the User Interface, specifically the mode line, header line,
  and tab-{bar,line}.

+ The existing 'modus-themes-links' variable now has a colourless
  stylistic alternative: 'underline-only'.  The available styles:

    1. nil (default)
    2. faint
    3. neutral-underline
    4. faint-neutral-underline
    5. no-underline
    6. underline-only

+ The existing 'modus-themes-prompts' variable has two new grayscale
  styles: 'subtle-gray', 'intense-gray'.  Furthermore, their old
  'subtle' and 'intense' values have more informative aliases in the
  form of 'subtle-accented' and 'intense-accented'.  All available
  values:

    1. nil (default)
    2. subtle-accented ('subtle' remains for backward-compatibility)
    3. intense-accented ('intense' remains for backward-compatibility)
    4. subtle-gray
    5. intense-gray

+ The existing 'modus-themes-headings' variable now accepts two new
  styles: 'no-color', 'no-color-no-bold'.  All stylistic variants:

    1.  nil (default fallback option---covers all heading levels)
    2.  t (default style for a single heading, when the fallback differs)
    3.  no-bold
    4.  line
    5.  line-no-bold
    6.  rainbow
    7.  rainbow-line
    8.  rainbow-line-no-bold
    9.  highlight
    10. highlight-no-bold
    11. rainbow-highlight
    12. rainbow-highlight-no-bold
    13. section
    14. section-no-bold
    15. rainbow-section
    16. rainbow-section-no-bold
    17. no-color
    18. no-color-no-bold

  Please read the manual for instructions on how to apply those
  universally or on a per-level basis.

Added support for packages
--------------------------

+ cfrs (used by treemacs)
+ cperl-mode
+ diredc

+ display-fill-column-indicator-mode.  Thanks to Gustavo Barros for the
  feedback: <https://gitlab.com/protesilaos/modus-themes/-/issues/148>.

+ evil-snipe.  Thanks to Peter Wu for the feedback:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/139>.

+ isl (isearch-light).  Thanks to Manuel Uberti for the feedback:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/144>.

+ marginalia
+ org-tree-slide
+ recursion-indicator

+ solaire.  Thanks to CsBigDataHub1 for the feedback:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/137>.

Refinements to already supported faces
--------------------------------------

+ Reviewed the 'rainbow-delimiters' faces.  Everything is documented in
  a separate report (with screenshots).  The short version is that we
  pay close attention to detail and are willing to go to great lengths
  in pursuit of improving the overall user experience:
  <https://protesilaos.com/codelog/2020-12-27-modus-themes-review-rainbow-delimiters/>.

+ Updated the dedicated colours for 'whitespace-mode'.  The background
  should now be easier to discern.  Also removed any remaining
  inconsistencies.  Thanks to Toon Claes for the feedback:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/149>.

+ Refined the faces of regexp constructs for strings affected by certain
  values passed to the 'modus-themes-syntax' option.  This is done to
  disambiguate the backslashes and grouping delimiters from the rest of
  the string.  The relevant values for 'modus-themes-syntax' are:

  - green-strings
  - yellow-comments-green-strings
  - alt-syntax
  - alt-syntax-yellow-comments

  The default colour for strings is blue, while regexp faces are yellow
  and red, whereas in those variants the strings become green, hence the
  need to make regexp faces more distinct (blue and magenta contrast
  better with green and also between themselves, thus matching the
  alternative aesthetics).

+ Reviewed dictionary.el faces (which ships with Emacs 28):

  - Made 'dictionary-reference-face' look like all other links.

  - Removed all properties from 'dictionary-word-definition-face':
    the default sets a font family, which can create inconsistencies.

  - Converted 'dictionary-word-entry-face' into comment-like text.

+ Refined and expanded the faces of Consult.

  - Made its grep commands look the same as those of all other grep
    tools.

  - Ensured that line number previews, such as for the 'consult-line'
    command use their own style of a subtle foreground instead of
    inheriting from the 'line-number' face.  This is to avoid cases
    where previewed numbers and actual line numbers could be conflated
    for one another.

  - Removed the foreground pertinent to 'consult-imenu-prefix', as its
    bold weight combined with the structure of Imenu indices was deemed
    sufficient to differentiate it from actual 'consult-imenu' targets.

+ Eliminated exaggerations in the use of colour for various 'which-key'
  faces.

+ Removed the needless background from the 'log-view-commit-body' face.
  This is a new face that ships with Emacs 28 (its inclusion upstream
  was documented in the last changelog entry).

+ Applied a subtle background to the 'log-view-message' face, in the
  interest of improving the usability of its interface, in particular,
  to contribute to heightened situational awareness while invoking
  'log-view-toggle-entry-display' in buffers such as those produced by
  'vc-print-root-log'.

+ Introduced a neutral background for all 'outline-minor-faces' instead
  of merely mirroring the style of 'outline-mode' headings.  This is
  because it can sometimes be hard to tell whether 'outline-minor-mode'
  is active, provided certain fairly common configurations in the
  'modus-themes-headings' user option (refer to the manual for all
  customisation options).

+ Tweaked 'diff-mode' headings.

  - Adjusted the values of the dedicated colours for diff headings in
    order to amplify their relative contrast.

  - Assigned a bold typographic weight to the 'diff-hunk-header' face so
    as to enforce a greater sense of structure.

  - Instructed 'diff-function' to inherit 'modus-theme-diff-heading' in
    order to eliminate exaggerations in colouration.

+ Removed unnecessary underline from 'selectrum-current-candidate'.
  Thanks to Daniel Mendler for the feedback:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/132>.

+ Made 'counsel-outline' inherit from the underlying Org faces.  Also
  corrected the style of 'counsel-outline-default' to use the main
  foreground colour.  Thanks to Gustavo Barros for the feedback:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/134>.

+ Prevented headings, ultimately governed by the 'modus-themes-headings'
  user option, from inheriting the 'default' face as that could lead to
  unintended consequences, such as by retaining a background colour when
  none was expected.

+ Refashioned all faces that specified a foreground value of 'fg-alt' to
  inherit the 'shadow' face instead ('fg-alt' is the colour that is
  used, for example, in code comments by default).  This makes it
  possible for users to enact change across the theme just by tweaking
  'shadow'.

+ Fixed 'ruler-mode' text scaling adjustment, to make it cope well with
  'text-scale-adjust' and relevant commands.  Also introduced minor
  stylistic changes to the remainder of the 'ruler-mode' faces.

+ Eliminated the potentially problematic form of ':foreground nil' from
  the 'org-ellipsis' face.  In such cases it is always better to either
  specify no foreground whatsoever, or declare an unspecified value.

Patches from the community
--------------------------

Remember that the themes are part of Emacs and, thus, contributions that
exceed a cumulative total of ~15 lines require the assignment of
copyright to the Free Software Foundation.  Please consult the themes'
manual on the matter.

+ Nicolas De Jaeghere added support for 'exwm-floating-border-color':
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/15>.

+ Anders Johansson added support for 'helm-fd-finish':
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/16>.

+ Carlo Zancanaro fixed misquoting of 'tuareg-font-lock-multistage-face':
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/17>.

+ Xinglu Chen expanded Notmuch support to all its remaining faces:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/18>.

+ Kostadin Ninev added support for Dired+:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/19>.

+ Nicolas De Jaeghere expanded the supported items of 'pdf-faces'.  Also
  added an entry to the manual pertaining to link hints and the
  requisite setup:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/20>.

+ Nicolas De Jaeghere wrote the new 'modus-themes-with-colors' macro,
  which is documented at length in the manual:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/21>.

+ Nicolas De Jaeghere set up the infrastructure that grants users the
  ability to override palette colors; an option that was removed in the
  transition from version 0.13.0 to 1.0.0.  The relevant variables are
  'modus-themes-colors-operandi', 'modus-themes-colors-vivendi' (again,
  consult the manual):
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/23>.

+ Nicolas De Jaeghere deleted the 'modus-themes-core.el' file and merged
  its contents into the main 'modus-themes.el' library:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/24> and
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/25>.

+ Nicolas De Jaeghere made the 'compilation-info' face consistent with
  other compilation faces in terms of their optional bold weight:
  <https://gitlab.com/protesilaos/modus-themes/-/merge_requests/26>.

Any remaining faults that may exist, despite our best intentions to
remove them, are those of the maintainer and will be addressed as soon
as they are identified.

FSF copyright status:

| Full name           | Copyright    |
|---------------------+--------------|
| Anders Johansson    | covered      |
| Carlo Zancanaro     | not required |
| Kostadin Ninev      | covered      |
| Nicolas De Jaeghere | covered      |
| Xinglu Chen         | not required |

Theme-related contributions to the wider community
--------------------------------------------------

+ Helped address an incomplete colour value in 'org-transclusion-block':
  <https://github.com/nobiot/org-transclusion/issues/41>.

+ Contributed to the formation of the zebra striping of 'embark':
  <https://github.com/oantolin/embark/commit/bb4ae2a666ab1f4a307edd71f77bcbb90fb25cef>.

+ Reviewed the faces of 'goggles':
  <https://github.com/minad/goggles/commit/d6e584a2c9487d3df4aee818c43485e437cb87ef>.

+ Helped raise awareness about refactoring 'org-tree-slide-header-overlay-face':
  <https://github.com/takaxp/org-tree-slide/issues/38>.

+ Reported an issue for Moody that would affect the subset of Emacs 28
  users who enable the new 'mode-line-compact' option:
  <https://github.com/tarsius/moody/issues/28>.

+ Did the same for Keycast: <https://github.com/tarsius/keycast/issues/13>.

+ Defined the new 'perl-non-scalar-variable' in upstream Emacs:
  <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=45840>.

Miscellaneous
-------------

+ Created a new palette subset for "graph" colours, as none of the
  existing paradigms would suffice for cases where faithfulness to
  colour huenesss is important.  Those are currently used by
  'modus-themes-org-habit'.

+ Ensured that theme functions which need to produce an error message do
  so by calling 'error' instead of 'user-error'.

+ Added a 'modus-themes-load-themes' function that users can add to
  their init files.

+ Expanded the project's git repo README file with a sample
  'use-package' configuration.

+ The previous two points followed from an inquiry into the subtleties
  between 'enable-theme' and 'load-theme'.  Those are now documented at
  length in the manual.

+ Added screenshots to the web page that holds the official manual.
  Thanks to Damien Cassou for the feedback:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/147>.

+ Swapped the values of 'cyan-faint' and 'cyan-alt-faint' for Modus
  Vivendi.

+ Tweaked 'font-lock-doc-face' and 'font-lock-type-face' variations when
  "faint syntax" is in effect: (setq modus-themes-syntax 'faint).

+ Refined 'font-lock-doc-face' for when modus-themes-syntax is given a
  value of either 'yellow-comments-green-strings' or 'green-strings'.
  The changes are minor when treated in isolation, though they have
  helped improve the overall consistency of the end result: the gestalt.

+ Reviewed select "faint" colours for both Modus Operandi and Modus
  Vivendi.  The technicalities are discussed in a complete report:
  <https://protesilaos.com/codelog/2021-01-11-modus-themes-review-select-faint-colours/>.

+ Ensured that (setq modus-themes-syntax 'alt-syntax) and its "yellow
  comments" variant are more truthful to their intended style, by
  eliminating any exaggerations in the use of colour.

+ Adjusted the saturation of the green-alt value of Modus Vivendi.

+ Updated the manual to reflect all of the aforementioned.

Thanks once again to everyone who contributed patches or reported an
issue.  This has been yet another period of intense work; work which
helps solidify the Modus themes as (i) uncompromisingly accessible in
accordance with the highest legibility standard, (ii) highly
customisable in true Emacs fashion, (iii) thoroughly comprehensive in
terms of face coverage, and (iv) meticulously designed throughout.

Modus themes version 1.0.2

Minor tweaks to the manual to ensure that the right instructions are
provided for those who install the themes manually or will be using the
version that is shipped with Emacs.

For all the rest, please refer to the release notes for version 1.0.0:
<https://protesilaos.com/codelog/2020-12-05-modus-themes-1-0-0/>.

Modus themes version 1.0.0

By Protesilaos Stavrou <info@protesilaos.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/modus-themes>.

Overview of major changes
=========================

0. 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).

1. The code base has been refactored.  The two themes, Modus Operandi
   (light) and Modus Vivendi (dark), derive from the same source.

2. The refactoring makes it possible to distribute the two themes as
   part of a single package.  You can find 'modus-themes' on MELPA, with
   other archives and core Emacs following suit soon thereafter (the
   Modus themes are built into Emacs since their version 0.12.0).

3. The 'modus-operandi-theme' and 'modus-vivendi-theme' packages 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.

4. To avoid surprises, the refactored code is in the 'main' branch which
   becomes the default henceforth.  The 'master' branch, from where all
   prior releases were built, is thus deprecated.  Existing installs of
   'modus-operandi-theme' and/or 'modus-vivendi-theme' must 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.el' must make sure that they pull from the
     'main' branch.  This may also be the case for other such tools,
     though I have not had the time to test them all.

5. The refactoring introduces a unified customisation framework.  Now
   all user-facing variables are named 'modus-themes-*' instead of
   'modus-operandi-*' and '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

6. The themes now provide common user-facing functions.

   + 'modus-themes-load-operandi' and 'modus-themes-load-vivendi' can 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-toggle' interactively 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-color' returns the colour value of a symbol in the
     alists that hold the themes' palettes.  The alists are
     'modus-themes-colors-operandi' and 'modus-themes-colors-vivendi'.
     'modus-themes-color' always 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-alts' occupies 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-operandi' and the second is
     for 'modus-vivendi'.

   + 'modus-themes-wcag-formula' implements the WCAG formula to measure
     a colour value's relative luminance.  While 'modus-themes-contrast'
     applies 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).

Customisation options
=====================

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

    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:

1. modus-themes-syntax

   * nil (default)
   * faint
   * yellow-comments
   * green-strings
   * yellow-comments-green-strings
   * alt-syntax
   * alt-syntax-yellow-comments

   (supersedes options for "faint syntax" and "comments")

2. modus-themes-links

   * nil (default)
   * faint
   * neutral-underline
   * faint-neutral-underline
   * no-underline

   (supersedes options for "no underlines")

3. modus-themes-paren-match

   * nil (default)
   * intense
   * subtle-bold
   * intense-bold

   (supersedes options for "intense paren match")

4. modus-themes-region

   * nil (default)
   * no-extend
   * bg-only
   * bg-only-no-extend

Furthermore, the 'modus-themes-diff' has a new option to choose from:
the symbol '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
====================================

+ consult
+ macrostep
+ make-mode
+ pdf-tools
+ popup
+ shr
+ sieve-mode

(remember that the list of supported packages is already comprehensive)

Thanks to:

+ Adam Spiers for bringing 'macrostep' to 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 calendar' are 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-mode' now 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-mode' has 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's 'swiper-isearch' command 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-posframe' is more noticeable.  Thanks to Pete
  Kazmier: <https://gitlab.com/protesilaos/modus-themes/-/issues/126>.

+ The 'fringe' face no longer returns a nil background, which allows
  'dap-ui-controls-mode' to 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-builder' are less intrusive.

+ All the following now inherit from basic font-lock faces and thus
  benefit from options such as 'modus-themes-syntax':

  * geiser
  * nxml-mode
  * tuareg
  * web-mode
  * xah-elisp-mode

+ 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-face' uses a cyan hue instead of magenta.

+ 'magit-header-line-key' uses 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-date' now respects the 'modus-themes-no-mixed-fonts' option.
  Thanks to user "fleimgruber" for reporting the issue:
  <https://gitlab.com/protesilaos/modus-themes/-/issues/124>.

+ 'org-property-value' uses a slightly different shade of cyan.

+ 'dim-autoload' will always look like a regular comment.

+ The 'italic' face 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 'bold' face---just
  apply the same idea to the 'italic' face).

+ 'dictionary-reference-face' inherits from 'button' (as with all
  links).

+ Several comment-related faces beyond the basic ones work with
  'modus-themes-syntax' when that has an effect on the colour of
  comments.  The faces are:

  * git-commit-comment-file
  * git-commit-comment-heading
  * git-rebase-comment-hash
  * git-rebase-comment-heading

+ 'transient-value' is 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:

  * org-drawer
  * org-property-value
  * org-special-keyword

Theme-related contributions to the wider community
==================================================

+ Defined the 'log-view-commit-body' for 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-error' face for Emacs 28.1:
  <https://lists.gnu.org/archive/html/bug-gnu-emacs/2020-11/msg01328.html>.

+ Added the 'org-dispatcher-highlight' face 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>.

Miscellaneous
=============

+ The new default 'main' branch 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-syntax' customisation 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 'modus-themes' package.

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.

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!

Modus Operandi and Modus Vivendi version 0.12.0

By Protesilaos Stavrou <info@protesilaos.com> on 2020-08-26

This entry documents the set of changes since version 0.11.0
(2020-07-31).  There have been around 70 commits in the meatime, though
the sheer number may obfuscate the fact that a lot of work has gone into
this release.

As always, every change described here conforms with the accessibility
objective of the themes for a minimum 7:1 contrast ratio between
background and foreground values in their given combinations
(conformance with the WCAG AAA standard).

New customisation options
=========================

1 Completion Frameworks
-----------------------

The star of the show has to be the new option that refashions the
aesthetics of completion UIs: Helm, Icomplete, Ido, Ivy, Sallet,
Selectrum.  The 'modus-operandi-theme-completions' and
'modus-vivendi-theme-completions' accept the following symbols:

+ nil (default)
+ moderate
+ opinionated

Nil means that the overall presentation of the UI follows the patterns
established by its own source code.  For example, Ivy uses four distinct
background and foreground combinations of accented colours to highlight
the matching groups.  A grey background is added to denote the implicit
match between those groups.  So we choose to respect this metaphor,
while applying colours that conform with the accessibility goal of our
project.  Whereas Icomplete or Ido use subtle styles to present their
results.  Again, we remain faithful to their presentation.

With 'moderate', we apply nuanced background and foreground combinations
of accented colour values.  This will slightly tone down Helm, Ivy,
Sallet, Selectrum, while it will slightly adjust the looks of Icomplete
and Ido.

Whereas 'opinionated' has a more pronounced effect on the overall
aesthetics of the UI.  For the likes of Icomplete and Ido which are
subtle by default, this option will use intense combinations of
background and foreground colours.  They are the diametric opposite of
the nil value.  Whereas Helm, Ivy, Sallet, Selectrum, will use even more
subtle colours.  Again, they are farther away than their default looks.

These new options supersede the now-deprecated and more limited in scope
variables of prior releases:

+ modus-operandi-theme-intense-standard-completions
+ modus-vivendi-theme-intense-standard-completions

Thanks to the following people for their valuable feedback in issue 75:
https://gitlab.com/protesilaos/modus-themes/-/issues/75

+ Anders Johansson
+ Manuel Uberti
+ Shreyas Ragavan

2 Prompts
---------

The 'modus-operandi-theme-prompts' and modus-vivendi-theme-prompts' will
change the overall looks of minibuffer and shell prompts ('M-x shell' as
well as 'M-x eshell').  Their possible values are:

+ nil (default)
+ subtle
+ intense

Nil will only use a coloured foreground for the prompts' text.  Simple
and effective.

With 'subtle', the default foreground value is retained but is now
complemented by an appropriately tinted background.  The effect is more
noticeable than the default, though not by much.

While 'intense' applies a coloured background and foreground combination
that should clearly stand out from the rest of the context.

Thanks to Manuel Uberti for sharing feedback in issue 74:
https://gitlab.com/protesilaos/modus-themes/-/issues/74

3 Fringe visibility
-------------------

A new pair of symbols supersedes older variables:

+ modus-operandi-theme-visible-fringes ==> modus-operandi-theme-fringes
+ modus-vivendi-theme-visible-fringes  ==> modus-vivendi-theme-fringes

While the deprecated options were booleans, the current ones offer a
choice between the following:

+ nil (default)
+ subtle
+ intense

Nil means that the fringes have no distinct background of their own.
They still exist per the settings of 'fringe-mode', but can only be
discerned by tracking the negative space between the frame's or window's
edge and the buffer's effective boundaries.

The 'subtle' value will apply a greyscale background that is fairly
close to the default main background (pure white/black).  The fringes
are now visible.

As its name implies, 'intense' has a more pronounced effect than the
other values.  It also uses a greyscale background.

Review of already supported faces and colours
=============================================

1 Magit blame styles
--------------------

The headers that Magit's blame interface produces were difficult to tell
apart from their context.  A set of carefully selected colours now makes
sure that they are always distinct.  Some subtle background values are
used, in addition to other typographic elements.

Thanks to Damien Cassou for reporting this problem and for providing
valuable feedback that informed the final design.  Refer to issue 71:
https://gitlab.com/protesilaos/modus-themes/-/issues/71

2 Paren match colours
---------------------

The face that highlights the matching delimiter when 'show-paren-mode'
(or equivalent) is enabled uses two dedicated colours, whose names are:
'bg-paren-match' and 'bg-paren-match-intense'.  Those have been reviewed
to make them more obvious in various contexts and to improve their
overall consistency.

A report with relative contrast ratios is available on my website:
https://protesilaos.com/codelog/2020-08-09-modus-themes-paren-match/

I benefited from valuable feedback from Shreyas Ragavan in issue 70:
https://gitlab.com/protesilaos/modus-themes/-/issues/70

3 Mu4e faces
------------

Some faces were tweaked to make it easier to distinguish replied,
forwarded, and draft messages from other headers.  The changes are
fairly small in scope, but the effect should be that of an overall
improvement.

Thanks to Shreyas Ragavan for noticing these inconsistencies and for
their continued participation in addressing them.  See issue 69:
https://gitlab.com/protesilaos/modus-themes/-/issues/69

4 Notmuch message headings
--------------------------

A couple of inconsistencies with how notmuch would style email addresses
and folded messages were addressed.  The generic 'italic' face was also
tweaked in the process, removing the foreground it would falsely define.

Thanks to Damien Cassou for bringing these to my attention in issue 72:
https://gitlab.com/protesilaos/modus-themes/-/issues/72

5 hl-todo
---------

Let the special keywords of 'hl-todo-mode' use an optional slant, just
like code comments do.  This is to ensure that they feel part of their
context.

6 Magit general interface
-------------------------

Several faces were reviewed in the interest of colour harmony and to
address potential inconsistencies or exaggerations.  The most noticeable
change pertains to the log views, as we now use fewer accent values,
reducing whatever unnecessary "rainbow effect" may have existed.

7 VC commit logs
----------------

The presentation of 'vc-print-log' and 'vc-print-root-log' has been
reviewed to reduce the stark contrast between the colours it once used.
While the elements remain distinct, the differences between them are
more subtle, which is preferable when viewing long lists of
similar-looking patterns.

8 Powerline
-----------

The active and inactive minibuffers now use appropriate accented
backgrounds or foregrounds for some of their elements.  This makes them
better for their intended function.

Thanks to Shreyas Ragavan and tycho garen for their feedback in issue
73, which was actually about adding support for Spaceline.  It uses
Powerline as its dependency, so we eventually had to accommodate both of
them: https://gitlab.com/protesilaos/modus-themes/-/issues/73

Shreyas also helped by adding a short note in the README which informs
users of those two packages on how to tweak things when conducting tests
or changing themes.  See merge requests 9 and 10:

+ https://gitlab.com/protesilaos/modus-themes/-/merge_requests/9
+ https://gitlab.com/protesilaos/modus-themes/-/merge_requests/10

9 Latex sectioning
------------------

The themes will no longer affect the height of the Latex sectioning
faces.  This is because there already exists a variable that scales them
accordingly.

Thanks to Anders Johansson for providing insights in issue 77:
https://gitlab.com/protesilaos/modus-themes/-/issues/77

10 Transient pop-up menu
------------------------

Extended support for its new colour-coded faces that follow in the
footsteps of the 'hydra' package for visual semantics.

11 Miscellaneous
----------------

The following faces were refined:

+ 'org-formula' inherits from 'fixed-pitch' to ensure that it does not
  break table layouts when the user opts for a mixed-font setup (such as
  with 'M-x variable-pitch-mode').

+ 'bongo-elapsed-track-part' uses a more appropriate accented
  background.

+ 'symbol-overlay-default-face' is less intense than before.  This is in
  response to feedback I received from Manuel Uberti as an aside in
  issue 75: https://gitlab.com/protesilaos/modus-themes/-/issues/75

+ 'rectangle-preview' uses a slightly accented background, which
  distinguishes it from the highlighted region.  This is to denote a
  different state where the user is typing in some text.

+ 'diff-hl-change' now uses the more appropriate yellow colour instead
  of blue.  Yellow denotes "mixed changes" and, therefore, stands
  between "removed" (red) and "added" (green).  As it so happens, yellow
  is a colour that derives by mixing red with green.

New packages
============

The following are now explicitly supported by the themes:

+ org-table-sticky-header
+ pkgbuild-mode
+ semantic
+ spaceline

More faces or face groups that are defined:

+ git-rebase (magit)
+ doom-modeline-debug-visual
+ file-name-shadow
+ the faces used by Emacs 27's 'display-line-numbers-major-tick' and
  'display-line-numbers-minor-tick'
+ table-cell

Final notes
===========

There now exists an HTML version of the README, which will hopefully
make things easier for users: https://protesilaos.com/modus-themes/

Other changes are not user-facing.  For example, using 'pcase' instead
of 'cond' to make relevant expressions more succinct.  Or defining a
coloured underline in a more straightforward way.  No need to document
them at length.

While this release introduces customisation options, it feels as though
the themes are approaching a stable state.  We know what works, we have
a comprehensive colour palette that can meet our evolving needs, and we
have already achieved broad package/face coverage.  All while conforming
with the overarching objective of this project for a minimum 7:1
contrast ratio between background and foreground values in any given
combination we specify.

I wish to thank everyone who has helped me by testing things and sharing
their thoughts.  The people already mentioned herein:

- Anders Johansson (https://gitlab.com/andersjohansson)
- Damien Cassou (https://gitlab.com/DamienCassou)
- Manuel Uberti (https://gitlab.com/muberti)
- Shreyas Ragavan (https://gitlab.com/shrysr)
- tycho garen (https://gitlab.com/tychoish)