[elpa] externals/fontaine 4b6b631337 3/5: Simplify the documentation of 'fontaine-presets'

[ELPA Syncer]

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

    Simplify the documentation of 'fontaine-presets'
---
 README.org  |  81 ++++++++++++++++++++++++++++++--------------
 fontaine.el | 110 ++++++++++++++----------------------------------------------
 2 files changed, 82 insertions(+), 109 deletions(-)

diff --git a/README.org b/README.org
index 83a8c7b6d7..aa3b3a7920 100644
--- a/README.org
+++ b/README.org
@@ -76,68 +76,99 @@ them on demand on graphical Emacs frames.  The user option
 ~fontaine-presets~ holds all such presets.
 
 [ The support for the mode line, header line, line number, tab bar,
-  and tab line faces is part of {{{development-version}}}. ]
+  and tab line faces is part of {{{development-version}}}.  Same for
+  the introduction of the variables ~fontaine-weights~,
+  ~fontaine-slants~, ~fontaine-faces~. ]
 
 Presets consist of a list of properties that govern the family,
-weight, and height of the faces ~default~, ~fixed-pitch~,
-~fixed-pitch-serif~, ~variable-pitch~, ~mode-line-active~ (and
-~mode-line~ for older Emacs version), ~mode-line-inactive~,
-~header-line~, ~line-number~, ~tab-bar~, ~tab-line~, ~bold~, and
-~italic~. Each preset is identified by a user-defined symbol as the
-car of a property list. It looks like this (check the default value of
+weight, height, and slant of the faces listed in the value of the
+variable ~fontaine-faces~.
+
+Each preset is identified by a user-defined symbol as the ~car~ of a
+property list. It looks like this (check the default value of
 ~fontaine-presets~ for how everything is pieced together):
 
 #+begin_src emacs-lisp
 (regular
  ;; I keep all properties for didactic purposes, but most can be
- ;; omitted.
+ ;; omitted.  See the fontaine manual for the technicalities:
+ ;; <https://protesilaos.com/emacs/fontaine>.
  :default-family "Monospace"
  :default-weight regular
+ :default-slant normal
  :default-height 100
 
- :fixed-pitch-family nil ; falls back to :default-family
- :fixed-pitch-weight nil ; falls back to :default-weight
+ :fixed-pitch-family nil
+ :fixed-pitch-weight nil
+ :fixed-pitch-slant nil
  :fixed-pitch-height 1.0
 
- :fixed-pitch-serif-family nil ; falls back to :default-family
- :fixed-pitch-serif-weight nil ; falls back to :default-weight
+ :fixed-pitch-serif-family nil
+ :fixed-pitch-serif-weight nil
+ :fixed-pitch-serif-slant nil
  :fixed-pitch-serif-height 1.0
 
  :variable-pitch-family "Sans"
  :variable-pitch-weight nil
+ :variable-pitch-slant nil
  :variable-pitch-height 1.0
 
- :mode-line-active-family nil ; falls back to :default-family
- :mode-line-active-weight nil ; falls back to :default-weight
+ :mode-line-active-family nil
+ :mode-line-active-weight nil
+ :mode-line-active-slant nil
  :mode-line-active-height 1.0
 
- :mode-line-inactive-family nil ; falls back to :default-family
- :mode-line-inactive-weight nil ; falls back to :default-weight
+ :mode-line-inactive-family nil
+ :mode-line-inactive-weight nil
+ :mode-line-inactive-slant nil
  :mode-line-inactive-height 1.0
 
- :header-line-family nil ; falls back to :default-family
- :header-line-weight nil ; falls back to :default-weight
+ :header-line-family nil
+ :header-line-weight nil
+ :header-line-slant nil
  :header-line-height 1.0
 
- :line-number-family nil ; falls back to :default-family
- :line-number-weight nil ; falls back to :default-weight
+ :line-number-family nil
+ :line-number-weight nil
+ :line-number-slant nil
  :line-number-height 1.0
 
- :tab-bar-family nil ; falls back to :default-family
- :tab-bar-weight nil ; falls back to :default-weight
+ :tab-bar-family nil
+ :tab-bar-weight nil
+ :tab-bar-slant nil
  :tab-bar-height 1.0
 
- :tab-line-family nil ; falls back to :default-family
- :tab-line-weight nil ; falls back to :default-weight
+ :tab-line-family nil
+ :tab-line-weight nil
+ :tab-line-slant nil
  :tab-line-height 1.0
 
- :bold-family nil ; use whatever the underlying face has
+ :bold-family nil
+ :bold-slant nil
  :bold-weight bold
+ :bold-height 1.0
+
  :italic-family nil
+ :italic-weight nil
  :italic-slant italic
+ :italic-height 1.0
+
  :line-spacing nil)
 #+end_src
 
+Multiple presets form an alist (a list of lists), like this:
+
+#+begin_src emacs-lisp
+'((regular
+   :default-family "Monospace"
+   ;; More properties here
+   )
+  (medium
+   :default-family "Iosevka Comfy Wide")
+  ;; More presets here
+  )
+#+end_src
+
 The doc string of ~fontaine-presets~ explains all properties in detail
 and documents some important caveats or information about font settings
 in Emacs.
diff --git a/fontaine.el b/fontaine.el
index 87bb219d48..3d479cd8fa 100644
--- a/fontaine.el
+++ b/fontaine.el
@@ -164,9 +164,7 @@
      :italic-height 1.0
 
      :line-spacing nil))
-  "DEV NOTE 2024-02-21 13:00 +0200: Must be updated to describe new options.
-
-Alist of desired typographic properties.
+  "Alist of desired typographic properties.
 
 The car of each cell is an arbitrary symbol that identifies
 and/or describes the set of properties (e.g. small, reading).
@@ -179,80 +177,29 @@ that change from the default.  See the default value of 
this
 variable for how that is done.
 
 The cdr is a plist that specifies the typographic properties of
-the faces `default', `fixed-pitch', `variable-pitch', `bold', and
-`italic'.  It also covers the `line-spacing' variable.
-
-The properties in detail:
-
-- `:default-family' is the family of the `default' face.  If not
-  specified, it falls back to Monospace.
-
-- `:default-weight' is the weight of the `default' face.  The
-  fallback value is `normal'.  Available weights are `normal' or
-  `regular', `thin', `ultralight', `extralight', `light',
-  `semilight', `medium', `semibold', `extrabold', `ultrabold' and
-  must be supported by the underlying typeface.
-
-- `:default-height' is the height of the `default' face.  The
-  fallback value is 100 (the height is 10x the point size).
-
-- `:fixed-pitch-family', `:fixed-pitch-weight',
-  `:fixed-pitch-height' apply to the `fixed-pitch' face.  Their
-  fallback values are `:default-family', `:default-weight', and
-  1.0, respectively.
-
-- `:fixed-pitch-serif-family', `:fixed-pitch-serif-weight',
-  `:fixed-pitch-serif-height' apply to the `fixed-pitch-serif'
-  face.  Their fallback values are `:default-family',
-  `:default-weight', and 1.0, respectively.
-
-- The `:variable-pitch-family', `:variable-pitch-weight', and
-  `:variable-pitch-height' apply to the `variable-pitch' face.
-  They all fall back to the respective default values, as
-  described above.
-
-- The `:mode-line-active-family', `:mode-line-active-weight', and
-  `:mode-line-active-height' apply to the `mode-line' and
-  `mode-line-active' faces.  They all fall back to the respective
-  default values, as described above.
-
-- The `:mode-line-inactive-family', `:mode-line-inactive-weight',
-  and `:mode-line-inactive-height' apply to the
-  `mode-line-inactive' face.  They all fall back to the
-  respective default values, as described above.
-
-- The `:header-line-family', `:header-line-weight', and
-  `:header-line-height' apply to the `header-line' face.  They
-  all fall back to the respective default values, as described
-  above.
-
-- The `:line-number-family', `:line-number-weight', and
-  `:line-number-height' apply to the `line-number' face.  They
-  all fall back to the respective default values, as described
-  above.
-
-- The `:tab-bar-family', `:tab-bar-weight', and `:tab-bar-height'
-  apply to the `tab-bar' face.  They all fall back to the
-  respective default values, as described above.
-
-- The `:tab-line-family', `:tab-line-weight', and
-  `:tab-line-height' apply to the `tab-line' face.  They all fall
-  back to the respective default values, as described above.
-
-- The `:bold-family' and `:italic-family' are the font families
-  of the `bold' and `italic' faces, respectively.  Only set them
-  if you want to override that of the underlying face.
-
-- The `:bold-weight' specifies the weight of the `bold' face.
-  Its fallback value is bold, meaning the weight, not the face.
-  For more, refer to the value of `fontaine-font-weights'.  The
-  font family must support the given weight.
-
-- The `:italic-slant' specifies the slant of the `italic' face.
-  Its fallback value is italic, in reference to the slant, not
-  the face.  Acceptable values are those included in the value of
-  `fontaine-font-slants' and must be supported by the underlying
-  typeface
+the faces listed in `fontaine-faces'.  It also covers the
+`line-spacing' variable.
+
+For each face, Fontaine reads keywords that describe its font
+family, font weight, font slant, and font height.  The name of
+those keywords is composed from the name of the face plus th
+specifier.  For example, with the `default' face, we have
+`:default-family', `:default-height', `:default-weight', and
+`:default-slant'.
+
+The properties in mode detail:
+
+- The font family is a string that refers to the name of the
+  font.
+
+- The font weight is an unquoted symbol among `fontaine-weights'.
+
+- The font slant is an unquoted symbol among `fontaine-slants'.
+
+- The font height is a floating point (like 1.0) which is
+  interpreted as a multiple of the default font height.  An
+  exception to this is for the `default' face (i.e. the
+  `:default-height'), which needs to be a natural number.
 
 - The `:line-spacing' specifies the value of the `line-spacing'
   variable.
@@ -283,13 +230,8 @@ Caveats or further notes:
 - All the properties for `bold' and `italic' will only have a
   noticeable effect if the active theme does not hardcode a
   weight and a slant, but instead inherits the relevant
-  face (such as the `modus-themes').
-
-- A height attribute for anything other than the `default' face
-  must be set to a floating point, which is understood as a
-  multiple of the default height (this allows all faces to scale
-  harmoniously).  The `:default-height' always is a natural
-  number.
+  face (such as the `modus-themes', `ef-themes',
+  `standard-themes').
 
 - Fontaine does not [yet] support Emacs' fontsets for other
   scripts or character sets (e.g. Emoji).  Read the documentation