branch: externals/modus-themes
commit f71a62c50f3550665565752d3fb7f46b2d94456f
Author: Protesilaos Stavrou <[email protected]>
Commit: Protesilaos Stavrou <[email protected]>
Update the documentation about building on top of the Modus themes
---
doc/modus-themes.info | 171 ++++++++++++++++++++++++++------------------------
doc/modus-themes.org | 79 ++++++++++++-----------
2 files changed, 132 insertions(+), 118 deletions(-)
diff --git a/doc/modus-themes.info b/doc/modus-themes.info
index c98571e160..3a3778469a 100644
--- a/doc/modus-themes.info
+++ b/doc/modus-themes.info
@@ -4276,9 +4276,9 @@ 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
-‘theme-properties’, (iii) register it in the
+ A new theme can be instantiated with the function
+‘modus-themes-theme’. It takes care to (i) declare the theme, (ii) add
+to it relevant ‘theme-properties’, (iii) register it in the
‘modus-themes-registered-items’, (iv) make it work with all the faces
and customizations documented in this manual, and (v) ‘provide-theme’
the theme.
@@ -4287,36 +4287,43 @@ the theme.
arguments:
‘NAME’
- The name of the new theme, like ‘modus-operandi’.
+ The name of the new theme as a symbol, like ‘modus-operandi’.
‘FAMILY’
- The collection this theme is a member of, like ‘modus-themes’.
+ The collection this theme is a member of as a symbol, like
+ ‘modus-themes’.
‘DESCRIPTION’
A string describing the theme.
‘BACKGROUND-MODE’
The symbol ‘dark’ or ‘light’, in reference to the theme's
background color.
‘CORE-PALETTE’
- A palette with named colors and semantic mappings, like
- ‘modus-operandi-palette’. A palette that does not have at least
- all the entries of a default Modus palette will eventually not work
- properly because some face definition will expect a given color.
- Though the macro does not impose any check in this regard.
+ The symbol of a variable containing a palette with named colors and
+ semantic mappings, like ‘modus-operandi-palette’. A palette that
+ does not have at least all the entries of a default Modus palette
+ will eventually not work properly because some face definition will
+ expect a given color. Though the macro does not impose any check
+ in this regard.
‘USER-PALETTE’
- A user-defined extension to the ‘CORE-PALETTE’, commensurate with
- it, though with arbitrary entries. This can be nil, a fully
- fledged palette, or a short list of entries.
+ The symbol of a user-defined extension to the ‘CORE-PALETTE’,
+ commensurate with it, though with arbitrary entries. This can be
+ nil, a fully fledged palette, or a short list of entries. Any
+ colors defined therein are treated the same as the ‘CORE-PALETTE’
+ and can, in practice, be used to apply distinct styles to the
+ ‘CUSTOM-FACES’ and ‘CUSTOM-VARIABLES’ (more below).
‘OVERRIDES-PALETTE’
- 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.
+ The symbol of 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.
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.
+ The symbol of a variable with 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
+ The symbol of a variable with a list of custom variables (typically
+ user options) like those defined in
‘modus-themes-custom-variables’. They also override the core Modus
definitions in case of a conflict.
@@ -4324,13 +4331,13 @@ Optional ‘CUSTOM-VARIABLES’
passing all the mandatory arguments, but not the optional ones:
(modus-themes-theme
- ef-summer
- ef-themes
+ 'ef-summer
+ 'ef-themes
"Legible light warm pink theme with magenta, purple, gold, cyan colors."
- light
- modus-operandi-palette
- ef-summer-palette
- ef-summer-palette-overrides)
+ 'light
+ 'modus-operandi-palette
+ 'ef-summer-palette
+ 'ef-summer-palette-overrides)
Here we notice how ‘ef-summer’ has ‘modus-operandi-palette’ as its
‘CORE-PALETTE’. This means that if the ‘ef-summer-palette’ lacks some
@@ -4351,14 +4358,14 @@ This mirrors the style of ‘modus-themes-faces’ and
They are declared in this way:
(modus-themes-theme
- standard-dark
- standard-themes
+ '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
+ '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:
@@ -6712,10 +6719,10 @@ B.2 Variable index
* modus-themes-common-palette-user: Palette extension. (line 16)
* modus-themes-completions: Completion UIs. (line 6)
* modus-themes-custom-variables: Build on top of the Modus themes.
- (line 56)
+ (line 62)
* modus-themes-disable-other-themes: Disable other themes. (line 6)
* modus-themes-faces: Build on top of the Modus themes.
- (line 50)
+ (line 56)
* modus-themes-headings: Heading styles. (line 6)
* modus-themes-italic-constructs: Italic constructs. (line 6)
* modus-themes-items: Option for which themes to rotate.
@@ -6903,51 +6910,51 @@ Node: DIY Add support for combobulate178944
Node: DIY Use a hook at the post-load-theme phase182567
Node: DIY A theme-agnostic hook for theme loading184688
Node: Build on top of the Modus themes187319
-Node: Determine what counts as a Modus theme192402
-Node: Create convenience commands to load a derivative theme195594
-Node: Face coverage197646
-Node: Supported packages198108
-Node: Indirectly covered packages203974
-Node: Notes on individual packages205330
-Node: Note on calendarel weekday and weekend colors206432
-Node: Note on git-gutter in Doom Emacs207582
-Node: Note on php-mode multiline comments210084
-Node: Note on underlines in compilation buffers210846
-Node: Note on inline Latex in Org buffers211720
-Node: Note on dimmerel212332
-Node: Note on display-fill-column-indicator-mode213819
-Node: Note on highlight-parenthesesel215272
-Node: Note on mmm-modeel background colors221351
-Node: Note for prism223705
-Node: Note on company-mode overlay pop-up226919
-Ref: Note on company-mode overlay pop-up-Footnote-1227649
-Ref: Note on company-mode overlay pop-up-Footnote-2227716
-Node: Note on ERC escaped color sequences227771
-Ref: Note on ERC escaped color sequences-Footnote-1229201
-Node: Note on powerline or spaceline229311
-Node: Note on SHR colors229727
-Node: Note on SHR fonts230149
-Node: Note on Ement colors and fonts230838
-Node: Note on pdf-tools link hints232344
-Node: Note on the Notmuch logo234802
-Node: Note on goto-address-mode faces235336
-Node: Frequently Asked Questions236456
-Node: Is the contrast ratio about adjacent colors?237087
-Node: What does it mean to avoid exaggerations?238596
-Node: Why are colors mostly variants of blue magenta cyan?240446
-Node: What is the best setup for legibility?244780
-Node: Are these color schemes?247422
-Node: Port the Modus themes to other platforms?251076
-Node: Contributing253910
-Node: Sources of the themes254309
-Node: Issues you can help with255205
-Node: Patches require copyright assignment to the FSF256597
-Node: Acknowledgements258819
-Node: GNU Free Documentation License263302
-Node: Indices288465
-Node: Function index288644
-Node: Variable index291754
-Node: Concept index295962
+Node: Determine what counts as a Modus theme192823
+Node: Create convenience commands to load a derivative theme196015
+Node: Face coverage198067
+Node: Supported packages198529
+Node: Indirectly covered packages204395
+Node: Notes on individual packages205751
+Node: Note on calendarel weekday and weekend colors206853
+Node: Note on git-gutter in Doom Emacs208003
+Node: Note on php-mode multiline comments210505
+Node: Note on underlines in compilation buffers211267
+Node: Note on inline Latex in Org buffers212141
+Node: Note on dimmerel212753
+Node: Note on display-fill-column-indicator-mode214240
+Node: Note on highlight-parenthesesel215693
+Node: Note on mmm-modeel background colors221772
+Node: Note for prism224126
+Node: Note on company-mode overlay pop-up227340
+Ref: Note on company-mode overlay pop-up-Footnote-1228070
+Ref: Note on company-mode overlay pop-up-Footnote-2228137
+Node: Note on ERC escaped color sequences228192
+Ref: Note on ERC escaped color sequences-Footnote-1229622
+Node: Note on powerline or spaceline229732
+Node: Note on SHR colors230148
+Node: Note on SHR fonts230570
+Node: Note on Ement colors and fonts231259
+Node: Note on pdf-tools link hints232765
+Node: Note on the Notmuch logo235223
+Node: Note on goto-address-mode faces235757
+Node: Frequently Asked Questions236877
+Node: Is the contrast ratio about adjacent colors?237508
+Node: What does it mean to avoid exaggerations?239017
+Node: Why are colors mostly variants of blue magenta cyan?240867
+Node: What is the best setup for legibility?245201
+Node: Are these color schemes?247843
+Node: Port the Modus themes to other platforms?251497
+Node: Contributing254331
+Node: Sources of the themes254730
+Node: Issues you can help with255626
+Node: Patches require copyright assignment to the FSF257018
+Node: Acknowledgements259240
+Node: GNU Free Documentation License263723
+Node: Indices288886
+Node: Function index289065
+Node: Variable index292175
+Node: Concept index296383
End Tag Table
diff --git a/doc/modus-themes.org b/doc/modus-themes.org
index 54334ad667..35403d16ce 100644
--- a/doc/modus-themes.org
+++ b/doc/modus-themes.org
@@ -4128,7 +4128,7 @@ core Emacs.
#+findex: modus-themes-theme
#+vindex: modus-themes-registered-items
-A new theme can be instantiated with the macro ~modus-themes-theme~.
+A new theme can be instantiated with the function ~modus-themes-theme~.
It takes care to (i) declare the theme, (ii) add to it relevant
~theme-properties~, (iii) register it in the ~modus-themes-registered-items~,
(iv) make it work with all the faces and customizations documented
@@ -4136,46 +4136,53 @@ in this manual, and (v) ~provide-theme~ the theme.
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~.
+- =NAME= :: The name of the new theme as a symbol, like ~modus-operandi~.
+- =FAMILY= :: The collection this theme is a member of as a symbol,
+ like ~modus-themes~.
- =DESCRIPTION= :: A string describing the theme.
- =BACKGROUND-MODE= :: The symbol =dark= or =light=, in reference to
the theme's background color.
-- =CORE-PALETTE= :: A palette with named colors and semantic mappings,
- like ~modus-operandi-palette~. A palette that does not have at least
- all the entries of a default Modus palette will eventually not work
- properly because some face definition will expect a given color.
- Though the macro does not impose any check in this regard.
-- =USER-PALETTE= :: A user-defined extension to the =CORE-PALETTE=,
- commensurate with it, though with arbitrary entries. This can be
- nil, a fully fledged palette, or a short list of entries.
-- =OVERRIDES-PALETTE= :: 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.
+- =CORE-PALETTE= :: The symbol of a variable containing a palette with
+ named colors and semantic mappings, like ~modus-operandi-palette~. A
+ palette that does not have at least all the entries of a default
+ Modus palette will eventually not work properly because some face
+ definition will expect a given color. Though the macro does not
+ impose any check in this regard.
+- =USER-PALETTE= :: The symbol of a user-defined extension to the
+ =CORE-PALETTE=, commensurate with it, though with arbitrary entries.
+ This can be nil, a fully fledged palette, or a short list of
+ entries. Any colors defined therein are treated the same as the
+ =CORE-PALETTE= and can, in practice, be used to apply distinct
+ styles to the =CUSTOM-FACES= and =CUSTOM-VARIABLES= (more below).
+- =OVERRIDES-PALETTE= :: The symbol of 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.
#+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.
+- Optional =CUSTOM-FACES= :: The symbol of a variable with 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.
+- Optional =CUSTOM-VARIABLES= :: The symbol of a variable with a list
+ of custom variables (typically user options) 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:
#+begin_src emacs-lisp
(modus-themes-theme
- ef-summer
- ef-themes
+ 'ef-summer
+ 'ef-themes
"Legible light warm pink theme with magenta, purple, gold, cyan colors."
- light
- modus-operandi-palette
- ef-summer-palette
- ef-summer-palette-overrides)
+ 'light
+ 'modus-operandi-palette
+ 'ef-summer-palette
+ 'ef-summer-palette-overrides)
#+end_src
Here we notice how ~ef-summer~ has ~modus-operandi-palette~ as its
@@ -4198,14 +4205,14 @@ They are declared in this way:
#+begin_src emacs-lisp
(modus-themes-theme
- standard-dark
- standard-themes
+ '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
+ '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
