[elpa] externals/modus-operandi-theme 0bcb9d8 082/153: Add note in manual on ERC escaped colour sequences

[Stefan Monnier]

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

    Add note in manual on ERC escaped colour sequences
    
    This concerns issue 92:
    https://gitlab.com/protesilaos/modus-themes/-/issues/92
    
    Thanks to Dario Gjorgjevski for the valuable feedback!
---
 doc/modus-themes.info | 162 +++++++++++++++++++++++++++++++-------------------
 doc/modus-themes.org  |  33 ++++++++++
 2 files changed, 135 insertions(+), 60 deletions(-)

diff --git a/doc/modus-themes.info b/doc/modus-themes.info
index 948229a..4949ec7 100644
--- a/doc/modus-themes.info
+++ b/doc/modus-themes.info
@@ -103,6 +103,7 @@ Face coverage
 
 Notes for individual packages
 
+* Note for ERC escaped colour sequences::
 * Note for powerline or spaceline::
 * Note on shr colours::
 * Note for Helm grep::
@@ -1607,15 +1608,54 @@ individual packages.
 
 * Menu:
 
+* Note for ERC escaped colour sequences::
 * Note for powerline or spaceline::
 * Note on shr colours::
 * Note for Helm grep::
 * Note on vc-annotate-background-mode::
 
 
-File: modus-themes.info,  Node: Note for powerline or spaceline,  Next: Note 
on shr colours,  Up: Notes for individual packages
+File: modus-themes.info,  Node: Note for ERC escaped colour sequences,  Next: 
Note for powerline or spaceline,  Up: Notes for individual packages
 
-7.1 Note for powerline or spaceline
+7.1 Note for ERC escaped colour sequences
+=========================================
+
+The built-in IRC client ‘erc’ has the ability to colourise any text
+using escape sequences that start with ‘^C’ (inserted with ‘C-q C-c’)
+and are followed by a number for the foreground and background.(1)
+Possible numbers are 0-15, with the first entry being the foreground and
+the second the background, separated by a comma.  Like this ‘^C1,6’.
+The minimum setup is this:
+
+     (add-to-list 'erc-modules 'irccontrols)
+     (setq erc-interpret-controls-p t
+           erc-interpret-mirc-color t)
+
+   As this allows users to make arbitrary combinations, it is impossible
+to guarantee a consistently high contrast ratio.  All we can we do is
+provide guidance on the combinations that satisfy the accessibility
+standard of the themes:
+
+Modus Operandi
+     Use foreground colour 1 for all backgrounds from 2-15.  Like so:
+     ‘C-q C-c1,N’ where ‘N’ is the background.
+
+Modus Vivendi
+     Use foreground colour 0 for all backgrounds from 2-13.  Use
+     foreground ‘1’ for backgrounds 14, 15.
+
+   Colours 0 and 1 are white and black respectively.  So combine them
+together, if you must.
+
+   ---------- Footnotes ----------
+
+   (1) This page explains the basics, though it is not specific to
+Emacs: <https://www.mirc.com/colors.html>
+
+
+File: modus-themes.info,  Node: Note for powerline or spaceline,  Next: Note 
on shr colours,  Prev: Note for ERC escaped colour sequences,  Up: Notes for 
individual packages
+
+7.2 Note for powerline or spaceline
 ===================================
 
 Both Powerline and Spaceline package users will likely need to use the
@@ -1625,7 +1665,7 @@ and/or modeline setup.
 
 File: modus-themes.info,  Node: Note on shr colours,  Next: Note for Helm 
grep,  Prev: Note for powerline or spaceline,  Up: Notes for individual packages
 
-7.2 Note on shr colours
+7.3 Note on shr colours
 =======================
 
 Emacs’ HTML rendering mechanism (‘shr’) may need explicit configuration
@@ -1635,7 +1675,7 @@ webpage provides.  Consult ‘C-h v shr-use-colors’.
 
 File: modus-themes.info,  Node: Note for Helm grep,  Next: Note on 
vc-annotate-background-mode,  Prev: Note on shr colours,  Up: Notes for 
individual packages
 
-7.3 Note for Helm grep
+7.4 Note for Helm grep
 ======================
 
 There is one face from the Helm package that is meant to highlight the
@@ -1665,7 +1705,7 @@ ANSI colour number 1 (red) from the already-supported 
array of
 
 File: modus-themes.info,  Node: Note on vc-annotate-background-mode,  Prev: 
Note for Helm grep,  Up: Notes for individual packages
 
-7.4 Note on vc-annotate-background-mode
+7.5 Note on vc-annotate-background-mode
 =======================================
 
 Due to the unique way ‘vc-annotate’ (‘C-x v g’) applies colours, support
@@ -2307,61 +2347,63 @@ Appendix A GNU Free Documentation License
 
 Tag Table:
 Node: Top218
-Node: Overview3832
-Node: How do the themes look like5517
-Node: Installation6000
-Node: Install from the archives6650
-Node: Install on GNU/Linux7337
-Node: Debian 11 Bullseye7782
-Node: GNU Guix8191
-Node: Enable and load8542
-Node: Load automatically9119
-Node: Load at a given time or at sunset/sunrise9678
-Ref: Load at a given time or at sunset/sunrise-Footnote-111716
-Ref: Load at a given time or at sunset/sunrise-Footnote-211844
-Node: Toggle between the themes on demand11927
-Node: Configure options prior to loading12674
-Ref: Configure options prior to loading-Footnote-115270
-Node: Customisation Options15445
-Node: Bold constructs17125
-Node: Slanted constructs18124
-Node: Syntax highlighting18715
-Node: Link underline19443
-Node: Command prompts19930
-Node: Mode line20728
-Node: Completion UIs23165
-Node: Fringes25106
-Node: Line highlighting25870
-Node: Matching parentheses26536
-Node: Diffs27180
-Node: Org mode blocks28973
-Node: Heading styles30476
-Node: Scaled headings33865
-Node: Scaled heading sizes34482
-Node: Headings' font36441
-Node: Advanced customisation (do-it-yourself)37065
-Node: Tweak colours (DIY)38069
-Node: Font configs (DIY)41703
-Ref: Font configs (DIY)-Footnote-144283
-Ref: Font configs (DIY)-Footnote-244470
-Node: Org user faces (DIY)44692
-Node: Face coverage47913
-Node: Supported packages48415
-Node: Covered indirectly54374
-Node: Will NOT be supported54743
-Node: Notes for individual packages55461
-Node: Note for powerline or spaceline55867
-Node: Note on shr colours56239
-Node: Note for Helm grep56652
-Node: Note on vc-annotate-background-mode58099
-Node: Contributing58953
-Node: Sources of the themes59372
-Node: Issues you can help with60134
-Node: Merge requests61321
-Node: Acknowledgements62403
-Node: Meta63667
-Node: External projects (ports)64720
-Node: GNU Free Documentation License65543
+Node: Overview3874
+Node: How do the themes look like5559
+Node: Installation6042
+Node: Install from the archives6692
+Node: Install on GNU/Linux7379
+Node: Debian 11 Bullseye7824
+Node: GNU Guix8233
+Node: Enable and load8584
+Node: Load automatically9161
+Node: Load at a given time or at sunset/sunrise9720
+Ref: Load at a given time or at sunset/sunrise-Footnote-111758
+Ref: Load at a given time or at sunset/sunrise-Footnote-211886
+Node: Toggle between the themes on demand11969
+Node: Configure options prior to loading12716
+Ref: Configure options prior to loading-Footnote-115312
+Node: Customisation Options15487
+Node: Bold constructs17167
+Node: Slanted constructs18166
+Node: Syntax highlighting18757
+Node: Link underline19485
+Node: Command prompts19972
+Node: Mode line20770
+Node: Completion UIs23207
+Node: Fringes25148
+Node: Line highlighting25912
+Node: Matching parentheses26578
+Node: Diffs27222
+Node: Org mode blocks29015
+Node: Heading styles30518
+Node: Scaled headings33907
+Node: Scaled heading sizes34524
+Node: Headings' font36483
+Node: Advanced customisation (do-it-yourself)37107
+Node: Tweak colours (DIY)38111
+Node: Font configs (DIY)41745
+Ref: Font configs (DIY)-Footnote-144325
+Ref: Font configs (DIY)-Footnote-244512
+Node: Org user faces (DIY)44734
+Node: Face coverage47955
+Node: Supported packages48457
+Node: Covered indirectly54416
+Node: Will NOT be supported54785
+Node: Notes for individual packages55503
+Node: Note for ERC escaped colour sequences55951
+Ref: Note for ERC escaped colour sequences-Footnote-157334
+Node: Note for powerline or spaceline57444
+Node: Note on shr colours57862
+Node: Note for Helm grep58275
+Node: Note on vc-annotate-background-mode59722
+Node: Contributing60576
+Node: Sources of the themes60995
+Node: Issues you can help with61757
+Node: Merge requests62944
+Node: Acknowledgements64026
+Node: Meta65290
+Node: External projects (ports)66343
+Node: GNU Free Documentation License67166
 
 End Tag Table
 
diff --git a/doc/modus-themes.org b/doc/modus-themes.org
index 1f06542..a2abacb 100644
--- a/doc/modus-themes.org
+++ b/doc/modus-themes.org
@@ -1480,6 +1480,39 @@ and the intended styles for the content you are actually 
working on.
 This section covers information that may be of interest to users of
 individual packages.
 
+** Note for ERC escaped colour sequences
+:PROPERTIES:
+:CUSTOM_ID: h:98bdf319-1e32-4469-8a01-771200fba65c
+:END:
+
+The built-in IRC client =erc= has the ability to colourise any text using
+escape sequences that start with =^C= (inserted with =C-q C-c=) and are
+followed by a number for the foreground and background.[fn:: This page
+explains the basics, though it is not specific to Emacs:
+https://www.mirc.com/colors.html] Possible numbers are 0-15, with the
+first entry being the foreground and the second the background,
+separated by a comma.  Like this =^C1,6=.  The minimum setup is this:
+
+#+begin_src emacs-lisp
+(add-to-list 'erc-modules 'irccontrols)
+(setq erc-interpret-controls-p t
+      erc-interpret-mirc-color t)
+#+end_src
+
+As this allows users to make arbitrary combinations, it is impossible to
+guarantee a consistently high contrast ratio.  All we can we do is
+provide guidance on the combinations that satisfy the accessibility
+standard of the themes:
+
++ Modus Operandi :: Use foreground colour 1 for all backgrounds from
+  2-15.  Like so: =C-q C-c1,N= where =N= is the background.
+
++ Modus Vivendi :: Use foreground colour 0 for all backgrounds from
+  2-13.  Use foreground =1= for backgrounds 14, 15.
+
+Colours 0 and 1 are white and black respectively.  So combine them
+together, if you must.
+
 ** Note for powerline or spaceline
 :PROPERTIES:
 :CUSTOM_ID: h:9130a8ba-d8e3-41be-a58b-3cb1eb7b6d17