branch: externals/standard-themes
commit b594df646b99d55acba3ccff3109bd322a3278f0
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Update to version 1.2.0
---
CHANGELOG.org | 126 +++++++++++++++++++++++++++++++++++++++++++++++++++++
README.org | 16 ++-----
standard-themes.el | 2 +-
3 files changed, 130 insertions(+), 14 deletions(-)
diff --git a/CHANGELOG.org b/CHANGELOG.org
index 09fe1c9a8c..c23dfd7412 100644
--- a/CHANGELOG.org
+++ b/CHANGELOG.org
@@ -9,6 +9,132 @@ project's main git repository:
<https://git.sr.ht/~protesilaos/standard-themes>.
The newest release is at the top. For further details, please consult
the manual: <https://protesilaos.com/emacs/standard-themes>.
+* Version 1.2.0 on 2023-02-16
+
+** Support for palette overrides
+
+It is now possible to override the palette of each Standard theme.
+This is the same feature that I implemented for the ~modus-themes~,
+except it is a bit more limited in scope (the Modus themes are
+maximalist due to their accessibility target).
+
+Overrides allow the user to tweak the presentation of either or both
+themes, such as to change the colour value of individual entries
+and/or remap how named colours are applied to semantic code
+constructs.
+
+For example, the user can change what the exact value of ~blue-warmer~
+is and then, say, make comments use a shade of green instead of red.
+
+There are three user options to this end:
+
++ ~standard-themes-common-palette-overrides~ which covers both themes.
++ ~standard-dark-palette-overrides~ which concerns the dark theme.
++ ~standard-light-palette-overrides~ which is for the light theme.
+
+The theme-specific overrides take precedence over the "common" ones.
+
+The theme's palette with named colors can be previewed with the
+commands ~standard-themes-preview-colors~ and
+~standard-themes-preview-colors-current~. When called with a
+universal prefix argument (=C-u= with default key bindings) these
+commands produce a preview of the semantic colour mappings (e.g. what
+colour applies to level 2 headings).
+
+Use the preview as a reference to find entries to override. And
+consult the manual for the technicalities.
+
+Thanks to Clemens Radermacher for fixing a mistake I made in the code
+that produces the palette previews.
+
+** Added the function ~standard-themes-get-color-value~
+
+It returns the colour value of named =COLOR= for the current Standard
+theme.
+
+=COLOR= is a symbol that represents a named colour entry in the
+palette.
+
+If the value is the name of another colour entry in the palette (so a
+mapping), recur until you find the underlying colour value.
+
+With optional =OVERRIDES= as a non-nil value, account for palette
+overrides. Else use the default palette.
+
+With optional =THEME= as a symbol among ~standard-themes-items~, use
+the palette of that item. Else use the current Standard theme.
+
+If =COLOR= is not present in the palette, return the ~unspecified~
+symbol, which is safe when used as a face attribute's value.
+
+The manual provides this information and also links to relevant
+entries. The example it uses, with the ~standard-light~ as current:
+
+#+begin_src emacs-lisp
+;; Here we show the recursion of palette mappings. In general, it is
+;; better for the user to specify named colors to avoid possible
+;; confusion with their configuration, though those still work as
+;; expected.
+(setq standard-themes-common-palette-overrides
+ '((cursor red)
+ (prompt cursor)
+ (variable prompt)))
+
+;; Ignore the overrides and get the original value.
+(standard-themes-get-color-value 'variable)
+;; => "#a0522d"
+
+;; Read from the overrides and deal with any recursion to find the
+;; underlying value.
+(standard-themes-get-color-value 'variable :overrides)
+;; => "#b3303a"
+#+end_src
+
+** New user option ~standard-themes-disable-other-themes~
+
+This user option is set to ~t~ by default. This means that loading a
+Standard theme with the command ~standard-themes-toggle~ or the
+functions ~standard-theme-load-dark~, ~standard-theme-load-light~
+will disable all ~custom-enabled-themes~.
+
+When the value of this user option is nil, themes are loaded without
+disabling other entries outside their family. This retains the
+original (and in my opinion bad for most users) behaviour of Emacs
+where it blithely blends multiple enabled themes.
+
+I consider the blending a bad default because it undoes the work of
+the designer and often leads to highly inaccessible and unpredictable
+combinations. Sure, experts can blend themes which is an argument in
+favour of making that behaviour opt-in.
+
+** Other changes
+
++ Refined the ~standard-dark~ theme's ~bg-hl-line~ background. This
+ makes it easier to read the underlying text of the currently
+ highlighted line in hl-line-mode.
+
+ Thanks to Manuel Uberti for the feedback on the mailing list:
+
<https://lists.sr.ht/~protesilaos/standard-themes/%3C6e218fc0-f2dc-e03f-4e42-da0cbf9bd79b%40inventati.org%3E>.
+
++ Clarified some statements in the documentation about the 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>.
+
+** Acknowledgement
+
+Thanks to Fritz Grabo who provided feedback via a private channel.
+With it, I was able to better understand the underlying patterns of
+the out-of-the-box Emacs faces and thus design the ~standard-themes~
+accordingly. This information is shared with permission.
+
+As a reminder, the Standard themes are an interpretation of the
+default Emacs faces (which technically are not a "theme"). I have
+expanded the effective palette with harmonious entries, made mappings
+that are consistent with the patterns found in some base faces, and
+extended support for lots of packages. At first sight, the Standard
+themes look like what you get with an unconfigured Emacs. Though make
+no mistake: they are far more detail-oriented.
+
* Version 1.1.0 on 2022-12-06
:PROPERTIES:
:CUSTOM_ID: h:f7a5799c-279c-4dfb-96ae-3eba58ee582e
diff --git a/README.org b/README.org
index f9e7a66676..8b2dd06185 100644
--- a/README.org
+++ b/README.org
@@ -4,9 +4,9 @@
#+language: en
#+options: ':t toc:nil author:t email:t num:t
#+startup: content
-#+macro: stable-version 1.1.0
-#+macro: release-date 2022-12-06
-#+macro: development-version 1.2.0-dev
+#+macro: stable-version 1.2.0
+#+macro: release-date 2023-02-16
+#+macro: development-version 1.3.0-dev
#+export_file_name: standard-themes.texi
#+texinfo_filename: standard-themes.info
#+texinfo_dir_category: Emacs misc features
@@ -191,8 +191,6 @@ re-load ([[#h:59c399d6-5dca-4686-b793-255be8bffc31][Loading
a theme]]).
:CUSTOM_ID: h:bc4827ec-7ec1-4511-ae1b-491c28835b19
:END:
-[ Part of {{{development-version}}}. ]
-
#+vindex: standard-themes-disable-other-themes
The user option ~standard-themes-disable-other-themes~ controls which
themes to disable when loading a Standard theme
([[#h:59c399d6-5dca-4686-b793-255be8bffc31][Loading a theme]]).
@@ -545,10 +543,6 @@ Other examples:
:END:
#+cindex: Override color values and semantic color mappings
-[ Part of {{{development-version}}}. For a video demo of the same
-idea that I implemented in the ~modus-themes~, check:
-https://protesilaos.com/codelog/2022-12-17-modus-themes-v4-demo/. ]
-
The Standard themes define their own color palette as well as semantic
color mappings. The former is the set of color values such as what
shade of blue to use. The latter refers to associations between a
@@ -658,8 +652,6 @@ These two functions are also called by the command
:CUSTOM_ID: h:1eebe221-0d0c-43e8-877a-202d2f15ef34
:END:
-[ Updated as part of {{{development-version}}}. ]
-
#+findex: standard-themes-preview-colors
The command ~standard-themes-preview-colors~ uses minibuffer
completion to select an item from the Standard themes and then
@@ -740,8 +732,6 @@ liking, often by employing the
~standard-themes-with-colors~ macro
:CUSTOM_ID: h:cc1633d3-8e83-45b5-b258-804935f9ee0d
:END:
-[ Part of {{{development-version}}}. ]
-
[[#h:a6d48445-c215-4f2e-b0ff-c83b0c673fa7][The general approach to advanced
DIY changes]].
#+findex: standard-themes-get-color-value
diff --git a/standard-themes.el b/standard-themes.el
index 612e413a36..5f69af1ff2 100644
--- a/standard-themes.el
+++ b/standard-themes.el
@@ -6,7 +6,7 @@
;; Maintainer: Standard-Themes Development
<~protesilaos/standard-the...@lists.sr.ht>
;; URL: https://git.sr.ht/~protesilaos/standard-themes
;; Mailing-List: https://lists.sr.ht/~protesilaos/standard-themes
-;; Version: 1.1.0
+;; Version: 1.2.0
;; Package-Requires: ((emacs "27.1"))
;; Keywords: faces, theme, accessibility
