[elpa] externals/modus-operandi-theme 624cbd6 46/99: Improve README for Org-block-related options

[Stefan Monnier]

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

    Improve README for Org-block-related options
    
    See issue 57 for screenshots (and to send feedback):
    https://gitlab.com/protesilaos/modus-themes/-/issues/57
---
 README.org | 43 +++++++++++++++++++++++++++++--------------
 1 file changed, 29 insertions(+), 14 deletions(-)

diff --git a/README.org b/README.org
index 261d2ab..848ff1c 100644
--- a/README.org
+++ b/README.org
@@ -207,9 +207,10 @@ background of their beginning and end lines to the edge of 
the window
 would extend regardless).
 
 The default is to use the same background as the rest of the buffer for
-the contents of the block, while beginning and end lines do not extend
-to the end of the window (again, the "extend" is for Emacs 27 or
-higher).
+the contents of the block.  The beginning and end lines do not extend to
+the end of the window, meaning that their background is only applied to
+the area covered by their respective keywords (again, the "extend" is
+only relevant for Emacs 27 or higher).
 
 Also see: [[#h:3eebcc85-b104-4774-a742-6dc4dc3dd122][Option for colourful 
"rainbow" Org SRC blocks]].
 
@@ -223,15 +224,28 @@ Also see: 
[[#h:3eebcc85-b104-4774-a742-6dc4dc3dd122][Option for colourful "rainb
 
 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 (it is the same as the rest
-of the buffer).
-
-*Alternatively* you can specify your own language+face combination.  Here
-is an example that you can put in your Emacs configuration file:
+ratio).  To make the block feel like a complete rectangle, the special
+keywords that delimit the beginning and end of the block explicitly have
+their background extended to the edge of the window.
+
+The default is to use no background at all, meaning that the block is
+the same as the rest of the buffer, while the begin/end lines only apply
+a background colour to the area covered by the length of their
+respective keywords.
+
+This is also true for the "distinct Org blocks" option mentioned in the
+previous section.  Compared to that other option, the "begin" and "end"
+lines of Org blocks will have a subtler grey background, so that the
+focus is on the more colourful block (whereas the "distinct Org blocks"
+option retains the same shade of grey as the default looks, which is a
+bit more pronounced, and only appends the =:extend t= property).
+
+*Alternatively* you can avoid setting the "rainbow src blocks" option and
+instead specify your own language and face combination.  Here is an
+example that you can put in your Emacs configuration file:
 
 #+begin_src emacs-lisp
 (setq org-src-block-faces
@@ -241,11 +255,12 @@ is an example that you can put in your Emacs 
configuration file:
 
 The faces: =modus-theme-nuanced-{red,green,yellow,blue,magenta,cyan}=.
 
-Note that if you update the referenced faces, 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.
+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.
 
-Consider sending 
[[https://gitlab.com/protesilaos/modus-themes/-/issues/57][feedback in issue 
57]].
+Consider sending 
[[https://gitlab.com/protesilaos/modus-themes/-/issues/57][feedback in issue 
57]] as this option is still subject to
+further refinements.
 
 Also see: [[#h:ca57a3af-6f79-4530-88c0-e35eda9d3bf7][Option for distinct Org 
blocks]].