[elpa] externals/modus-operandi-theme 49872b0 031/153: Expand manual with new heading styles alist option

[Stefan Monnier]

branch: externals/modus-operandi-theme
commit 49872b061a2d3aafe4aea84b5559e53928bb63a5
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Expand manual with new heading styles alist option
    
    For an ongoing discussion, refer to issue 81:
    https://gitlab.com/protesilaos/modus-themes/-/issues/81
---
 doc/modus-themes.org | 128 ++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 86 insertions(+), 42 deletions(-)

diff --git a/doc/modus-themes.org b/doc/modus-themes.org
index b5f3804..e7c9e60 100644
--- a/doc/modus-themes.org
+++ b/doc/modus-themes.org
@@ -660,66 +660,110 @@ major-mode so that the colours are applied properly: use 
=M-x org-mode= or
 =M-x org-mode-restart= to refresh the buffer.  Or start typing in each
 code block (inefficient at scale, but it still works).
 
-** Option for colourful headings
+** Option for headings' overall style
 :PROPERTIES:
-:ALT_TITLE: Accented headings
-:DESCRIPTION: Toggle saturated outline headings
-:CUSTOM_ID: h:61b65cff-cc37-4c69-91d7-f818293139a0
+:ALT_TITLE: Heading styles
+:DESCRIPTION: Choose among several styles, also per heading level
+:CUSTOM_ID: h:271eff19-97aa-4090-9415-a6463c2f9ae1
 :END:
 
+This is defined as an alist and, therefore, uses a different approach
+than other customisation options documented in this manual.
+
 Symbol names:
 
-+ =modus-operandi-theme-rainbow-headings=
-+ =modus-vivendi-theme-rainbow-headings=
++ =modus-operandi-theme-headings=
++ =modus-vivendi-theme-headings=
+
+Possible values, which can be specified for each heading level (examples
+further below):
+
++ =t= (default style)
++ =no-bold=
++ =line=
++ =line-no-bold=
++ =rainbow=
++ =rainbow-line=
++ =rainbow-line-no-bold=
++ =rainbow-highlight=
++ =rainbow-highlight-no-bold=
++ =section=
++ =section-no-bold=
++ =rainbow-section=
++ =rainbow-section-no-bold=
+
+To control faces per level from 1-8, use something like this (same for
+=modus-vivendi-theme-headings=):
 
-Possible values:
+#+begin_src emacs-lisp
+(setq modus-operandi-theme-headings
+      '((1 . highlight)
+        (2 . line)
+        (t . rainbow-line-no-bold)))
+#+end_src
 
-1. =nil= (default)
-2. =t=
+The above uses the =highlight= value for heading levels 1 and the =line= for
+headings 2.  All other levels fall back to =rainbow-line-no-bold=.
 
-Apply more saturated colours to headings in =org-mode= and =outline-mode=
-while retaining all other heading properties.  The colours follow the
-rainbow's spectrum.  In Org headings, some additional tweaks are made to
-adapt keywords (like "TODO") to the more vivid presentation.
+To set a uniform value for all heading levels, use this pattern:
 
-The default uses a more frugal aesthetic for headings, letting their
-bold typography and the nuances between the various heading levels
-provide the elements of differentiation.
+#+begin_src emacs-lisp
+(setq modus-operandi-theme-headings
+      '((t . rainbow-line-no-bold)))
+#+end_src
 
-** Option for sectioned headings
-:PROPERTIES:
-:ALT_TITLE: Section headings
-:DESCRIPTION: Toggle sectioned outline headings
-:CUSTOM_ID: h:7649e1b4-7b1d-41bc-aebd-fdae585212d9
-:END:
+The default style for headings uses a fairly desaturated foreground
+value in combination with a bold typographic weight.  To specify this
+style for a given level N (assuming you wish to have another fallback
+option), just specify the value t like this:
 
-Symbol names:
+#+begin_src emacs-lisp
+(setq modus-operandi-theme-headings
+      '((1 . t)
+        (2 . line)
+        (t . rainbow-line-no-bold)))
+#+end_src
 
-+ =modus-operandi-theme-section-headings=
-+ =modus-vivendi-theme-section-headings=
+A description of all other possible values:
 
-Possible values:
++ =no-bold= retains the default text colour while removing the typographic
+  weight.
 
-1. =nil= (default)
-2. =t=
++ =line= is the same as the default plus an overline over the heading.
 
-Uses a background colour and an overline to mark section headings in
-=org-mode= and =outline-mode=.  These attributes are applied in addition to
-the existing foreground colour and the bold weight and can, therefore,
-be combined with the "rainbow" headings option (as well as all the other
-options pertaining to headings).  For Org several additional faces are
-configured accordingly, such as =TODO= keywords which gain a box style.
++ =line-no-bold= is the same as =line= without bold weight.
 
-The default is to use only a subtle foreground and a bold weight for
-headings, while no boxes or {under,over}-line effects are present.
++ =rainbow= uses a more colourful foreground in combination with bold
+  weight.
 
-Note that the background for sectioned headings will extend to the edge
-of the window.  To make it cover just the area occupied by the heading's
-text, use this:
++ =rainbow-line= is the same as =rainbow= plus an overline.
 
-#+begin_src emacs-lisp
-(setq org-fontify-whole-heading-line nil)
-#+end_src
++ =rainbow-line-no-bold= is the same as =rainbow-line= without the bold
+  weight.
+
++ =highlight= retains the default style of a fairly desaturated foreground
+  combined with a bold weight and add to it a subtle accented
+  background.
+
++ =highlight-no-bold= is the same as =highlight= without a bold weight.
+
++ =rainbow-highlight= is the same as =highlight= but with a more colourful
+  foreground.
+
++ =rainbow-highlight-no-bold= is the same as =rainbow-highlight= without a
+  bold weight.
+
++ =section= retains the default looks and adds to them both an overline
+  and a slightly accented background.  It is, in effect, a combination
+  of the =line= and =highlight= values.
+
++ =section-no-bold= is the same as =section= without a bold weight.
+
++ =rainbow-section= is the same as =section= but with a more colourful
+  foreground.
+
++ =rainbow-section-no-bold= is the same as =rainbow-section= without a bold
+  weight."
 
 ** Option for scaled headings
 :PROPERTIES: