[elpa] externals/modus-operandi-theme efa3431 63/99: MAJOR REVIEW of Org block custom option

[Stefan Monnier]

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

    MAJOR REVIEW of Org block custom option
    
    Deprecate the "distinct org blocks" and "rainbow org src blocks" boolean
    types.  Replace them with a single symbol that accepts a choice from a
    list that includes the functional equivalents of "greyscale" and
    "rainbow", respectively.
    
    This should make things simpler for users, while it should also reduce
    the risk of mutually-exclusive options being set simultaneously.
---
 README.org              | 96 ++++++++++++++++++-------------------------------
 modus-operandi-theme.el | 64 ++++++++++++++++++++++++++-------
 modus-vivendi-theme.el  | 64 ++++++++++++++++++++++++++-------
 3 files changed, 138 insertions(+), 86 deletions(-)

diff --git a/README.org b/README.org
index 99255c8..e7b1b09 100644
--- a/README.org
+++ b/README.org
@@ -249,84 +249,57 @@ a theme, you can evaluate either of these:
 Consult the section below with the 
[[#h:0e3b8a62-8d72-4439-be2d-cb12ed98f4cb][complete example configuration]] for 
a
 fully fledged =use-package= declaration.
 
-** Option for distinct Org blocks
+** Option for "greyscale" or "rainbow" Org blocks
    :PROPERTIES:
    :CUSTOM_ID: h:ca57a3af-6f79-4530-88c0-e35eda9d3bf7
    :END:
 
-+ =modus-operandi-theme-distinct-org-blocks=
-+ =modus-vivendi-theme-distinct-org-blocks=
-
-Use a distinct neutral background for Org's blocks.  This is the most
-subtle shade of grey used by each theme (it is more subtle than the one
-used for the begin/end lines of the blocks).
-
-The default is to use the same background as the rest of the buffer for
-the contents of the block.
-
-Also see: [[#h:3eebcc85-b104-4774-a742-6dc4dc3dd122][Option for colourful 
"rainbow" Org SRC blocks]].
-
-** Option for colourful "rainbow" Org SRC blocks
-   :PROPERTIES:
-   :CUSTOM_ID: h:3eebcc85-b104-4774-a742-6dc4dc3dd122
-   :END:
-
-+ =modus-operandi-theme-rainbow-org-src-blocks=
-+ =modus-vivendi-theme-rainbow-org-src-blocks=
-
-Apply a colour-coded background to Org src blocks.  The exact colour of
-the background depends on the language being used.  These colours are
-"nuanced" variants of red, green, yellow, blue, magenta, cyan: they are
-designed to work well with all foreground values that are used in
-programming modes (meaning that they respect the minimum 7:1 contrast
-ratio).
-
-The default is to use no background at all: the block is the same as the
-rest of the buffer.
-
-Also see: [[#h:ca57a3af-6f79-4530-88c0-e35eda9d3bf7][Option for distinct Org 
blocks]].
-
-This table summarises the differences between the "rainbow src blocks"
-option, the "distinct blocks" mentioned in the section right above, a
-combination of those two when enabled at the same time, and the
-out-of-the-box experience that the themes provide:
+Symbol names:
 
-#+NAME: modus-themes-org-blocks
-|                  | Block Background   | Beg/End bg       |
-|------------------+--------------------+------------------|
-| default          | None (white/black) | Subtle grey      |
-| distinct blocks  | Most subtle grey   | Subtle grey      |
-| rainbow blocks   | Accented           | Most subtle grey |
-| distinct+rainbow | Mixed (per lang)   | Most subtle grey |
++ =modus-operandi-theme-org-blocks=
++ =modus-vivendi-theme-org-blocks=
 
-*Alternatively* you can avoid setting the "rainbow src blocks" option and
-instead specify your own language and face combinations, while still
-using the bespoke faces defined by the Modus themes.  Here is an example
-that you can put in your Emacs configuration file:
+Possible values:
 
-#+begin_src emacs-lisp
-;; Assign a language to a face:
-;; modus-theme-nuanced-{red,green,yellow,blue,magenta,cyan}
-(setq org-src-block-faces
-      '(("emacs-lisp" 'modus-theme-nuanced-yellow)
-        ("python" 'modus-theme-nuanced-red)))
-#+end_src
+1. =nil= (default)
+2. =greyscale=
+3. =rainbow=
+
+=greyscale= will apply a subtle neutral grey background to the block's
+contents.  It will also extend to the edge of the window the background
+of the "begin" and "end" block delimiter lines (only relevant for Emacs
+versions >= 27 where the ':extend' keyword is recognised by
+=set-face-attribute=).
+
+=rainbow= will instead use an accented background for the contents of the
+block.  The exact colour will depend on the programming language and is
+controlled by the =org-src-block-faces= variable (refer to the theme's
+source code for the current association list).  This is most suitable
+for users who work on literate programming documents that mix and match
+several languages.
 
-Note that if you update the referenced faces using this alternative
-method, you will need to evaluate =org-src-block-faces= and then either
-=M-x org-mode= to refresh the buffer or start typing in each code block.
+The default is to use the same background as the rest of the buffer for
+the contents of the block.
 
-Consider sending 
[[https://gitlab.com/protesilaos/modus-themes/-/issues/57][feedback in issue 
57]] as this option is still subject to
-further refinements.
+Note that the "rainbow" blocks may require you to also reload the
+major-mode so that the colours are applied properly: =M-x org-mode= to
+refresh the buffer.  Or start typing in each code block.
 
 ** Option for colourful "rainbow" headings
    :PROPERTIES:
    :CUSTOM_ID: h:1be42afb-bcd2-4425-b956-0ba93eb960c2
    :END:
 
+Symbol names:
+
 + =modus-operandi-theme-rainbow-headings=
 + =modus-vivendi-theme-rainbow-headings=
 
+Possible values:
+
+1. =nil= (default)
+2. =t=
+
 Apply more saturated colours to headings in =org-mode= and =outline-mode=
 while retaining all other heading properties (such as a bold weight and
 the optional scaled height ---see relevant customisation toggle).  The
@@ -648,8 +621,7 @@ being available.
         modus-operandi-theme-3d-modeline t
         modus-operandi-theme-subtle-diffs t
         modus-operandi-theme-intense-standard-completions t
-        modus-operandi-theme-distinct-org-blocks t
-        modus-operandi-theme-rainbow-org-src-blocks t
+        modus-operandi-theme-org-blocks 'greyscale
         modus-operandi-theme-proportional-fonts t
         modus-operandi-theme-rainbow-headings t
         modus-operandi-theme-section-headings t
diff --git a/modus-operandi-theme.el b/modus-operandi-theme.el
index 355476c..62aca25 100644
--- a/modus-operandi-theme.el
+++ b/modus-operandi-theme.el
@@ -488,16 +488,44 @@ For more on the matter, read the documentation of
   "Use a visible style for fringes."
   :type 'boolean)
 
+(define-obsolete-variable-alias 'modus-operandi-theme-distinct-org-blocks
+  'modus-operandi-theme-org-blocks "`modus-operandi-theme' 0.11.0")
+
 (defcustom modus-operandi-theme-distinct-org-blocks nil
   "Use a distinct neutral background for `org-mode' blocks."
   :type 'boolean)
 
+(define-obsolete-variable-alias 'modus-operandi-theme-rainbow-org-src-blocks
+  'modus-operandi-theme-org-blocks "`modus-operandi-theme' 0.11.0")
+
 (defcustom modus-operandi-theme-rainbow-org-src-blocks nil
   "Use colour-coded backgrounds for `org-mode' source blocks.
 The colour in use depends on the language (send feedback to
 include more languages)."
   :type 'boolean)
 
+(defcustom modus-operandi-theme-org-blocks nil
+  "Use a subtle grey or colour-coded background for Org blocks.
+
+Nil means that the block will have no background of its own and
+will use the default that applies to the rest of the buffer.
+
+Option `greyscale' will apply a subtle neutral grey background to
+the block's contents.  It also affects the begin and end lines of
+the block: their background will be extended to the edge of the
+window for Emacs version >= 27 where the ':extend' keyword is
+recognised by `set-face-attribute'.
+
+Option `rainbow' will use an accented background for the contents
+of the block.  The exact colour will depend on the programming
+language and is controlled by the `org-src-block-faces'
+variable (refer to the theme's source code for the current
+association list)."
+  :type '(choice
+             (const :tag "No Org block background (default)" nil)
+             (const :tag "Subtle grey block background" greyscale)
+             (const :tag "Colour-coded background per programming language" 
rainbow)))
+
 (defcustom modus-operandi-theme-3d-modeline nil
   "Use a three-dimensional style for the active mode line."
   :type 'boolean)
@@ -552,11 +580,15 @@ and the border.  FG is used when no block style is in 
effect."
   "Conditionally set the background of Org blocks.
 BGBLK applies to a distinct neutral background.  Else blocks have
 no background of their own (the default), so they look the same
-as the rest of the buffer."
-  (if modus-operandi-theme-distinct-org-blocks
-      (append
-       (and (>= emacs-major-version 27) '(:extend t))
-       (list :background bgblk))
+as the rest of the buffer.
+
+`modus-operandi-theme-org-blocks' also accepts a `rainbow' option
+which is applied conditionally to `org-src-block-faces' (see the
+theme's source code)."
+  (if (eq modus-operandi-theme-org-blocks 'greyscale)
+    (append
+     (and (>= emacs-major-version 27) '(:extend t))
+     (list :background bgblk))
     (list :background nil)))
 
 (defun modus-operandi-theme-org-block-delim (bgaccent fgaccent bg fg)
@@ -565,14 +597,22 @@ BG, FG, BGACCENT, FGACCENT apply a background and 
foreground
 colour respectively.
 
 The former pair is a greyscale combination that should be more
-distinct than the background of the block.
+distinct than the background of the block.  It is applied to the
+default styles or when `modus-operandi-theme-org-blocks' is set
+to `greyscale'.
 
 The latter pair should be more subtle than the background of the
-block, as it is used when source blocks are cast on a
-coloured/accented backdrop."
-  (if modus-operandi-theme-rainbow-org-src-blocks
-      (list :background bgaccent :foreground fgaccent)
-    (list :background bg :foreground fg)))
+block, as it is used when `modus-operandi-theme-org-blocks' is
+set to `rainbow'."
+  (cond
+   ((eq modus-operandi-theme-org-blocks 'greyscale)
+    (append
+     (and (>= emacs-major-version 27) '(:extend t))
+     (list :background bg :foreground fg)))
+   ((eq modus-operandi-theme-org-blocks 'rainbow)
+    (list :background bgaccent :foreground fgaccent))
+   (t
+    (list :background bg :foreground fg))))
 
 (defun modus-operandi-theme-modeline-box (col3d col &optional btn int)
   "Control the box properties of the mode line.
@@ -3824,7 +3864,7 @@ Also bind `class' to ((class color) (min-colors 89))."
   ;;; Conditional theme variables
   ;;;; org-src-block-faces (this is a user option to add a colour-coded
   ;;;; background to source blocks for various programming languages)
-  (when modus-operandi-theme-rainbow-org-src-blocks
+  (when (eq modus-operandi-theme-org-blocks 'rainbow)
     (custom-theme-set-variables
      'modus-operandi
      `(org-src-block-faces              ; TODO this list should be expanded
diff --git a/modus-vivendi-theme.el b/modus-vivendi-theme.el
index e1f3943..3ed1e8d 100644
--- a/modus-vivendi-theme.el
+++ b/modus-vivendi-theme.el
@@ -488,16 +488,44 @@ For more on the matter, read the documentation of
   "Use a visible style for fringes."
   :type 'boolean)
 
+(define-obsolete-variable-alias 'modus-vivendi-theme-distinct-org-blocks
+  'modus-vivendi-theme-org-blocks "`modus-vivendi-theme' 0.11.0")
+
 (defcustom modus-vivendi-theme-distinct-org-blocks nil
   "Use a distinct neutral background for `org-mode' blocks."
   :type 'boolean)
 
+(define-obsolete-variable-alias 'modus-vivendi-theme-rainbow-org-src-blocks
+  'modus-vivendi-theme-org-blocks "`modus-vivendi-theme' 0.11.0")
+
 (defcustom modus-vivendi-theme-rainbow-org-src-blocks nil
   "Use colour-coded backgrounds for `org-mode' source blocks.
 The colour in use depends on the language (send feedback to
 include more languages)."
   :type 'boolean)
 
+(defcustom modus-vivendi-theme-org-blocks nil
+  "Use a subtle grey or colour-coded background for Org blocks.
+
+Nil means that the block will have no background of its own and
+will use the default that applies to the rest of the buffer.
+
+Option `greyscale' will apply a subtle neutral grey background to
+the block's contents.  It also affects the begin and end lines of
+the block: their background will be extended to the edge of the
+window for Emacs version >= 27 where the ':extend' keyword is
+recognised by `set-face-attribute'.
+
+Option `rainbow' will use an accented background for the contents
+of the block.  The exact colour will depend on the programming
+language and is controlled by the `org-src-block-faces'
+variable (refer to the theme's source code for the current
+association list)."
+  :type '(choice
+             (const :tag "No Org block background (default)" nil)
+             (const :tag "Subtle grey block background" greyscale)
+             (const :tag "Colour-coded background per programming language" 
rainbow)))
+
 (defcustom modus-vivendi-theme-3d-modeline nil
   "Use a three-dimensional style for the active mode line."
   :type 'boolean)
@@ -552,11 +580,15 @@ and the border.  FG is used when no block style is in 
effect."
   "Conditionally set the background of Org blocks.
 BGBLK applies to a distinct neutral background.  Else blocks have
 no background of their own (the default), so they look the same
-as the rest of the buffer."
-  (if modus-vivendi-theme-distinct-org-blocks
-      (append
-       (and (>= emacs-major-version 27) '(:extend t))
-       (list :background bgblk))
+as the rest of the buffer.
+
+`modus-vivendi-theme-org-blocks' also accepts a `rainbow' option
+which is applied conditionally to `org-src-block-faces' (see the
+theme's source code)."
+  (if (eq modus-vivendi-theme-org-blocks 'greyscale)
+    (append
+     (and (>= emacs-major-version 27) '(:extend t))
+     (list :background bgblk))
     (list :background nil)))
 
 (defun modus-vivendi-theme-org-block-delim (bgaccent fgaccent bg fg)
@@ -565,14 +597,22 @@ BG, FG, BGACCENT, FGACCENT apply a background and 
foreground
 colour respectively.
 
 The former pair is a greyscale combination that should be more
-distinct than the background of the block.
+distinct than the background of the block.  It is applied to the
+default styles or when `modus-vivendi-theme-org-blocks' is set
+to `greyscale'.
 
 The latter pair should be more subtle than the background of the
-block, as it is used when source blocks are cast on a
-coloured/accented backdrop."
-  (if modus-vivendi-theme-rainbow-org-src-blocks
-      (list :background bgaccent :foreground fgaccent)
-    (list :background bg :foreground fg)))
+block, as it is used when `modus-vivendi-theme-org-blocks' is
+set to `rainbow'."
+  (cond
+   ((eq modus-vivendi-theme-org-blocks 'greyscale)
+    (append
+     (and (>= emacs-major-version 27) '(:extend t))
+     (list :background bg :foreground fg)))
+   ((eq modus-vivendi-theme-org-blocks 'rainbow)
+    (list :background bgaccent :foreground fgaccent))
+   (t
+    (list :background bg :foreground fg))))
 
 (defun modus-vivendi-theme-modeline-box (col3d col &optional btn int)
   "Control the box properties of the mode line.
@@ -3824,7 +3864,7 @@ Also bind `class' to ((class color) (min-colors 89))."
   ;;; Conditional theme variables
   ;;;; org-src-block-faces (this is a user option to add a colour-coded
   ;;;; background to source blocks for various programming languages)
-  (when modus-vivendi-theme-rainbow-org-src-blocks
+  (when (eq modus-vivendi-theme-org-blocks 'rainbow)
     (custom-theme-set-variables
      'modus-vivendi
      `(org-src-block-faces              ; TODO this list should be expanded