[elpa] externals/fontaine 2ad09e2a1c 1/2: Declare and document fontaine-apply-current-preset

[ELPA Syncer]

branch: externals/fontaine
commit 2ad09e2a1ced750080118742c2c85735f6450796
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Declare and document fontaine-apply-current-preset
---
 README.org  | 28 +++++++++++++++++++++-------
 fontaine.el | 30 ++++++++++++++++++++++++++++--
 2 files changed, 49 insertions(+), 9 deletions(-)

diff --git a/README.org b/README.org
index 7f18ec9f5f..8921e956e8 100644
--- a/README.org
+++ b/README.org
@@ -551,21 +551,35 @@ Remember to read the relevant doc strings.
 :CUSTOM_ID: h:f1b48050-e8e1-4689-b92f-7776bbaa55a4
 :END:
 
+[ The command ~fontaine-apply-current-preset~ is part of 
{{{development-version}}} ]
+
+#+findex: fontaine-apply-current-preset
+#+vindex: fontaine-current-preset
 Themes re-apply face definitions when they are loaded.  This is
 necessary to render the theme.  For certain faces, such as ~bold~ and
-~italic~, this means that their font family is reset.  To avoid this
-problem, we can instruct them to restore the current font configuration
-with something like this:
+~italic~, this means that their font family may be reset.  To avoid such
+a problem, we can instruct them to restore the current font preset.
+Fontaine provides the command ~fontaine-apply-current-preset~.  It can
+either be called interactively after loading a theme or be assigned to a
+hook that is ran at the post ~load-theme~ phase.
+
+Some themes that provide a hook are the =modus-themes= and =ef-themes=
+(both by Protesilaos), so we can use something like:
+
+#+begin_src emacs-lisp
+(add-hook 'modus-themes-after-load-theme-hook #'fontaine-apply-current-preset))
+#+end_src
+
+If both packages are used, we can either write two lines of ~add-hook~
+or do this:
 
 #+begin_src emacs-lisp
 ;; Persist font configurations while switching themes (doing it with
 ;; my `modus-themes' and `ef-themes' via the hooks they provide).
 (dolist (hook '(modus-themes-after-load-theme-hook ef-themes-post-load-hook))
-  (add-hook hook (lambda () (fontaine-set-preset fontaine-current-preset))))
+  (add-hook hook #'fontaine-apply-current-preset))
 #+end_src
 
-[ The variable ~fontaine-current-preset~ is part of {{{development-version}}} ]
-
 Themes must specify a hook that is called by their relevant commands at
 the post-theme-load phase.  This can also be done in a theme-agnostic
 way:
@@ -585,7 +599,7 @@ way:
 And then simply use that hook:
 
 #+begin_src emacs-lisp
-(add-hook 'after-enable-theme-hook (lambda () (fontaine-set-preset 
fontaine-current-preset)))
+(add-hook 'after-enable-theme-hook #'fontaine-apply-current-preset)
 #+end_src
 
 * Acknowledgements
diff --git a/fontaine.el b/fontaine.el
index f4ab29dc9c..4e7c14a37f 100644
--- a/fontaine.el
+++ b/fontaine.el
@@ -471,7 +471,8 @@ ARGS are its routines."
 
 (defvar fontaine-current-preset nil
   "Current font set in `fontaine-presets'.
-This is the preset last used by `fontaine-set-preset'.")
+This is the preset last used by `fontaine-set-preset'.  Also see
+the command `fontaine-apply-current-preset'.")
 
 ;;;###autoload
 (defun fontaine-set-preset (preset &optional frame)
@@ -487,7 +488,10 @@ frame and apply the effects to it.
 
 When called interactively with a universal prefix
 argument (\\[universal-argument]), FRAME is interpreted as
-non-nil."
+non-nil.
+
+Set `fontaine-current-preset' to PRESET.  Also see the command
+`fontaine-apply-current-preset'."
   (interactive
    (list
     (if (= (length fontaine-presets) 1)
@@ -506,6 +510,28 @@ non-nil."
     (add-to-history 'fontaine--preset-history (format "%s" preset))
     (run-hooks 'fontaine-set-preset-hook)))
 
+;;;###autoload
+(defun fontaine-apply-current-preset ()
+  "Use `fontaine-set-preset' on `fontaine-current-preset'.
+The value of `fontaine-current-preset' must be one of the keys in
+`fontaine-presets'.
+
+Re-applying the current preset is useful when a new theme is
+loaded which overrides certain font families.  For example, if
+the theme defines the `bold' face without a `:family', loading
+that theme will make `bold' use the `default' family, even if the
+`fontaine-presets' are configured to have different families
+between the two.  In such a case, applying the current preset at
+the post `load-theme' phase (e.g. via a hook) ensures that font
+configurations remain consistent.
+
+Some themes that provide hooks of this sort are the
+`modus-themes' and `ef-themes' (both by Protesilaos)."
+  (interactive)
+  (when-let* ((current fontaine-current-preset)
+              ((alist-get current fontaine-presets)))
+    (fontaine-set-preset current)))
+
 ;;;; Modify individual faces
 
 (defconst fontaine--font-faces