[elpa] externals/standard-themes 08beba43e6: Improve doc strings of palette overrides

[ELPA Syncer]

branch: externals/standard-themes
commit 08beba43e6c66afb7dd215e7753c2b79c02c0a98
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Improve doc strings of palette overrides
    
    Thanks to Tassilo Horn for the feedback on the mailing list:
    
<https://lists.sr.ht/~protesilaos/standard-themes/%3C87cz8bjrwz.fsf%40gnu.org%3E>.
---
 README.org              |  3 ++-
 standard-dark-theme.el  | 23 +++++++++++++++++++++--
 standard-light-theme.el | 23 +++++++++++++++++++++--
 standard-themes.el      | 16 +++++++++++++---
 4 files changed, 57 insertions(+), 8 deletions(-)

diff --git a/README.org b/README.org
index ff3e15c36c..50ceda52b4 100644
--- a/README.org
+++ b/README.org
@@ -1239,7 +1239,8 @@ matters.
 
 + Contributions to code :: Clemens Radermacher.
 
-+ Ideas and/or user feedback :: Fritz Grabo, Manuel Uberti.
++ Ideas and/or user feedback :: Fritz Grabo, Manuel Uberti, Tassilo
+  Horn.
 
 * GNU Free Documentation License
 :PROPERTIES:
diff --git a/standard-dark-theme.el b/standard-dark-theme.el
index 79d1a94b6c..41c6acf599 100644
--- a/standard-dark-theme.el
+++ b/standard-dark-theme.el
@@ -212,10 +212,29 @@
       (prose-code cyan-cooler)
       (prose-macro green-warmer)
       (prose-verbatim magenta-warmer))
-    "The `standard-dark' palette.")
+    "The `standard-dark' palette.
+Color values have the form (COLOR-NAME HEX-VALUE) with the former
+as a symbol and the latter as a string.
+
+Semantic color mappings have the form (MAPPING-NAME COLOR-NAME)
+with both as symbols.  The latter is a color that already exists
+in the palette and is associated with a HEX-VALUE.")
 
   (defvar standard-dark-palette-overrides nil
-    "Overrides for `standard-dark-palette'.")
+    "Overrides for `standard-dark-palette'.
+
+Mirror the elements of the aforementioned palette, overriding
+their value.
+
+For overrides that are shared across all of the Standard themes,
+refer to `standard-themes-common-palette-overrides'.
+
+Theme-specific overrides take precedence over shared overrides.
+The idea of common overrides is to change semantic color
+mappings, such as to make the cursor red.  Wherea theme-specific
+overrides can also be used to change the value of a named color,
+such as what hexadecimal RGB value the red-warmer symbol
+represents.")
 
   (standard-themes-theme standard-dark
                          standard-dark-palette
diff --git a/standard-light-theme.el b/standard-light-theme.el
index 8544c0be8a..73d0e05312 100644
--- a/standard-light-theme.el
+++ b/standard-light-theme.el
@@ -212,10 +212,29 @@
       (prose-code cyan-cooler)
       (prose-macro green-warmer)
       (prose-verbatim magenta))
-    "The `standard-light' palette.")
+    "The `standard-light' palette.
+Color values have the form (COLOR-NAME HEX-VALUE) with the former
+as a symbol and the latter as a string.
+
+Semantic color mappings have the form (MAPPING-NAME COLOR-NAME)
+with both as symbols.  The latter is a color that already exists
+in the palette and is associated with a HEX-VALUE.")
 
   (defvar standard-light-palette-overrides nil
-    "Overrides for `standard-light-palette'.")
+    "Overrides for `standard-light-palette'.
+
+Mirror the elements of the aforementioned palette, overriding
+their value.
+
+For overrides that are shared across all of the Standard themes,
+refer to `standard-themes-common-palette-overrides'.
+
+Theme-specific overrides take precedence over shared overrides.
+The idea of common overrides is to change semantic color
+mappings, such as to make the cursor red.  Wherea theme-specific
+overrides can also be used to change the value of a named color,
+such as what hexadecimal RGB value the red-warmer symbol
+represents.")
 
   (standard-themes-theme standard-light
                          standard-light-palette
diff --git a/standard-themes.el b/standard-themes.el
index ae3e312c1b..114a843937 100644
--- a/standard-themes.el
+++ b/standard-themes.el
@@ -1989,11 +1989,21 @@ Helper function for `standard-themes-preview-colors'."
 
 Mirror the elements of a theme's palette, overriding their value.
 The palette variables are named THEME-NAME-palette, while
-individual theme overrides are THEME-NAME-palette-overrides.  The
-THEME-NAME is one of the symbols in `standard-themes-items'.
+individual theme overrides are THEME-NAME-palette-overrides:
+
+- `standard-dark-palette'
+- `standard-dark-palette-overrides'
+- `standard-light-palette'
+- `standard-light-palette-overrides'
 
 Individual theme overrides take precedence over these common
-overrides.")
+overrides.
+
+The idea of common overrides is to change semantic color
+mappings, such as to make the cursor red.  Wherea theme-specific
+overrides can also be used to change the value of a named color,
+such as what hexadecimal RGB value the red-warmer symbol
+represents.")
 
 ;;;###autoload
 (defmacro standard-themes-theme (name palette &optional overrides)