[elpa] externals/modus-operandi-theme 53f877a 060/153: Expand manual's entry on modeline 'moody' option

[Stefan Monnier]

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

    Expand manual's entry on modeline 'moody' option
    
    * doc/modus-themes.org (Option for mode line presentation): Inform
    users about the 'distant-foreground' property that is added when
    the 'moody' option is selected.
    
    * doc/modus-themes.info: Recompile the manual.
    
    Special thanks to Nicolas De Jaeghere for all the feedback in issue 80:
    https://gitlab.com/protesilaos/modus-themes/-/issues/80
---
 doc/modus-themes.info | 89 ++++++++++++++++++++++++++++++---------------------
 doc/modus-themes.org  | 20 +++++++++++-
 2 files changed, 72 insertions(+), 37 deletions(-)

diff --git a/doc/modus-themes.info b/doc/modus-themes.info
index f5decb0..eb02334 100644
--- a/doc/modus-themes.info
+++ b/doc/modus-themes.info
@@ -589,8 +589,25 @@ same as what you get when you run Emacs without any 
customisations
    While ‘moody’ removes all box effects from the modelines and applies
 underline and overline properties instead.  It also tones down a bit the
 inactive modelines.  This is meant to optimise things for use with the
-moody package (https://github.com/tarsius/moody), though it can work
-fine even without it.
+moody package (https://github.com/tarsius/moody) (hereinafter referred
+to as “Moody”), though it can work fine even without it.
+
+   Note that Moody does not expose any faces that the themes could style
+directly.  Instead it re-purposes existing ones to render its tabs and
+ribbons.  As such, there may be cases where the contrast ratio falls
+below the 7:1 target that the themes conform with (WCAG AAA). To hedge
+against this, we configure a fallback foreground for the ‘moody’ option,
+which will come into effect when the background of the modeline changes
+to something less accessible, such as Moody ribbons (read the doc string
+of ‘set-face-attribute’, specifically ‘:distant-foreground’).  This
+fallback comes into effect when Emacs determines that the background and
+foreground of the given construct are too close to each other in terms
+of colour distance.  In effect, users would need to experiment with the
+variable ‘face-near-same-color-threshold’ to trigger the fallback
+colour.  We find that a value of ‘45000’ would suffice, contrary to the
+default ‘30000’.  Do not set the value too high, because that would have
+the adverse effect of always overriding the default colour (which has
+been carefully designed to be highly accessible).
 
 
 File: modus-themes.info,  Node: Completion UIs,  Next: Fringes,  Prev: Mode 
line,  Up: Customisation Options
@@ -2280,40 +2297,40 @@ Node: Slanted constructs17977
 Node: Syntax highlighting18568
 Node: Command prompts19297
 Node: Mode line20100
-Node: Completion UIs21354
-Node: Fringes23295
-Node: Line highlighting24059
-Node: Matching parentheses24725
-Node: Diffs25367
-Node: Org mode blocks27160
-Node: Accented headings28666
-Node: Section headings29521
-Node: Scaled headings30706
-Node: Scaled heading sizes31325
-Node: Headings' font33284
-Node: Advanced customisation (do-it-yourself)33908
-Node: Tweak colours (DIY)34912
-Node: Font configs (DIY)38546
-Ref: Font configs (DIY)-Footnote-141126
-Ref: Font configs (DIY)-Footnote-241313
-Node: Org user faces (DIY)41535
-Node: Face coverage44756
-Node: Supported packages45258
-Node: Covered indirectly51199
-Node: Will NOT be supported51551
-Node: Notes for individual packages52269
-Node: Note for powerline or spaceline52675
-Node: Note on shr colours53047
-Node: Note for Helm grep53460
-Node: Note on vc-annotate-background-mode54907
-Node: Contributing55761
-Node: Sources of the themes56180
-Node: Issues you can help with56942
-Node: Merge requests58129
-Node: Acknowledgements59211
-Node: Meta60668
-Node: External projects (ports)61721
-Node: GNU Free Documentation License62544
+Node: Completion UIs22537
+Node: Fringes24478
+Node: Line highlighting25242
+Node: Matching parentheses25908
+Node: Diffs26550
+Node: Org mode blocks28343
+Node: Accented headings29849
+Node: Section headings30704
+Node: Scaled headings31889
+Node: Scaled heading sizes32508
+Node: Headings' font34467
+Node: Advanced customisation (do-it-yourself)35091
+Node: Tweak colours (DIY)36095
+Node: Font configs (DIY)39729
+Ref: Font configs (DIY)-Footnote-142309
+Ref: Font configs (DIY)-Footnote-242496
+Node: Org user faces (DIY)42718
+Node: Face coverage45939
+Node: Supported packages46441
+Node: Covered indirectly52382
+Node: Will NOT be supported52734
+Node: Notes for individual packages53452
+Node: Note for powerline or spaceline53858
+Node: Note on shr colours54230
+Node: Note for Helm grep54643
+Node: Note on vc-annotate-background-mode56090
+Node: Contributing56944
+Node: Sources of the themes57363
+Node: Issues you can help with58125
+Node: Merge requests59312
+Node: Acknowledgements60394
+Node: Meta61851
+Node: External projects (ports)62904
+Node: GNU Free Documentation License63727
 
 End Tag Table
 
diff --git a/doc/modus-themes.org b/doc/modus-themes.org
index 99b891d..3d23dd9 100644
--- a/doc/modus-themes.org
+++ b/doc/modus-themes.org
@@ -462,7 +462,25 @@ command line).
 While =moody= removes all box effects from the modelines and applies
 underline and overline properties instead.  It also tones down a bit the
 inactive modelines.  This is meant to optimise things for use with the
-[[https://github.com/tarsius/moody][moody package]], though it can work fine 
even without it.
+[[https://github.com/tarsius/moody][moody package]] (hereinafter referred to 
as "Moody"), though it can work
+fine even without it.
+
+Note that Moody does not expose any faces that the themes could style
+directly.  Instead it re-purposes existing ones to render its tabs and
+ribbons.  As such, there may be cases where the contrast ratio falls
+below the 7:1 target that the themes conform with (WCAG AAA).  To hedge
+against this, we configure a fallback foreground for the =moody= option,
+which will come into effect when the background of the modeline changes
+to something less accessible, such as Moody ribbons (read the doc string
+of =set-face-attribute=, specifically =:distant-foreground=).  This fallback
+comes into effect when Emacs determines that the background and
+foreground of the given construct are too close to each other in terms
+of colour distance.  In effect, users would need to experiment with the
+variable =face-near-same-color-threshold= to trigger the fallback colour.
+We find that a value of =45000= would suffice, contrary to the default
+=30000=.  Do not set the value too high, because that would have the
+adverse effect of always overriding the default colour (which has been
+carefully designed to be highly accessible).
 
 ** Option for completion framework aesthetics
 :PROPERTIES: