branch: externals/standard-themes
commit 7de8b74c4fa40d5415960af3bbcade449cb9b891
Author: Protesilaos Stavrou <[email protected]>
Commit: Protesilaos Stavrou <[email protected]>
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
