[elpa] externals/modus-operandi-theme a5832c9 151/153: Update to version 0.13.0

[Stefan Monnier]

branch: externals/modus-operandi-theme
commit a5832c9310765098e75d11155f765cc3c90b3548
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Update to version 0.13.0
---
 CHANGELOG.org           | 542 +++++++++++++++++++++++++++++++++++++++++++++++-
 doc/modus-themes.info   | 359 +++++++++++++++++++-------------
 doc/modus-themes.org    | 233 ++++++++++++++-------
 modus-operandi-theme.el |   2 +-
 modus-vivendi-theme.el  |   2 +-
 5 files changed, 914 insertions(+), 224 deletions(-)

diff --git a/CHANGELOG.org b/CHANGELOG.org
index 439b080..c8bca0d 100644
--- a/CHANGELOG.org
+++ b/CHANGELOG.org
@@ -1,11 +1,547 @@
 #+TITLE: Change log of the Modus Themes for GNU Emacs
 #+AUTHOR: Protesilaos Stavrou
 #+EMAIL: public@protesilaos.com
+#+OPTIONS: ':nil toc:nil num:nil author:nil email:nil
 
 This document contains the release notes that are included in each
-tagged commit on https://gitlab.com/protesilaos/modus-themes.  The
-newest release is at the top.  Since the notes are meant to be plain
-text, I copy them verbatim.
+tagged commit on the project's main git repository:
+<https://gitlab.com/protesilaos/modus-themes>.
+
+The newest release is at the top.  Since the notes are meant to be in
+plain text format, I copy them verbatim.
+
+For further details, please consult these additional resources:
+
++ Manual :: <https://protesilaos.com/modus-themes>
++ Screenshots :: <https://protesilaos.com/modus-themes-pictures>
+
+* 0.13.0
+
+#+begin_src text
+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!
+#+end_src
 
 * 0.12.0
 
diff --git a/doc/modus-themes.info b/doc/modus-themes.info
index 9267e66..bd0beb0 100644
--- a/doc/modus-themes.info
+++ b/doc/modus-themes.info
@@ -14,10 +14,11 @@ Modus themes for GNU Emacs
 
 This manual, written by Protesilaos Stavrou, describes the customisation
 options for the ‘modus-operandi’ and ‘modus-vivendi’ themes, and
-provides every other piece of information pertinent to them.  The
-document corresponds to version 0.13.0, expected to be released in late
-September 2020.  As such, the present entry should be considered a
-work-in-progress.
+provides every other piece of information pertinent to them.
+
+   The documentation furnished herein corresponds to version 0.13.0,
+released on 2020-10-08.  Any reference to a newer feature which does not
+yet form part of the latest tagged commit, is explicitly marked as such.
 
    Copyright (C) 2020 Free Software Foundation, Inc.
 
@@ -27,8 +28,6 @@ work-in-progress.
      Foundation; with no Invariant Sections, with no Front-Cover Texts,
      and with no Back-Cover Texts.
 
-   Info manual HTML version (https://protesilaos.com/modus-themes).
-
 * Menu:
 
 * Overview::
@@ -49,6 +48,7 @@ work-in-progress.
 Overview
 
 * How do the themes look like::
+* Learn about the latest changes::
 
 Installation
 
@@ -126,7 +126,7 @@ File: modus-themes.info,  Node: Overview,  Next: 
Installation,  Prev: Top,  Up:
 
 The Modus themes are designed for accessible readability.  They conform
 with the highest standard for colour contrast between any given
-combination of background and foreground colours.  This corresponds to
+combination of background and foreground values.  This corresponds to
 the WCAG AAA standard, which specifies a minimum rate of distance in
 relative luminance of 7:1.
 
@@ -137,7 +137,7 @@ in the Emacs computing environment.
 
    The overarching objective of this project is to always offer
 accessible colour combinations.  There shall never be a compromise on
-this principle.  If there is an inescapable trade-off between
+this principle.  If there arises an inescapable trade-off between
 readability and stylistic considerations, we will always opt for the
 former.
 
@@ -145,23 +145,16 @@ former.
 themes strive to achieve as close to full face coverage as possible (see
 *note Face coverage::).
 
-   Starting with version 0.12.0, the themes are built into Emacs.  Their
-version is that of the latest tagged release.  This is because I
-(Protesilaos Stavrou) do not have push privileges to the Emacs
-repository and must contact the mailing list for someone else to make
-the changes for me.  As you can understand, it would be too tedious to
-do this each time I make a commit.
-
-   If I am ever granted access to the Emacs git repo, I will make sure
-that the built-in themes are synced with the ‘HEAD’ of my ‘master’
-branch.
+   Starting with version 0.12.0 and onwards, the themes are built into
+GNU Emacs (current version is 0.13.0).
 
 * Menu:
 
 * How do the themes look like::
+* Learn about the latest changes::
 
 
-File: modus-themes.info,  Node: How do the themes look like,  Up: Overview
+File: modus-themes.info,  Node: How do the themes look like,  Next: Learn 
about the latest changes,  Up: Overview
 
 1.1 How do the themes look like
 ===============================
@@ -175,6 +168,16 @@ customisation options.
    *note Customisation options: Customisation Options.
 
 
+File: modus-themes.info,  Node: Learn about the latest changes,  Prev: How do 
the themes look like,  Up: Overview
+
+1.2 Learn about the latest changes
+==================================
+
+Please refer to the web page with the change log
+(https://protesilaos.com/modus-themes-changelog).  It is comprehensive
+and covers everything that goes into every tagged release of the themes.
+
+
 File: modus-themes.info,  Node: Installation,  Next: Enable and load,  Prev: 
Overview,  Up: Top
 
 2 Installation
@@ -202,14 +205,14 @@ File: modus-themes.info,  Node: Install from the 
archives,  Next: Install on GNU
 =============================
 
 ‘modus-operandi-theme’ and ‘modus-vivendi-theme’ are available from GNU
-Elpa, Melpa, Melpa-Stable.
+ELPA, MELPA, MELPA Stable.
 
    Prior to querying any package archive, make sure to have updated the
 index, with ‘M-x package-refresh-contents’.  Then all you need to do is
 type ‘M-x package-install’ and specify the theme of your choice.
 
-   GNU Elpa and Melpa-Stable contain the last tagged release.  While
-Melpa builds from the latest commit to the Modus theme’s Git repository
+   GNU ELPA and MELPA Stable contain the last tagged release.  While
+MELPA builds from the latest commit to the Modus theme’s Git repository
 (https://gitlab.com/protesilaos/modus-themes).
 
 
@@ -293,8 +296,9 @@ you might run into unexpected issues.
    Note that you can always ‘M-x disable-theme’ and specify an item.
 The command does exactly what its name suggests.  To deactivate all
 enabled themes at once, in case you have multiple of them enabled, you
-may evaluate the expression ‘(mapc #'disable-theme
-custom-enabled-themes)’.
+may evaluate the expression:
+
+     (mapc #'disable-theme custom-enabled-themes)
 
 
 File: modus-themes.info,  Node: Load at a given time or at sunset/sunrise,  
Next: Toggle between the themes on demand,  Prev: Load automatically,  Up: 
Enable and load
@@ -318,8 +322,8 @@ given theme will be loaded.(1)
                     (enable-theme 'modus-vivendi)))
 
    A modified version of the above technique is to use the sunrise and
-sunset as references, instead of specifying a fixed value.(2)  If you
-set ‘calendar-latitude’ and ‘calendar-longitude’ (defined in the
+sunset as references, instead of specifying a fixed hour value.(2)  If
+you set ‘calendar-latitude’ and ‘calendar-longitude’ (defined in the
 built-in ‘solar.el’ library—read it with ‘M-x find-library’), you can
 automatically switch between both themes at the appropriate time-of-day.
 Note that _those calendar variables need to be set before loading the
@@ -375,6 +379,9 @@ switch between them on demand.
          (disable-theme 'modus-vivendi)
          (load-theme 'modus-operandi t)))
 
+   You could use ‘(mapc #'disable-theme custom-enabled-themes)’ instead
+of disabling a single target, but you get the idea.
+
 
 File: modus-themes.info,  Node: Configure options prior to loading,  Prev: 
Toggle between the themes on demand,  Up: Enable and load
 
@@ -409,9 +416,10 @@ are just for the sake of this demonstration):(1)
                 modus-%1$s-theme-diffs nil ; {nil,'desaturated,'fg-only}
                 modus-%1$s-theme-org-blocks 'greyscale ; 
{nil,'greyscale,'rainbow}
                 modus-%1$s-theme-headings  ; Read further below in the manual 
for this one
-                '((1 . line)
+                '((1 . section)
+                  (2 . line)
                   (t . rainbow-line-no-bold))
-                modus-%1$s-theme-variable-pitch-headings t
+                modus-%1$s-theme-variable-pitch-headings nil
                 modus-%1$s-theme-scale-headings t
                 modus-%1$s-theme-scale-1 1.1
                 modus-%1$s-theme-scale-2 1.15
@@ -433,7 +441,7 @@ are just for the sake of this demonstration):(1)
 
    ---------- Footnotes ----------
 
-   (1) The ‘defmacro’ and ‘dolist’ method was contributed on Reddit by
+   (1) The ‘defmacro’ and ‘dolist’ method were contributed on Reddit by
 user b3n
 
<https://www.reddit.com/r/emacs/comments/gqsz8u/weekly_tipstricketc_thread/fsfakhg/>.
 
@@ -488,18 +496,21 @@ Symbol names:
 
    Display several constructs in bold weight.  This concerns keywords
 and other important aspects of code syntax.  It also affects certain
-mode line indicators.
+mode line indicators and command-line prompts.
 
-   The default is to only use a bold weight when it is necessary.
+   The default is to only use a bold weight when it is required.
 
-   Additionally and while not necessary, to define the precise weight
+   Additionally, and while not necessary, to define the precise weight
 for bold constructs, you can change the typographic intensity of the
-‘bold’ face.  Assuming your typeface of choice supports a “semibold”
-weight, adding the following snippet to your init file should suffice:
+‘bold’ face.  The standard is a bold weight.  It requires no further
+intervention.  Assuming though that your typeface of choice supports a
+“semibold” weight, adding the following snippet to your init file should
+suffice.
 
      (set-face-attribute 'bold nil :weight 'semibold)
 
-   The standard is a bold weight.  It requires no further intervention.
+   Note that if you are switching themes, you need to re-evaluate this
+expression after the new theme is loaded.
 
 
 File: modus-themes.info,  Node: Slanted constructs,  Next: Syntax 
highlighting,  Prev: Bold constructs,  Up: Customisation Options
@@ -542,8 +553,10 @@ Symbol names:
 syntax.  The default is to use saturated colours.
 
    This option essentially affects the font-lock faces, so it may also
-have effects in other places that are hard-wired to rely directly on
-font-lock.  The author is aware of ‘vc-dir’ as a case in point.
+have implications in other places that are hard-wired to rely directly
+on them instead of specifying their own faces (which could inherit from
+font-lock if that is the intent).  The author is aware of ‘vc-dir’ as a
+case in point.
 
 
 File: modus-themes.info,  Node: No mixed fonts,  Next: Link underline,  Prev: 
Syntax highlighting,  Up: Customisation Options
@@ -616,8 +629,8 @@ prompts (like ‘M-x shell’ and ‘M-x eshell’).  The 
difference between the
 two is that the latter has a more pronounced/noticeable effect than the
 former.
 
-   The default is to not use any background for such prompts, while only
-relying on an accented foreground colour.
+   The default is to not use any background for such prompts, while
+relying exclusively on an accented foreground colour.
 
 
 File: modus-themes.info,  Node: Mode line,  Next: Completion UIs,  Prev: 
Command prompts,  Up: Customisation Options
@@ -815,7 +828,7 @@ Word-wise or “refined” changes follow this pattern but use 
different
 shades of those colours to remain distinct.
 
    A ‘desaturated’ value tones down all relevant colour values.  It
-still combines an accented background with an appropriate background,
+still combines an accented background with an appropriate foreground,
 yet its overall impression is very subtle.  Refined changes are a bit
 more intense to fulfil their intended function, though still less
 saturated than default.
@@ -886,13 +899,16 @@ than other customisation options documented in this 
manual.
    Possible values, which can be specified for each heading level
 (examples further below):
 
-   • ‘t’ (default style)
+   • nil (default fallback option—covers all heading levels)
+   • ‘t’ (default style for a single heading, when the fallback differs)
    • ‘no-bold’
    • ‘line’
    • ‘line-no-bold’
    • ‘rainbow’
    • ‘rainbow-line’
    • ‘rainbow-line-no-bold’
+   • ‘highlight’
+   • ‘highlight-no-bold’
    • ‘rainbow-highlight’
    • ‘rainbow-highlight-no-bold’
    • ‘section’
@@ -904,30 +920,36 @@ than other customisation options documented in this 
manual.
 for ‘modus-vivendi-theme-headings’):
 
      (setq modus-operandi-theme-headings
-           '((1 . highlight)
+           '((1 . section)
              (2 . line)
-             (t . rainbow-line-no-bold)))
+             (3 . highlight)
+             (t . rainbow-no-bold)))
 
-   The above uses the ‘highlight’ value for heading levels 1 and the
-‘line’ for headings 2.  All other levels fall back to
+   The above uses the ‘section’ value for heading levels 1, the ‘line’
+for headings 2, ‘highlight’ for 3.  All other levels fall back to
 ‘rainbow-line-no-bold’.
 
    To set a uniform value for all heading levels, use this pattern:
 
+     ;; A given style for every heading
      (setq modus-operandi-theme-headings
            '((t . rainbow-line-no-bold)))
 
+     ;; Default aesthetic for every heading
+     (setq modus-operandi-theme-headings
+           '((t . nil)))
+
    The default style for headings uses a fairly desaturated foreground
 value in combination with a bold typographic weight.  To specify this
 style for a given level N (assuming you wish to have another fallback
-option), just specify the value t like this:
+option), just specify the value ‘t’ like this:
 
      (setq modus-operandi-theme-headings
            '((1 . t)
              (2 . line)
              (t . rainbow-line-no-bold)))
 
-   A description of all other possible values:
+   A description of all other possible styles:
 
    • ‘no-bold’ retains the default text colour while removing the
      typographic weight.
@@ -946,7 +968,7 @@ option), just specify the value t like this:
      bold weight.
 
    • ‘highlight’ retains the default style of a fairly desaturated
-     foreground combined with a bold weight and add to it a subtle
+     foreground combined with a bold weight and adds to it a subtle
      accented background.
 
    • ‘highlight-no-bold’ is the same as ‘highlight’ without a bold
@@ -1007,9 +1029,9 @@ specify a number of their own.
      multiple of the base font size.  This is the recommended method.
 
    • If it is an integer, it is read as an absolute font height.  The
-     number is basically the point size multiplied by a hundred.  So if
-     you want it to be ‘18pt’ you must pass ‘180’.  Please understand
-     that setting an absolute value is discouraged, as it will break the
+     number is basically the point size multiplied by ten.  So if you
+     want it to be ‘18pt’ you must pass ‘180’.  Please understand that
+     setting an absolute value is discouraged, as it will break the
      layout when you try to change font sizes with the built-in
      ‘text-scale-adjust’ command (see *note Font configurations: Font
      configs (DIY).).
@@ -1031,12 +1053,10 @@ use a resource for finding a consistent scale:
            modus-vivendi-theme-scale-4 1.2
            modus-vivendi-theme-scale-5 1.3)
 
-   Note that in Org, scaling only increases the size of the heading, but
-not of keywords that are added to it, like “TODO”.  This is outside the
-control of the themes and I am not aware of any way to make such
-keywords scale accordingly without patching upstream Org (see issue 37
-(https://gitlab.com/protesilaos/modus-themes/-/issues/37) in the themes’
-issue tracker).
+   Note that in earlier versions of Org, scaling would only increase the
+size of the heading, but not of keywords that were added to it, like
+“TODO”.  The issue has been fixed upstream:
+<https://protesilaos.com/codelog/2020-09-24-org-headings-adapt/>.
 
 
 File: modus-themes.info,  Node: Headings' font,  Prev: Scaled headings,  Up: 
Customisation Options
@@ -1175,8 +1195,9 @@ File: modus-themes.info,  Node: Font configs (DIY),  
Next: Org user faces (DIY),
 5.2 Font configurations for Org (and others)
 ============================================
 
-The themes are designed to cope well with mixed font settings.
-Currently this applies to ‘org-mode’ and ‘markdown-mode’.
+The themes are designed to cope well with mixed font settings (*note
+Option for no font mixing: No mixed fonts.).  Currently this applies to
+‘org-mode’ and ‘markdown-mode’.
 
    In practice it means that the user can safely opt for a more
 prose-friendly proportionately spaced typeface as their default, while
@@ -1214,9 +1235,9 @@ importantance: it ensures that all fonts can scale 
gracefully when using
 something like the ‘text-scale-adjust’ command which only operates on
 the base font size (i.e.  the ‘default’ face’s absolute height).
 
-   An alternative syntax for the ‘default’ face, which the author of
-this documents prefers, is to pass all typeface parameters directly to a
-‘font’ property.(2)  Note that here we use a standard point size:
+   An alternative syntax for the ‘default’ face, is to pass all typeface
+parameters directly to a ‘font’ property.(2)  Note that here we use a
+standard point size:
 
      (set-face-attribute 'default nil :font "DejaVu Sans Mono-11")
 
@@ -1246,8 +1267,8 @@ priority cookies to better match their workflow.  User 
options are
    As those are meant to be custom faces, it would be futile to have the
 themes try to guess what each user would want to use, which keywords to
 target, and so on.  Instead, we can provide guidelines on how to
-customise things to one’s liking with the intent to retain the overall
-aesthetics of the theme.
+customise things to one’s liking with the intent of retaining the
+overall aesthetics of the theme.
 
    Please bear in mind that the end result of those is not controlled by
 the active theme but by how Org maps faces to its constructs.  Editing
@@ -1277,8 +1298,7 @@ items in ‘org-todo-keywords’ use their original styles 
(which are
 defined in the ‘org-todo’ and ‘org-done’ faces).
 
    If you want back the defaults, try specifying just the ‘org-todo’
-face (or use ‘org-done’ if the meaning of the keywords you use demands
-as much):
+face:
 
      (setq org-todo-keyword-faces
            '(("MEET" . org-todo)
@@ -1303,8 +1323,8 @@ use ‘M-x list-faces-display’.  Also try ‘M-x 
describe-variable’ and then
 specify the name of each of those Org variables demonstrated above.
 Their documentation strings will offer you further guidance.
 
-   Also consider reading the “Notes for aspiring Emacs theme
-developers”, published on 2020-08-28 by Protesilaos Stavrou:
+   Furthermore, consider reading the “Notes for aspiring Emacs theme
+developers”, published on 2020-08-28 by me (Protesilaos Stavrou):
 <https://protesilaos.com/codelog/2020-08-28-notes-emacs-theme-devs/>.
 
 
@@ -1385,6 +1405,7 @@ have lots of extensions, so the “full support” may not be 
100% true…
    • diff-hl
    • diff-mode
    • dim-autoload
+   • dir-treeview
    • dired
    • dired-async
    • dired-git
@@ -1868,14 +1889,58 @@ the themes are part of the upstream Emacs distribution: 
the FSF must at
 all times be in a position to enforce the GNU General Public License.
 
    Copyright assignment is a simple process.  Check the request form
-(https://git.savannah.gnu.org/cgit/gnulib.git/tree/doc/Copyright/request-assign.future).
-You must write an email to the address mentioned in the form and then
-wait for the FSF to send you a legal agreement.  Sign the document and
-file it back to them.  This could all happen via email and take about a
-week.
+below (please adapt it accordingly).  You must write an email to the
+address mentioned in the form and then wait for the FSF to send you a
+legal agreement.  Sign the document and file it back to them.  This
+could all happen via email and take about a week.  You are encouraged to
+go through this process.  You only need to do it once.  It will allow
+you to make contributions to Emacs in general.
+
+     Please email the following information to assign@gnu.org, and we
+     will send you the assignment form for your past and future changes.
+
+     Please use your full legal name (in ASCII characters) as the subject
+     line of the message.
+     ----------------------------------------------------------------------
+     REQUEST: SEND FORM FOR PAST AND FUTURE CHANGES
+
+     [What is the name of the program or package you're contributing to?]
+
+     GNU Emacs
+
+     [Did you copy any files or text written by someone else in these changes?
+     Even if that material is free software, we need to know about it.]
+
+     Copied a few snippets from the same files I edited.  Their author,
+     Protesilaos Stavrou, has already assigned copyright to the Free Software
+     Foundation.
 
-   You are encouraged to go through this process.  You only need to do
-it once.  It will allow you to make contributions to Emacs in general.
+     [Do you have an employer who might have a basis to claim to own
+     your changes?  Do you attend a school which might make such a claim?]
+
+
+     [For the copyright registration, what country are you a citizen of?]
+
+
+     [What year were you born?]
+
+
+     [Please write your email address here.]
+
+
+     [Please write your postal address here.]
+
+
+
+
+
+     [Which files have you changed so far, and which new files have you written
+     so far?]
+
+     Changed a couple of themes that are part of the Emacs source code:
+
+     ./etc/themes/modus-operandi-theme.el
+     ./etc/themes/modus-vivendi-theme.el
 
 
 File: modus-themes.info,  Node: Acknowledgements,  Next: Meta,  Prev: 
Contributing,  Up: Top
@@ -1899,10 +1964,11 @@ Ideas and user feedback
      Edmondson, Davor Rotim, Divan Santana, Gerry Agbobada, Gianluca
      Recchia, Iris Garcia, Len Trigg, Manuel Uberti, Mark Burton, Markus
      Beppler, Michael Goldenberg, Murilo Pereira, Nicolas De Jaeghere,
-     Pierre Téchoueyres, Ryan Phillips, Shreyas Ragavan, Tassilo Horn,
-     Thibaut Verron, Trey Merkley, Uri Sharf, Utkarsh Singh, Vincent
-     Foley.  As well as users: Ben, Fourchaux, Fredrik, Moesasji, Nick,
-     TheBlob42, dinko, doolio, jixiuf, okamsn, tycho garen.
+     Pierre Téchoueyres, Roman Rudakov, Ryan Phillips, Shreyas Ragavan,
+     Tassilo Horn, Thibaut Verron, Trey Merkley, Uri Sharf, Utkarsh
+     Singh, Vincent Foley.  As well as users: Ben, Fourchaux, Fredrik,
+     Moesasji, Nick, TheBlob42, dinko, doolio, jixiuf, okamsn, tycho
+     garen.
 
 Packaging
      Dhavan Vaidya (Debian), Stefan Kangas (core Emacs), Stefan Monnier
@@ -1923,7 +1989,8 @@ this project read the essay On the design of the Modus 
themes
 (2020-03-17).
 
    Here are some more publications for those interested in the kind of
-work that goes into this project:
+work that goes into this project (sometimes the commits also include
+details of this sort):
 
    • Modus Operandi theme subtle palette review
      
(https://protesilaos.com/codelog/2020-05-10-modus-operandi-palette-review/)
@@ -1941,6 +2008,15 @@ work that goes into this project:
      (https://protesilaos.com/codelog/2020-09-14-modus-themes-review-blues/)
      (2020-09-14)
 
+   And here are the canonical sources for this project’s documentation:
+
+Manual
+     <https://protesilaos.com/modus-themes>
+Change Log
+     <https://protesilaos.com/modus-themes-changelog>
+Screenshots
+     <https://protesilaos.com/modus-themes-pictures>
+
 
 File: modus-themes.info,  Node: External projects (ports),  Next: GNU Free 
Documentation License,  Prev: Meta,  Up: Top
 
@@ -2421,67 +2497,68 @@ Appendix A GNU Free Documentation License
 
 Tag Table:
 Node: Top218
-Node: Overview3978
-Node: How do the themes look like5663
-Node: Installation6131
-Node: Install from the archives6781
-Node: Install on GNU/Linux7468
-Node: Debian 11 Bullseye7913
-Node: GNU Guix8322
-Node: Enable and load8673
-Node: Load automatically9250
-Node: Load at a given time or at sunset/sunrise10063
-Ref: Load at a given time or at sunset/sunrise-Footnote-112101
-Ref: Load at a given time or at sunset/sunrise-Footnote-212229
-Node: Toggle between the themes on demand12312
-Node: Configure options prior to loading13059
-Ref: Configure options prior to loading-Footnote-115707
-Node: Customisation Options15882
-Node: Bold constructs17626
-Node: Slanted constructs18625
-Node: Syntax highlighting19216
-Node: No mixed fonts19944
-Node: Link underline21025
-Node: Command prompts21507
-Node: Mode line22305
-Node: Completion UIs24929
-Node: Fringes26841
-Node: Line highlighting27605
-Node: Matching parentheses28273
-Node: Diffs28917
-Node: Org mode blocks30710
-Node: Heading styles32213
-Node: Scaled headings35602
-Node: Scaled heading sizes36219
-Node: Headings' font38178
-Node: Advanced customisation (do-it-yourself)38802
-Node: Tweak colours (DIY)39806
-Node: Font configs (DIY)43440
-Ref: Font configs (DIY)-Footnote-146020
-Ref: Font configs (DIY)-Footnote-246207
-Node: Org user faces (DIY)46429
-Node: Face coverage49650
-Node: Supported packages50152
-Node: Covered indirectly56174
-Node: Will NOT be supported56559
-Node: Notes for individual packages57277
-Node: Note on company-mode overlay pop-up57765
-Ref: Note on company-mode overlay pop-up-Footnote-158429
-Ref: Note on company-mode overlay pop-up-Footnote-258496
-Node: Note for ERC escaped colour sequences58551
-Ref: Note for ERC escaped colour sequences-Footnote-159978
-Node: Note for powerline or spaceline60088
-Node: Note on shr colours60506
-Node: Note for Helm grep60919
-Node: Note on vc-annotate-background-mode62366
-Node: Contributing63220
-Node: Sources of the themes63639
-Node: Issues you can help with64401
-Node: Merge requests65588
-Node: Acknowledgements66670
-Node: Meta67953
-Node: External projects (ports)69145
-Node: GNU Free Documentation License69968
+Node: Overview3998
+Node: How do the themes look like5299
+Node: Learn about the latest changes5806
+Node: Installation6188
+Node: Install from the archives6838
+Node: Install on GNU/Linux7525
+Node: Debian 11 Bullseye7970
+Node: GNU Guix8379
+Node: Enable and load8730
+Node: Load automatically9307
+Node: Load at a given time or at sunset/sunrise10120
+Ref: Load at a given time or at sunset/sunrise-Footnote-112163
+Ref: Load at a given time or at sunset/sunrise-Footnote-212291
+Node: Toggle between the themes on demand12374
+Node: Configure options prior to loading13250
+Ref: Configure options prior to loading-Footnote-115932
+Node: Customisation Options16108
+Node: Bold constructs17852
+Node: Slanted constructs18999
+Node: Syntax highlighting19590
+Node: No mixed fonts20415
+Node: Link underline21496
+Node: Command prompts21978
+Node: Mode line22783
+Node: Completion UIs25407
+Node: Fringes27319
+Node: Line highlighting28083
+Node: Matching parentheses28751
+Node: Diffs29395
+Node: Org mode blocks31188
+Node: Heading styles32691
+Node: Scaled headings36445
+Node: Scaled heading sizes37062
+Node: Headings' font38895
+Node: Advanced customisation (do-it-yourself)39519
+Node: Tweak colours (DIY)40523
+Node: Font configs (DIY)44157
+Ref: Font configs (DIY)-Footnote-146745
+Ref: Font configs (DIY)-Footnote-246932
+Node: Org user faces (DIY)47154
+Node: Face coverage50312
+Node: Supported packages50814
+Node: Covered indirectly56856
+Node: Will NOT be supported57258
+Node: Notes for individual packages57976
+Node: Note on company-mode overlay pop-up58464
+Ref: Note on company-mode overlay pop-up-Footnote-159128
+Ref: Note on company-mode overlay pop-up-Footnote-259195
+Node: Note for ERC escaped colour sequences59250
+Ref: Note for ERC escaped colour sequences-Footnote-160677
+Node: Note for powerline or spaceline60787
+Node: Note on shr colours61205
+Node: Note for Helm grep61618
+Node: Note on vc-annotate-background-mode63065
+Node: Contributing63919
+Node: Sources of the themes64338
+Node: Issues you can help with65100
+Node: Merge requests66287
+Node: Acknowledgements68705
+Node: Meta70008
+Node: External projects (ports)71515
+Node: GNU Free Documentation License72338
 
 End Tag Table
 
diff --git a/doc/modus-themes.org b/doc/modus-themes.org
index 95f220b..8e00ac8 100644
--- a/doc/modus-themes.org
+++ b/doc/modus-themes.org
@@ -4,7 +4,7 @@
 #+OPTIONS: ':t toc:nil author:t email:t
 #+LANGUAGE: en
 #+MACRO: version-tag 0.13.0
-#+MACRO: release-date late September 2020
+#+MACRO: release-date 2020-10-08
 #+TEXINFO_FILENAME: modus-themes.info
 #+TEXINFO_DIR_CATEGORY: Emacs
 #+TEXINFO_DIR_TITLE: Modus Themes: (modus-themes)
@@ -13,10 +13,12 @@
 
 This manual, written by Protesilaos Stavrou, describes the customisation
 options for the =modus-operandi= and =modus-vivendi= themes, and provides
-every other piece of information pertinent to them.  The document
-corresponds to version {{{version-tag}}}, expected to be released in
-{{{release-date}}}.  As such, the present entry should be considered a
-work-in-progress.
+every other piece of information pertinent to them.
+
+The documentation furnished herein corresponds to version {{{version-tag}}},
+released on {{{release-date}}}.  Any reference to a newer feature which does
+not yet form part of the latest tagged commit, is explicitly marked as
+such.
 
 Copyright (C) 2020 Free Software Foundation, Inc.
 
@@ -28,8 +30,6 @@ Foundation; with no Invariant Sections, with no Front-Cover 
Texts,
 and with no Back-Cover Texts.
 #+end_quote
 
-[[https://protesilaos.com/modus-themes][Info manual HTML version]].
-
 #+TOC: headlines 8 insert TOC here, with eight headline levels
 
 * Overview
@@ -39,7 +39,7 @@ and with no Back-Cover Texts.
 
 The Modus themes are designed for accessible readability.  They conform
 with the highest standard for colour contrast between any given
-combination of background and foreground colours.  This corresponds to
+combination of background and foreground values.  This corresponds to
 the WCAG AAA standard, which specifies a minimum rate of distance in
 relative luminance of 7:1.
 
@@ -50,35 +50,36 @@ computing environment.
 
 The overarching objective of this project is to always offer accessible
 colour combinations.  There shall never be a compromise on this
-principle.  If there is an inescapable trade-off between readability and
-stylistic considerations, we will always opt for the former.
+principle.  If there arises an inescapable trade-off between readability
+and stylistic considerations, we will always opt for the former.
 
 To ensure that users have a consistently accessible experience, the
 themes strive to achieve as close to full face coverage as possible
 (see [[#h:a9c8f29d-7f72-4b54-b74b-ddefe15d6a19][Face coverage]]).
 
-Starting with version 0.12.0, the themes are built into Emacs.  Their
-version is that of the latest tagged release.  This is because I
-(Protesilaos Stavrou) do not have push privileges to the Emacs
-repository and must contact the mailing list for someone else to make
-the changes for me.  As you can understand, it would be too tedious to
-do this each time I make a commit.
-
-If I am ever granted access to the Emacs git repo, I will make sure that
-the built-in themes are synced with the =HEAD= of my =master= branch.
+Starting with version 0.12.0 and onwards, the themes are built into GNU
+Emacs (current version is {{{version-tag}}}).
 
 ** How do the themes look like
 :PROPERTIES:
 :CUSTOM_ID: h:69b92089-069c-4ba1-9d94-cc3415fc4f87
 :END:
 
-Check the [[https://protesilaos.com/modus-themes-pictures/][web page with the 
screen shots]].  There are lots of scenaria on
+Check the web page with [[https://protesilaos.com/modus-themes-pictures/][the 
screen shots]].  There are lots of scenaria on
 display that draw attention to details and important aspects in the
 design of the themes.  They also showcase the numerous customisation
 options.
 
 [[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customisation options]].
 
+** Learn about the latest changes
+:PROPERTIES:
+:CUSTOM_ID: h:2cc37c36-6c1a-48b2-a010-1050b270ee18
+:END:
+
+Please refer to the [[https://protesilaos.com/modus-themes-changelog][web page 
with the change log]].  It is comprehensive
+and covers everything that goes into every tagged release of the themes.
+
 * Installation
 :PROPERTIES:
 :CUSTOM_ID: h:1af85373-7f81-4c35-af25-afcef490c111
@@ -100,13 +101,13 @@ distributions.
 :END:
 
 =modus-operandi-theme= and =modus-vivendi-theme= are available from GNU
-Elpa, Melpa, Melpa-Stable.
+ELPA, MELPA, MELPA Stable.
 
 Prior to querying any package archive, make sure to have updated the
 index, with =M-x package-refresh-contents=.  Then all you need to do is
 type =M-x package-install= and specify the theme of your choice.
 
-GNU Elpa and Melpa-Stable contain the last tagged release.  While Melpa
+GNU ELPA and MELPA Stable contain the last tagged release.  While MELPA
 builds from the latest commit to the 
[[https://gitlab.com/protesilaos/modus-themes][Modus theme's Git repository]].
 
 ** Install on GNU/Linux
@@ -181,7 +182,11 @@ might run into unexpected issues.
 Note that you can always =M-x disable-theme= and specify an item.  The
 command does exactly what its name suggests.  To deactivate all enabled
 themes at once, in case you have multiple of them enabled, you may
-evaluate the expression =(mapc #'disable-theme custom-enabled-themes)=.
+evaluate the expression:
+
+#+begin_src emacs-lisp
+(mapc #'disable-theme custom-enabled-themes)
+#+end_src
 
 ** Load at a given time or at sunset/sunrise
 :PROPERTIES:
@@ -207,7 +212,7 @@ 
https://www.reddit.com/r/emacs/comments/gdtqov/weekly_tipstricketc_thread/fq9186
 #+end_src
 
 A modified version of the above technique is to use the sunrise and
-sunset as references, instead of specifying a fixed value.[fn::
+sunset as references, instead of specifying a fixed hour value.[fn::
 Contributed directly by André Alexandre Gomes https://gitlab.com/aadcg.]
 If you set =calendar-latitude= and =calendar-longitude= (defined in the
 built-in =solar.el= library---read it with =M-x find-library=), you can
@@ -260,6 +265,9 @@ switch between them on demand.
     (load-theme 'modus-operandi t)))
 #+end_src
 
+You could use =(mapc #'disable-theme custom-enabled-themes)= instead of
+disabling a single target, but you get the idea.
+
 ** Configure options prior to loading
 :PROPERTIES:
 :CUSTOM_ID: h:a897b302-8e10-4a26-beab-3caaee1e1193
@@ -272,7 +280,7 @@ presented in 
[[#h:2a0895a6-3281-4e55-8aa1-8a737555821e][Toggle between the theme
 
 Here is a comprehensive setup (the values assigned to the variables are
 just for the sake of this demonstration):[fn:: The =defmacro= and =dolist=
-method was contributed on Reddit by user b3n
+method were contributed on Reddit by user b3n
 
https://www.reddit.com/r/emacs/comments/gqsz8u/weekly_tipstricketc_thread/fsfakhg/.]
 
 #+begin_src emacs-lisp
@@ -296,9 +304,10 @@ 
https://www.reddit.com/r/emacs/comments/gqsz8u/weekly_tipstricketc_thread/fsfakh
            modus-%1$s-theme-diffs nil ; {nil,'desaturated,'fg-only}
            modus-%1$s-theme-org-blocks 'greyscale ; {nil,'greyscale,'rainbow}
            modus-%1$s-theme-headings  ; Read further below in the manual for 
this one
-           '((1 . line)
+           '((1 . section)
+             (2 . line)
              (t . rainbow-line-no-bold))
-           modus-%1$s-theme-variable-pitch-headings t
+           modus-%1$s-theme-variable-pitch-headings nil
            modus-%1$s-theme-scale-headings t
            modus-%1$s-theme-scale-1 1.1
            modus-%1$s-theme-scale-2 1.15
@@ -351,20 +360,23 @@ Possible values:
 
 Display several constructs in bold weight.  This concerns keywords and
 other important aspects of code syntax.  It also affects certain mode
-line indicators.
+line indicators and command-line prompts.
 
-The default is to only use a bold weight when it is necessary.
+The default is to only use a bold weight when it is required.
 
-Additionally and while not necessary, to define the precise weight for
+Additionally, and while not necessary, to define the precise weight for
 bold constructs, you can change the typographic intensity of the =bold=
-face.  Assuming your typeface of choice supports a "semibold" weight,
-adding the following snippet to your init file should suffice:
+face.  The standard is a bold weight.  It requires no further
+intervention.  Assuming though that your typeface of choice supports a
+"semibold" weight, adding the following snippet to your init file should
+suffice.
 
 #+begin_src emacs-lisp
 (set-face-attribute 'bold nil :weight 'semibold)
 #+end_src
 
-The standard is a bold weight.  It requires no further intervention.
+Note that if you are switching themes, you need to re-evaluate this
+expression after the new theme is loaded.
 
 ** Option for more slanted constructs
 :PROPERTIES:
@@ -409,8 +421,10 @@ Use less saturated colours in programming modes for 
highlighting code
 syntax.  The default is to use saturated colours.
 
 This option essentially affects the font-lock faces, so it may also have
-effects in other places that are hard-wired to rely directly on
-font-lock.  The author is aware of =vc-dir= as a case in point.
+implications in other places that are hard-wired to rely directly on
+them instead of specifying their own faces (which could inherit from
+font-lock if that is the intent).  The author is aware of =vc-dir= as a
+case in point.
 
 ** Option for no font mixing
 :PROPERTIES:
@@ -484,8 +498,8 @@ background and foreground to the minibuffer and other REPL 
prompts (like
 =M-x shell= and =M-x eshell=).  The difference between the two is that the
 latter has a more pronounced/noticeable effect than the former.
 
-The default is to not use any background for such prompts, while only
-relying on an accented foreground colour.
+The default is to not use any background for such prompts, while relying
+exclusively on an accented foreground colour.
 
 ** Option for mode line presentation
 :PROPERTIES:
@@ -690,7 +704,7 @@ Word-wise or "refined" changes follow this pattern but use 
different
 shades of those colours to remain distinct.
 
 A =desaturated= value tones down all relevant colour values.  It still
-combines an accented background with an appropriate background, yet its
+combines an accented background with an appropriate foreground, yet its
 overall impression is very subtle.  Refined changes are a bit more
 intense to fulfil their intended function, though still less saturated
 than default.
@@ -763,13 +777,16 @@ Symbol names:
 Possible values, which can be specified for each heading level (examples
 further below):
 
-+ =t= (default style)
++ nil (default fallback option---covers all heading levels)
++ =t= (default style for a single heading, when the fallback differs)
 + =no-bold=
 + =line=
 + =line-no-bold=
 + =rainbow=
 + =rainbow-line=
 + =rainbow-line-no-bold=
++ =highlight=
++ =highlight-no-bold=
 + =rainbow-highlight=
 + =rainbow-highlight-no-bold=
 + =section=
@@ -782,25 +799,32 @@ To control faces per level from 1-8, use something like 
this (same for
 
 #+begin_src emacs-lisp
 (setq modus-operandi-theme-headings
-      '((1 . highlight)
+      '((1 . section)
         (2 . line)
-        (t . rainbow-line-no-bold)))
+        (3 . highlight)
+        (t . rainbow-no-bold)))
 #+end_src
 
-The above uses the =highlight= value for heading levels 1 and the =line= for
-headings 2.  All other levels fall back to =rainbow-line-no-bold=.
+The above uses the =section= value for heading levels 1, the =line= for
+headings 2, =highlight= for 3.  All other levels fall back to
+=rainbow-line-no-bold=.
 
 To set a uniform value for all heading levels, use this pattern:
 
 #+begin_src emacs-lisp
+;; A given style for every heading
 (setq modus-operandi-theme-headings
       '((t . rainbow-line-no-bold)))
+
+;; Default aesthetic for every heading
+(setq modus-operandi-theme-headings
+      '((t . nil)))
 #+end_src
 
 The default style for headings uses a fairly desaturated foreground
 value in combination with a bold typographic weight.  To specify this
 style for a given level N (assuming you wish to have another fallback
-option), just specify the value t like this:
+option), just specify the value =t= like this:
 
 #+begin_src emacs-lisp
 (setq modus-operandi-theme-headings
@@ -809,7 +833,7 @@ option), just specify the value t like this:
         (t . rainbow-line-no-bold)))
 #+end_src
 
-A description of all other possible values:
+A description of all other possible styles:
 
 + =no-bold= retains the default text colour while removing the typographic
   weight.
@@ -827,7 +851,7 @@ A description of all other possible values:
   weight.
 
 + =highlight= retains the default style of a fairly desaturated foreground
-  combined with a bold weight and add to it a subtle accented
+  combined with a bold weight and adds to it a subtle accented
   background.
 
 + =highlight-no-bold= is the same as =highlight= without a bold weight.
@@ -885,9 +909,9 @@ specify a number of their own.
   of the base font size.  This is the recommended method.
 
 + If it is an integer, it is read as an absolute font height.  The
-  number is basically the point size multiplied by a hundred.  So if you
-  want it to be =18pt= you must pass =180=.  Please understand that setting
-  an absolute value is discouraged, as it will break the layout when you
+  number is basically the point size multiplied by ten.  So if you want
+  it to be =18pt= you must pass =180=.  Please understand that setting an
+  absolute value is discouraged, as it will break the layout when you
   try to change font sizes with the built-in =text-scale-adjust= command
   (see [[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations]]).
 
@@ -910,11 +934,10 @@ resource for finding a consistent scale:
       modus-vivendi-theme-scale-5 1.3)
 #+end_src
 
-Note that in Org, scaling only increases the size of the heading, but
-not of keywords that are added to it, like "TODO".  This is outside the
-control of the themes and I am not aware of any way to make such
-keywords scale accordingly without patching upstream Org (see 
[[https://gitlab.com/protesilaos/modus-themes/-/issues/37][issue 37]]
-in the themes' issue tracker).
+Note that in earlier versions of Org, scaling would only increase the
+size of the heading, but not of keywords that were added to it, like
+"TODO".  The issue has been fixed upstream:
+<https://protesilaos.com/codelog/2020-09-24-org-headings-adapt/>.
 
 ** Option for variable-pitch font in headings
 :PROPERTIES:
@@ -1053,8 +1076,9 @@ With optional \\[universal-argument] prefix, enable
 :CUSTOM_ID: h:defcf4fc-8fa8-4c29-b12e-7119582cc929
 :END:
 
-The themes are designed to cope well with mixed font settings.
-Currently this applies to =org-mode= and =markdown-mode=.
+The themes are designed to cope well with mixed font settings 
([[#h:115e6c23-ee35-4a16-8cef-e2fcbb08e28b][Option
+for no font mixing]]).  Currently this applies to =org-mode= and
+=markdown-mode=.
 
 In practice it means that the user can safely opt for a more
 prose-friendly proportionately spaced typeface as their default, while
@@ -1096,10 +1120,9 @@ when using something like the =text-scale-adjust= 
command which only
 operates on the base font size (i.e. the =default= face's absolute
 height).
 
-An alternative syntax for the =default= face, which the author of this
-documents prefers, is to pass all typeface parameters directly to a =font=
-property.[fn:: Has the benefit of accepting =fontconfig= parameters
-(GNU/Linux), such as ="DejaVu Sans
+An alternative syntax for the =default= face, is to pass all typeface
+parameters directly to a =font= property.[fn:: Has the benefit of
+accepting =fontconfig= parameters (GNU/Linux), such as ="DejaVu Sans
 Mono-11:hintstyle=hintslight:autohint=false"=.
 https://www.freedesktop.org/software/fontconfig/fontconfig-user.html]
 Note that here we use a standard point size:
@@ -1123,8 +1146,8 @@ priority cookies to better match their workflow.  User 
options are
 As those are meant to be custom faces, it would be futile to have the
 themes try to guess what each user would want to use, which keywords to
 target, and so on.  Instead, we can provide guidelines on how to
-customise things to one's liking with the intent to retain the overall
-aesthetics of the theme.
+customise things to one's liking with the intent of retaining the
+overall aesthetics of the theme.
 
 Please bear in mind that the end result of those is not controlled by
 the active theme but by how Org maps faces to its constructs.  Editing
@@ -1157,8 +1180,7 @@ This will refashion the keywords you specify, while 
letting the other
 items in =org-todo-keywords= use their original styles (which are defined
 in the =org-todo= and =org-done= faces).
 
-If you want back the defaults, try specifying just the =org-todo= face (or
-use =org-done= if the meaning of the keywords you use demands as much):
+If you want back the defaults, try specifying just the =org-todo= face:
 
 #+begin_src emacs-lisp
 (setq org-todo-keyword-faces
@@ -1187,8 +1209,8 @@ To find all the faces that are loaded in your current 
Emacs session, use
 the name of each of those Org variables demonstrated above.  Their
 documentation strings will offer you further guidance.
 
-Also consider reading the "Notes for aspiring Emacs theme developers",
-published on 2020-08-28 by Protesilaos Stavrou:
+Furthermore, consider reading the "Notes for aspiring Emacs theme
+developers", published on 2020-08-28 by me (Protesilaos Stavrou):
 https://protesilaos.com/codelog/2020-08-28-notes-emacs-theme-devs/.
 
 * Face coverage
@@ -1707,13 +1729,61 @@ assignment to the Free Software Foundation.  This is 
necessary because
 the themes are part of the upstream Emacs distribution: the FSF must at
 all times be in a position to enforce the GNU General Public License.
 
-Copyright assignment is a simple process.  Check the 
[[https://git.savannah.gnu.org/cgit/gnulib.git/tree/doc/Copyright/request-assign.future][request
 form]].  You
-must write an email to the address mentioned in the form and then wait
-for the FSF to send you a legal agreement.  Sign the document and file
-it back to them.  This could all happen via email and take about a week.
+Copyright assignment is a simple process.  Check the request form below
+(please adapt it accordingly).  You must write an email to the address
+mentioned in the form and then wait for the FSF to send you a legal
+agreement.  Sign the document and file it back to them.  This could all
+happen via email and take about a week.  You are encouraged to go
+through this process.  You only need to do it once.  It will allow you
+to make contributions to Emacs in general.
+
+#+begin_example text
+Please email the following information to assign@gnu.org, and we
+will send you the assignment form for your past and future changes.
+
+Please use your full legal name (in ASCII characters) as the subject
+line of the message.
+----------------------------------------------------------------------
+REQUEST: SEND FORM FOR PAST AND FUTURE CHANGES
+
+[What is the name of the program or package you're contributing to?]
+
+GNU Emacs
+
+[Did you copy any files or text written by someone else in these changes?
+Even if that material is free software, we need to know about it.]
 
-You are encouraged to go through this process.  You only need to do it
-once.  It will allow you to make contributions to Emacs in general.
+Copied a few snippets from the same files I edited.  Their author,
+Protesilaos Stavrou, has already assigned copyright to the Free Software
+Foundation.
+
+[Do you have an employer who might have a basis to claim to own
+your changes?  Do you attend a school which might make such a claim?]
+
+
+[For the copyright registration, what country are you a citizen of?]
+
+
+[What year were you born?]
+
+
+[Please write your email address here.]
+
+
+[Please write your postal address here.]
+
+
+
+
+
+[Which files have you changed so far, and which new files have you written
+so far?]
+
+Changed a couple of themes that are part of the Emacs source code:
+
+./etc/themes/modus-operandi-theme.el
+./etc/themes/modus-vivendi-theme.el
+#+end_example
 
 * Acknowledgements
 :PROPERTIES:
@@ -1733,11 +1803,11 @@ The Modus themes are a collective effort.  Every 
contribution counts.
   Gjorgjevski, David Edmondson, Davor Rotim, Divan Santana, Gerry
   Agbobada, Gianluca Recchia, Iris Garcia, Len Trigg, Manuel Uberti,
   Mark Burton, Markus Beppler, Michael Goldenberg, Murilo Pereira,
-  Nicolas De Jaeghere, Pierre Téchoueyres, Ryan Phillips, Shreyas
-  Ragavan, Tassilo Horn, Thibaut Verron, Trey Merkley, Uri Sharf,
-  Utkarsh Singh, Vincent Foley.  As well as users: Ben, Fourchaux,
-  Fredrik, Moesasji, Nick, TheBlob42, dinko, doolio, jixiuf, okamsn,
-  tycho garen.
+  Nicolas De Jaeghere, Pierre Téchoueyres, Roman Rudakov, Ryan Phillips,
+  Shreyas Ragavan, Tassilo Horn, Thibaut Verron, Trey Merkley, Uri
+  Sharf, Utkarsh Singh, Vincent Foley.  As well as users: Ben,
+  Fourchaux, Fredrik, Moesasji, Nick, TheBlob42, dinko, doolio, jixiuf,
+  okamsn, tycho garen.
 
 + Packaging :: Dhavan Vaidya (Debian), Stefan Kangas (core Emacs),
   Stefan Monnier (GNU Elpa).
@@ -1755,7 +1825,8 @@ this project read the essay 
[[https://protesilaos.com/codelog/2020-03-17-design-
 (2020-03-17).
 
 Here are some more publications for those interested in the kind of work
-that goes into this project:
+that goes into this project (sometimes the commits also include details
+of this sort):
 
 + 
[[https://protesilaos.com/codelog/2020-05-10-modus-operandi-palette-review/][Modus
 Operandi theme subtle palette review]] (2020-05-10)
 + 
[[https://protesilaos.com/codelog/2020-06-13-modus-vivendi-palette-review/][Modus
 Vivendi theme subtle palette review]] (2020-06-13)
@@ -1763,6 +1834,12 @@ that goes into this project:
 + 
[[https://protesilaos.com/codelog/2020-07-08-modus-themes-nuanced-colours/][Modus
 themes: major review of "nuanced" colours]] (2020-07-08)
 + 
[[https://protesilaos.com/codelog/2020-09-14-modus-themes-review-blues/][Modus 
themes: review of blue colours]] (2020-09-14)
 
+And here are the canonical sources for this project's documentation:
+
++ Manual :: <https://protesilaos.com/modus-themes>
++ Change Log :: <https://protesilaos.com/modus-themes-changelog>
++ Screenshots :: <https://protesilaos.com/modus-themes-pictures>
+
 * External projects (ports)
 :PROPERTIES:
 :CUSTOM_ID: h:21adb7c8-2208-41e8-803c-052e42e2c05d
diff --git a/modus-operandi-theme.el b/modus-operandi-theme.el
index e079be3..db61c97 100644
--- a/modus-operandi-theme.el
+++ b/modus-operandi-theme.el
@@ -4,7 +4,7 @@
 
 ;; Author: Protesilaos Stavrou <info@protesilaos.com>
 ;; URL: https://gitlab.com/protesilaos/modus-themes
-;; Version: 0.12.0
+;; Version: 0.13.0
 ;; Package-Requires: ((emacs "26.1"))
 ;; Keywords: faces, theme, accessibility
 
diff --git a/modus-vivendi-theme.el b/modus-vivendi-theme.el
index d8f6b3f..d45c3ca 100644
--- a/modus-vivendi-theme.el
+++ b/modus-vivendi-theme.el
@@ -4,7 +4,7 @@
 
 ;; Author: Protesilaos Stavrou <info@protesilaos.com>
 ;; URL: https://gitlab.com/protesilaos/modus-themes
-;; Version: 0.12.0
+;; Version: 0.13.0
 ;; Package-Requires: ((emacs "26.1"))
 ;; Keywords: faces, theme, accessibility