branch: externals/modus-themes
commit b104e2b9f4806a95a9f5d70c46a4772ee64b4dfd
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Update the documentation about building on top of the Modus themes
---
doc/modus-themes.info | 154 ++++++++++++++++++++++++++++++++------------------
doc/modus-themes.org | 55 ++++++++++++++++--
2 files changed, 150 insertions(+), 59 deletions(-)
diff --git a/doc/modus-themes.info b/doc/modus-themes.info
index 275426546f..ebae7b39cc 100644
--- a/doc/modus-themes.info
+++ b/doc/modus-themes.info
@@ -4296,9 +4296,10 @@ File: modus-themes.info, Node: Build on top of the
Modus themes, Next: Face co
This section concerns package developers or advanced users.
The Modus themes can be used as the basis for another theme. The
-‘ef-themes’ package (also by Protesilaos), is one such case. Developers
-may do so to benefit from the extensive customization of the Modus
-themes and the fact that they are part of core Emacs.
+‘ef-themes’ and ‘standard-themes’ packages (also by Protesilaos), are
+two such case. Developers may do so to benefit from the extensive
+customization of the Modus themes and the fact that they are part of
+core Emacs.
A new theme can be instantiated with the macro ‘modus-themes-theme’.
It takes care to (i) declare the theme, (ii) add to it relevant
@@ -4307,7 +4308,8 @@ It takes care to (i) declare the theme, (ii) add to it
relevant
and customizations documented in this manual, and (v) ‘provide-theme’
the theme.
- Concretely, ‘modus-themes-theme’ expects the following arguments:
+ Concretely, ‘modus-themes-theme’ expects the following mandatory
+arguments:
‘NAME’
The name of the new theme, like ‘modus-operandi’.
@@ -4332,8 +4334,19 @@ the theme.
A palette that contains overrides for the above two palettes. It
is functionally equivalent to the ‘USER-PALETTE’, except it is
meant to be customized by the end user. Its value can also be nil.
-
- This is an example of a theme that builds on top of ‘modus-operandi’:
+Optional ‘CUSTOM-FACES’
+ A list of face definitions like those in ‘modus-themes-faces’, to
+ extend or modify what core Modus defines. If provided, they
+ override whatever definition is present in ‘modus-themes-faces’ in
+ case of a conflict. Derivative themes can thus deviate from the
+ style of core Modus, wherever necessary.
+Optional ‘CUSTOM-VARIABLES’
+ A list of custom variables like those defined in
+ ‘modus-themes-custom-variables’. They also override the core Modus
+ definitions in case of a conflict.
+
+ This is an example of a theme that builds on top of ‘modus-operandi’,
+passing all the mandatory arguments, but not the optional ones:
(modus-themes-theme
ef-summer
@@ -4355,6 +4368,35 @@ variables are bound, nor will it declare any
customization options. In
the above example, the ‘ef-summer-palette-overrides’ is a user option
that is declared in that theme's file.
+ In addition to defining their own colors, themes can provide an
+entirely custom list of face definitions and customization options.
+This mirrors the style of ‘modus-themes-faces’ and
+‘modus-themes-custom-variables’, as already noted. For example, the
+‘standard-themes’ have a pseudo-3D style for their active mode line.
+They are declared in this way:
+
+ (modus-themes-theme
+ standard-dark
+ standard-themes
+ "Like the unthemed dark Emacs, but more consistent."
+ dark
+ modus-vivendi-palette
+ standard-dark-palette
+ standard-dard-palette-overrides
+ standard-themes-custom-faces) ; NOTE the additional optional argument
+
+ The ‘standard-themes-custom-faces’ in this example specifies a list
+of face definitions like this:
+
+ ;; Simplified example for illustration purposes
+ (defconst standard-themes-custom-faces
+ '(
+ `(mode-line ((,c :box (:style released-button :color
,border-mode-line-active))))))
+
+ Custom faces passed in this way can still define their semantic
+palette mappings, as illustrated herein where ‘border-mode-line-active’
+corresponds to some named color in the palette of the active theme.
+
Once the theme is instantiated, it will be listed in the return value
of the function ‘modus-themes-get-all-known-themes’. This function
accepts an optional argument to filter themes by their given family.
@@ -6570,15 +6612,15 @@ B.1 Function index
* modus-themes-contrast: DIY Measure color contrast.
(line 6)
* modus-themes-get-all-known-themes: Build on top of the Modus themes.
- (line 71)
+ (line 113)
* modus-themes-get-color-value: Get a single color from the palette
with modus-themes-get-color-value.
(line 6)
* modus-themes-get-themes: Option for which themes to rotate.
(line 19)
* modus-themes-get-themes <1>: Build on top of the Modus themes.
- (line 75)
+ (line 117)
* modus-themes-include-derivatives-mode: Build on top of the Modus themes.
- (line 106)
+ (line 148)
* modus-themes-list-colors: Preview theme colors.
(line 6)
* modus-themes-list-colors-current: Preview theme colors.
@@ -6603,7 +6645,7 @@ B.1 Function index
* modus-themes-select <2>: Disable other themes.
(line 15)
* modus-themes-theme: Build on top of the Modus themes.
- (line 16)
+ (line 17)
* modus-themes-toggle: Enable and load. (line 94)
* modus-themes-toggle <1>: Disable other themes.
(line 15)
@@ -6639,7 +6681,11 @@ B.2 Variable index
* modus-themes-common-palette-user: Palette extension. (line 16)
* modus-themes-completions: Completion UIs. (line 6)
* modus-themes-custom-auto-reload: Custom reload theme. (line 6)
+* modus-themes-custom-variables: Build on top of the Modus themes.
+ (line 56)
* modus-themes-disable-other-themes: Disable other themes. (line 6)
+* modus-themes-faces: Build on top of the Modus themes.
+ (line 50)
* modus-themes-headings: Heading styles. (line 6)
* modus-themes-italic-constructs: Italic constructs. (line 6)
* modus-themes-items: Option for which themes to rotate.
@@ -6657,7 +6703,7 @@ B.2 Variable index
(line 29)
* modus-themes-prompts: Command prompts. (line 6)
* modus-themes-registered-items: Build on top of the Modus themes.
- (line 16)
+ (line 17)
* modus-themes-to-rotate: Option for which themes to rotate.
(line 11)
* modus-themes-to-toggle: Option for which themes to toggle.
@@ -6828,49 +6874,49 @@ Node: DIY Add support for combobulate180021
Node: DIY Use a hook at the post-load-theme phase183644
Node: DIY A theme-agnostic hook for theme loading185765
Node: Build on top of the Modus themes188396
-Node: Face coverage194333
-Node: Supported packages194795
-Node: Indirectly covered packages200661
-Node: Notes on individual packages202017
-Node: Note on calendarel weekday and weekend colors203119
-Node: Note on git-gutter in Doom Emacs204269
-Node: Note on php-mode multiline comments206771
-Node: Note on underlines in compilation buffers207533
-Node: Note on inline Latex in Org buffers208407
-Node: Note on dimmerel209019
-Node: Note on display-fill-column-indicator-mode210506
-Node: Note on highlight-parenthesesel211959
-Node: Note on mmm-modeel background colors218038
-Node: Note for prism220392
-Node: Note on company-mode overlay pop-up223606
-Ref: Note on company-mode overlay pop-up-Footnote-1224336
-Ref: Note on company-mode overlay pop-up-Footnote-2224403
-Node: Note on ERC escaped color sequences224458
-Ref: Note on ERC escaped color sequences-Footnote-1225888
-Node: Note on powerline or spaceline225998
-Node: Note on SHR colors226414
-Node: Note on SHR fonts226836
-Node: Note on Ement colors and fonts227525
-Node: Note on pdf-tools link hints229031
-Node: Note on the Notmuch logo231489
-Node: Note on goto-address-mode faces232023
-Node: Frequently Asked Questions233143
-Node: Is the contrast ratio about adjacent colors?233774
-Node: What does it mean to avoid exaggerations?235283
-Node: Why are colors mostly variants of blue magenta cyan?237133
-Node: What is the best setup for legibility?241467
-Node: Are these color schemes?244109
-Node: Port the Modus themes to other platforms?247763
-Node: Contributing250597
-Node: Sources of the themes250996
-Node: Issues you can help with251892
-Node: Patches require copyright assignment to the FSF253284
-Node: Acknowledgements255506
-Node: GNU Free Documentation License259933
-Node: Indices285096
-Node: Function index285275
-Node: Variable index288763
-Node: Concept index292560
+Node: Face coverage196203
+Node: Supported packages196665
+Node: Indirectly covered packages202531
+Node: Notes on individual packages203887
+Node: Note on calendarel weekday and weekend colors204989
+Node: Note on git-gutter in Doom Emacs206139
+Node: Note on php-mode multiline comments208641
+Node: Note on underlines in compilation buffers209403
+Node: Note on inline Latex in Org buffers210277
+Node: Note on dimmerel210889
+Node: Note on display-fill-column-indicator-mode212376
+Node: Note on highlight-parenthesesel213829
+Node: Note on mmm-modeel background colors219908
+Node: Note for prism222262
+Node: Note on company-mode overlay pop-up225476
+Ref: Note on company-mode overlay pop-up-Footnote-1226206
+Ref: Note on company-mode overlay pop-up-Footnote-2226273
+Node: Note on ERC escaped color sequences226328
+Ref: Note on ERC escaped color sequences-Footnote-1227758
+Node: Note on powerline or spaceline227868
+Node: Note on SHR colors228284
+Node: Note on SHR fonts228706
+Node: Note on Ement colors and fonts229395
+Node: Note on pdf-tools link hints230901
+Node: Note on the Notmuch logo233359
+Node: Note on goto-address-mode faces233893
+Node: Frequently Asked Questions235013
+Node: Is the contrast ratio about adjacent colors?235644
+Node: What does it mean to avoid exaggerations?237153
+Node: Why are colors mostly variants of blue magenta cyan?239003
+Node: What is the best setup for legibility?243337
+Node: Are these color schemes?245979
+Node: Port the Modus themes to other platforms?249633
+Node: Contributing252467
+Node: Sources of the themes252866
+Node: Issues you can help with253762
+Node: Patches require copyright assignment to the FSF255154
+Node: Acknowledgements257376
+Node: GNU Free Documentation License261803
+Node: Indices286966
+Node: Function index287145
+Node: Variable index290633
+Node: Concept index294726
End Tag Table
diff --git a/doc/modus-themes.org b/doc/modus-themes.org
index 5601587e26..4b5a4b0f51 100644
--- a/doc/modus-themes.org
+++ b/doc/modus-themes.org
@@ -4150,9 +4150,10 @@ need to (provided they understand the implications).
This section concerns package developers or advanced users.
The Modus themes can be used as the basis for another theme. The
-~ef-themes~ package (also by Protesilaos), is one such case.
-Developers may do so to benefit from the extensive customization of
-the Modus themes and the fact that they are part of core Emacs.
+~ef-themes~ and ~standard-themes~ packages (also by Protesilaos), are
+two such case. Developers may do so to benefit from the extensive
+customization of the Modus themes and the fact that they are part of
+core Emacs.
#+findex: modus-themes-theme
#+vindex: modus-themes-registered-items
@@ -4162,7 +4163,7 @@ It takes care to (i) declare the theme, (ii) add to it
relevant
(iv) make it work with all the faces and customizations documented
in this manual, and (v) ~provide-theme~ the theme.
-Concretely, ~modus-themes-theme~ expects the following arguments:
+Concretely, ~modus-themes-theme~ expects the following mandatory arguments:
- =NAME= :: The name of the new theme, like ~modus-operandi~.
- =FAMILY= :: The collection this theme is a member of, like ~modus-themes~.
@@ -4181,8 +4182,19 @@ Concretely, ~modus-themes-theme~ expects the following
arguments:
above two palettes. It is functionally equivalent to the
=USER-PALETTE=, except it is meant to be customized by the end user.
Its value can also be nil.
+#+vindex: modus-themes-faces
+- Optional =CUSTOM-FACES= :: A list of face definitions like those in
+ ~modus-themes-faces~, to extend or modify what core Modus defines.
+ If provided, they override whatever definition is present in
+ ~modus-themes-faces~ in case of a conflict. Derivative themes can
+ thus deviate from the style of core Modus, wherever necessary.
+#+vindex: modus-themes-custom-variables
+- Optional =CUSTOM-VARIABLES= :: A list of custom variables like those
+ defined in ~modus-themes-custom-variables~. They also override the
+ core Modus definitions in case of a conflict.
-This is an example of a theme that builds on top of ~modus-operandi~:
+This is an example of a theme that builds on top of ~modus-operandi~,
+passing all the mandatory arguments, but not the optional ones:
#+begin_src emacs-lisp
(modus-themes-theme
@@ -4206,6 +4218,39 @@ the variables are bound, nor will it declare any
customization
options. In the above example, the ~ef-summer-palette-overrides~ is a
user option that is declared in that theme's file.
+In addition to defining their own colors, themes can provide an
+entirely custom list of face definitions and customization options.
+This mirrors the style of ~modus-themes-faces~ and
+~modus-themes-custom-variables~, as already noted. For example, the
+~standard-themes~ have a pseudo-3D style for their active mode line.
+They are declared in this way:
+
+#+begin_src emacs-lisp
+(modus-themes-theme
+ standard-dark
+ standard-themes
+ "Like the unthemed dark Emacs, but more consistent."
+ dark
+ modus-vivendi-palette
+ standard-dark-palette
+ standard-dard-palette-overrides
+ standard-themes-custom-faces) ; NOTE the additional optional argument
+#+end_src
+
+The ~standard-themes-custom-faces~ in this example specifies a list of
+face definitions like this:
+
+#+begin_src emacs-lisp
+;; Simplified example for illustration purposes
+(defconst standard-themes-custom-faces
+ '(
+ `(mode-line ((,c :box (:style released-button :color
,border-mode-line-active))))))
+#+end_src
+
+Custom faces passed in this way can still define their semantic
+palette mappings, as illustrated herein where ~border-mode-line-active~
+corresponds to some named color in the palette of the active theme.
+
#+findex: modus-themes-get-all-known-themes
Once the theme is instantiated, it will be listed in the return value
of the function ~modus-themes-get-all-known-themes~. This function
