Implement user option ef-themes-headings

I think this is necessary as (i) it is impossible to find a scale that
works for everyone, (ii) this option does not complicate the maintenance
of the project as it does not affect colour combinations.

1 files changed, 112 insertions, 0 deletions

diff --git a/README.org b/README.org
index ca85d16..7378d4f 100644
--- a/README.org
+++ b/README.org
@@ -138,6 +138,17 @@ Everything is in place to set up the package.
 ;; Also those which are optimized for deuteranopia (red-green color
 ;; deficiency): `ef-deuteranopia-dark', `ef-deuteranopia-light'.
 
+(setq ef-themes-headings ; read the manual's entry of the doc string
+      '((0 . (variable-pitch light 1.9))
+        (1 . (variable-pitch light 1.8))
+        (2 . (variable-pitch regular 1.7))
+        (3 . (variable-pitch regular 1.6))
+        (4 . (variable-pitch regular 1.5))
+        (5 . (variable-pitch 1.4)) ; absence of weight means `bold'
+        (6 . (variable-pitch 1.3))
+        (7 . (variable-pitch 1.2))
+        (t . (variable-pitch 1.1))))
+
 ;; We also provide these commands, but do not assign them to any key:
 ;;
 ;; - `ef-themes-select'
@@ -160,6 +171,107 @@ nonetheless, provide a light and a dark theme that are optimized for
 such users.  The named of the themes are: ~ef-deuteranopia-dark~ and
 ~ef-deuteranopia-light~ ([[#h:75d74aea-d17f-497f-a3b8-f0bf4c372de0][Loading a theme]]).
 
+* Customization options
+:PROPERTIES:
+:CUSTOM_ID: h:db8ba158-22f6-49f7-b2f2-1c8162e690dd
+:END:
+
+The =ef-themes= provide a limited set of user options which tweak
+secondary aspects of the theme.  No option affects coloration or the
+overall character of each theme ([[#h:a6dd030c-6b6c-4992-83e8-3438b4607b51][Principles]]).
+
+** Option for headings
+:PROPERTIES:
+:CUSTOM_ID: h:a7a02817-e324-43e9-a7d8-fde024530af6
+:END:
+
+[ Part of {{{development-version}}} ]
+
+#+vindex: ef-themes-headings
+The user option ~ef-themes-headings~ provides support for individual
+heading styles for levels 0 through 8.
+
+This is an alist that accepts a =(key . list-of-values)= combination.
+The key is either a number, representing the heading's level (0
+through 8) or =t=, which pertains to the fallback style.
+
+Level 0 is a special heading: it is used for what counts as a document
+title or equivalent, such as the =#+title= construct we find in Org
+files.  Levels 1-8 are regular headings.
+
+The list of values covers symbols that refer to properties, as described
+below.  Here is a complete sample, followed by a presentation of all
+available properties:
+
+#+begin_src emacs-lisp
+(setq ef-themes-headings
+      '((1 . (light variable-pitch 1.5))
+        (2 . (regular 1.3))
+        (3 . (1.1))
+        (t . (variable-pitch))))
+#+end_src
+
+By default (a =nil= value for this variable), all headings have a bold
+typographic weight, a font family that is the same as the ~default~ face
+(typically monospaced), and a height that is equal to the ~default~
+face's height.
+
+- A ~variable-pitch~ property changes the font family of the heading to
+  that of the ~variable-pitch~ face (normally a proportionately spaced
+  typeface).  Also check the =fontaine= package (by Protesilaos) for
+  tweaking fonts via faces.
+
+- The symbol of a weight attribute adjusts the font of the heading
+  accordingly, such as ~light~, ~semibold~, etc.  Valid symbols are
+  defined in the variable ~ef-themes-weights~.  The absence of a weight
+  means that bold will be used by virtue of inheriting the ~bold~ face.
+
+- A number, expressed as a floating point (e.g. 1.5), adjusts the height
+  of the heading to that many times the base font size.  The default
+  height is the same as 1.0, though it need not be explicitly stated.
+  Instead of a floating point, an acceptable value can be in the form of
+  a cons cell like =(height . FLOAT)= or =(height FLOAT)=, where =FLOAT=
+  is the given number.
+
+Combinations of any of those properties are expressed as a list, like in
+these examples:
+
+#+begin_src emacs-lisp
+(semibold)
+(variable-pitch semibold)
+(variable-pitch semibold 1.3)
+(variable-pitch semibold (height 1.3))   ; same as above
+(variable-pitch semibold (height . 1.3)) ; same as above
+#+end_src
+
+The order in which the properties are set is not significant.
+
+In user configuration files the form may look like this:
+
+#+begin_src emacs-lisp
+(setq ef-themes-headings
+      '((1 . (light variable-pitch 1.5))
+        (2 . (regular 1.3))
+        (3 . (1.1))
+        (t . (variable-pitch))))
+#+end_src
+
+When defining the styles per heading level, it is possible to
+pass a non-nil value (t) instead of a list of properties.  This
+will retain the original aesthetic for that level.  For example:
+
+#+begin_src emacs-lisp
+(setq ef-themes-headings
+      '((1 . t)           ; keep the default style
+              (2 . (variable-pitch 1.2))
+              (t . (variable-pitch)))) ; style for all other headings
+
+(setq ef-themes-headings
+      '((1 . (variable-pitch 1.6))
+              (2 . (1.3))
+              (t . t))) ; default style for all other levels
+#+end_src
+
 * Principles
 :PROPERTIES:
 :CUSTOM_ID: h:a6dd030c-6b6c-4992-83e8-3438b4607b51