[elpa] externals/standard-themes 7de8b74c4f 04/11: Update the manual about standard-themes-headings

[ELPA Syncer]

branch: externals/standard-themes
commit 7de8b74c4fa40d5415960af3bbcade449cb9b891
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Update the manual about standard-themes-headings
---
 README.org | 97 +++++++++++++++++++++++++++++++++++---------------------------
 1 file changed, 55 insertions(+), 42 deletions(-)

diff --git a/README.org b/README.org
index 2bcfdf733d..7ba91f453c 100644
--- a/README.org
+++ b/README.org
@@ -431,44 +431,56 @@ combinations, followed by a presentation of all available 
properties:
 
 #+begin_src emacs-lisp
 (setq standard-themes-headings
-      '((1 . (light variable-pitch 1.5))
-        (2 . (regular 1.3))
-        (3 . (1.1))
+      '((1 . (variable-pitch 1.5))
+        (2 . (1.3))
         (agenda-date . (1.3))
         (agenda-structure . (variable-pitch light 1.8))
-        (t . (variable-pitch))))
+        (t . (1.1))))
 #+end_src
 
-By default (a ~nil~ value for this variable), all headings have a normal
-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 ~standard-themes-weights~.  The absence of a
-  weight means that no distinct weight will be used.
-
-- 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:
+Properties:
+
++ A font weight, which must be supported by the underlying typeface:
+  - ~thin~
+  - ~ultralight~
+  - ~extralight~
+  - ~light~
+  - ~semilight~
+  - ~regular~
+  - ~medium~
+  - ~semibold~
+  - ~bold~ (default)
+  - ~heavy~
+  - ~extrabold~
+  - ~ultrabold~
++ A floating point as a height multiple of the default or a cons cell in
+  the form of =(height . FLOAT)=.
+
+By default (a ~nil~ value for this variable), all headings have a bold
+typographic weight and use a desaturated text color.
+
+A ~variable-pitch~ property changes the font family of the heading to that
+of the ~variable-pitch~ face (normally a proportionately spaced typeface).
+
+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 ~standard-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
 (variable-pitch semibold (height . 1.3)) ; same as above
 #+end_src
 
@@ -478,26 +490,27 @@ In user configuration files the form may look like this:
 
 #+begin_src emacs-lisp
 (setq standard-themes-headings
-      '((1 . (light variable-pitch 1.5))
-        (2 . (regular 1.3))
-        (3 . (1.1))
-        (t . (variable-pitch))))
+      '((1 . (variable-pitch 1.5))
+        (2 . (1.3))
+        (agenda-date . (1.3))
+        (agenda-structure . (variable-pitch light 1.8))
+        (t . (1.1))))
 #+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:
+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 standard-themes-headings
       '((1 . t)           ; keep the default style
-        (2 . (variable-pitch 1.2))
-        (t . (variable-pitch)))) ; style for all unspecified headings
+        (2 . (semibold 1.2))
+        (t . (rainbow)))) ; style for all other headings
 
 (setq standard-themes-headings
-      '((1 . (variable-pitch 1.6))
-        (2 . (1.3))
-        (t . t))) ; default style for all unspecified levels
+      '((1 . (variable-pitch 1.5))
+        (2 . (semibold))
+        (t . t))) ; default style for all other levels
 #+end_src
 
 ** Style of region highlight