[elpa] externals/modus-operandi-theme a3d064d 26/54: Several refinements to the README

[Stefan Monnier]

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

    Several refinements to the README
---
 README.org | 136 +++++++++++++++++++++++++++++++++++++++----------------------
 1 file changed, 88 insertions(+), 48 deletions(-)

diff --git a/README.org b/README.org
index 55bdfe1..394705f 100644
--- a/README.org
+++ b/README.org
@@ -109,8 +109,31 @@ snippet:
 (load-theme 'modus-vivendi t)           ; Dark theme
 #+END_SRC
 
-Make sure to /remove any other theme/ that is being loaded, otherwise
-you might run into unexpected issues.
+Make sure to /remove any other theme/ that is being loaded, otherwise you
+might run into unexpected issues (you can also =M-x disable-theme=).
+
+*** Load depending on the time of the day
+    :PROPERTIES:
+    :CUSTOM_ID: h:4e936e31-e9eb-4b50-8fdd-45d827a03cca
+    :END:
+
+This is a neat trick contributed by 
[[https://www.reddit.com/r/emacs/comments/gdtqov/weekly_tipstricketc_thread/fq9186h/][b3n
 on r/emacs]].  It will select the
+appropriate theme based on the time of the day and it will also switch
+themes when the time comes.
+
+#+begin_src emacs-lisp
+;; Light for the day
+(load-theme 'modus-operandi t t)
+(run-at-time "05:00" (* 60 60 24) (lambda () (enable-theme 'modus-operandi)))
+
+;; Dark for the night
+(load-theme 'modus-vivendi t t)
+(run-at-time "21:00" (* 60 60 24) (lambda () (enable-theme 'modus-vivendi)))
+#+end_src
+
+Note that the =load-theme= here is slightly different than the one in the
+section right above, because it does not enable the theme directly (the
+subsequent =enable-theme= does that when needed).
 
 * Customisation options
   :PROPERTIES:
@@ -155,12 +178,15 @@ fully fledged =use-package= declaration.
 + =modus-operandi-theme-distinct-org-blocks=
 + =modus-vivendi-theme-distinct-org-blocks=
 
-Use a distinct background for Org's source blocks and extend their
-headings until the edge of the window (the "extend" part is for Emacs
-versions >= 27, whereas before they would extend regardless).  The
-default is to use the same background as the rest of the buffer for the
-contents of the block, while beginning and end lines do not extend to
-the end of the window (again, the "extend" is for Emacs 27 or higher).
+Use a distinct background for Org's source blocks and extend the
+background of their beginning and end lines to the edge of the window
+(the "extend" part is for Emacs versions >= 27, whereas before they
+would extend regardless).
+
+The default is to use the same background as the rest of the buffer for
+the contents of the block, while beginning and end lines do not extend
+to the end of the window (again, the "extend" is for Emacs 27 or
+higher).
 
 ** Option for colourful "rainbow" headings
    :PROPERTIES:
@@ -175,9 +201,11 @@ while retaining all other heading properties (such as a 
bold weight and
 the optional scaled height ---see relevant customisation toggle).  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.  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.
+presentation.
+
+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.
 
 ** Option for sectioned headings
    :PROPERTIES:
@@ -187,9 +215,6 @@ heading levels provide the elements of differentiation.
 + =modus-operandi-theme-section-headings=
 + =modus-vivendi-theme-section-headings=
 
-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.
-
 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,
@@ -197,6 +222,9 @@ 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.
 
+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.
+
 ** Option for scaled headings
    :PROPERTIES:
    :CUSTOM_ID: h:db0275ea-11c2-47c9-82a9-10b65d8df0f8
@@ -212,9 +240,10 @@ headers and body copy.
 In addition to toggles for enabling scaled headings, users can also
 specify a number of their own.
 
-+ If it is a *floating point*, say, =1.5= then it is interpreted as a
-  multiple of the base font size (there are many ways to set the main
-  font on Emacs, such as those 
[[https://gitlab.com/protesilaos/modus-themes/-/issues/43#note_337308289][I 
documented in issue 43]]).
++ If it is a *floating point*, say, =1.5=, it is interpreted as a multiple
+  of the base font size (there are many ways to set the main font in
+  Emacs, such as those 
[[https://gitlab.com/protesilaos/modus-themes/-/issues/43#note_337308289][I 
documented in issue 43]], though the most robust
+  method is covered below in [[#h:ea30ff0e-3bb6-4801-baf1-d49169d94cd5][Font 
configurations for Org (and others)]]).
 + If it is an *integer*, it is read as an absolute font height.  The
   number is basically the point size multiplied by a hundred.  So if you
   want it to be =18pt= you must pass =180=.
@@ -241,7 +270,7 @@ resource for finding a consistent scale, like 
[[https://www.modularscale.com][mo
 Note that in Org, scaling only increases the size of the heading, but
 not of keywords that are added to it, like "TODO".  This is outside the
 control of the themes and I am not aware of any way to make such
-keywords scale accordingly.
+keywords scale accordingly (see [[*Font configurations for Org (and 
others)][issue 37]]).
 
 Also note that in the latest tagged release (=0.8.1=) an Org file's
 =#+TITLE= will not scale at all.  This has been fixed in =master= and will
@@ -257,9 +286,11 @@ be available in version =0.9.0=, which is expected in 
early June 2020
 + =modus-vivendi-theme-visible-fringe=
 
 When enabled, this will render the fringes in a subtle background
-colour.  The default is to use the same colour as that of the main
-background, meaning that the fringes are not obvious though they still
-occupy the space given to them by =fringe-mode=.
+colour.
+
+The default is to use the same colour as that of the main background,
+meaning that the fringes are not obvious though they still occupy the
+space given to them by =fringe-mode= (8px on either side by default).
 
 ** Option for more slanted constructs
    :PROPERTIES:
@@ -270,8 +301,9 @@ occupy the space given to them by =fringe-mode=.
 + =modus-vivendi-theme-slanted-constructs=
 
 Choose to render more faces in slanted text (italics).  This typically
-affects documentation strings and code comments.  The default is to not
-use italics unless it is absolutely necessary.
+affects documentation strings and code comments.
+
+The default is to not use italics unless it is absolutely necessary.
 
 ** Option for more bold constructs
    :PROPERTIES:
@@ -283,8 +315,9 @@ use italics unless it is absolutely necessary.
 
 Display several constructs in bold weight.  This concerns keywords and
 other important aspects of code syntax.  It also affects certain mode
-line indicators.  The default is to only use a bold weight when it is
-necessary.
+line indicators.
+
+The default is to only use a bold weight when it is necessary.
 
 ** Option for three-dimensional focused mode line
    :PROPERTIES:
@@ -296,10 +329,12 @@ necessary.
 
 Use a three-dimensional, "released button" effect for the focused
 window's mode line.  When enabled, this option will also affect the
-styles of any inactive mode lines, making them less intense overall in
-order to accommodate the added element of depth.  The default is to
-present the mode lines as rectangles with a border around them and with
-the active one having more intense colours than any inactive ones.
+styles of any inactive mode lines, making them slightly less intense in
+order to accommodate the added element of depth.
+
+The default is to present the mode lines as rectangles with a border
+around them and with the active one having more intense colours than any
+inactive ones.
 
 ** Option for subtle diffs
    :PROPERTIES:
@@ -314,13 +349,14 @@ and/or less intense background colours or, where 
possible, with no
 background colours applied to the presentation of the added and removed
 lines.  Concerning =magit=, an extra set of tweaks are introduced for the
 effect of highlighting the current diff hunk, so as to remain consistent
-with the overall experience of that mode.  The default is to use
-colour-coded backgrounds for line-wise highlights.  "Refined" changes
-(word-wise highlights) always use a background value which is,
-nonetheless, more subtle with this option than with its default
-equivalent.
+with the overall experience of that mode.
+
+The default is to use colour-coded backgrounds for line-wise highlights.
+"Refined" changes (word-wise highlights) always use a background value
+which is, nonetheless, more subtle with this option than with its
+default equivalent.
 
-** Option for proportional fonts
+** Option for proportional fonts in headings
    :PROPERTIES:
    :CUSTOM_ID: h:33023fa6-6482-45d4-9b5e-3c73c945718f
    :END:
@@ -328,11 +364,15 @@ equivalent.
 + =modus-operandi-theme-proportional-fonts=
 + =modus-vivendi-theme-proportional-fonts=
 
-Choose to apply a proportionately-spaced font to some faces.  Currently
-this only affects headings (e.g. in Org).  Contributions on how to make
-the use of proportional fonts more useful are highly appreciated (see
-[[#h:25ba8d6f-6604-4338-b774-bbe531d467f6][section on contributing]]).  The 
default is to use whatever the default
-typeface is, typically a monospaced family.
+Choose to apply a proportionately-spaced typeface to headings (such as
+in Org mode).  The default is to use whatever the main typeface is,
+typically a monospaced family.
+
+Though also read [[#h:ea30ff0e-3bb6-4801-baf1-d49169d94cd5][Font 
configurations for Org (and others)]] as the themes
+are designed to cope well with more prose-friendly typeface
+configurations (e.g. using a proportionately-spaced sans-serif font for
+the main text, while letting inline code and some other space-sensitive
+constructs use a monospaced font).
 
 ** Complete example configuration for the above
    :PROPERTIES:
@@ -345,7 +385,7 @@ variables /before/ loading the theme.  You can also see a 
different form
 of =setq= that sets the value of multiple variables at once: use one =setq=
 expression for each variable, if in doubt.
 
-Do not forget to =M-x package-refresh-contents= to get your package list
+*Do not forget* to =M-x package-refresh-contents= to get your package list
 up-to-date, else the initial download may fail due to a newer version
 being available.
 
@@ -376,7 +416,7 @@ Need more ideas?  Check the 
[[https://protesilaos.com/dotemacs/#h:b7444e76-75d4-
 do not try to interpret the values of the variables, as I always test
 different combinations and scenaria).
 
-** Full access to the palette for further tweaks
+** Full access to the palette for further tweaks (advanced)
    :PROPERTIES:
    :CUSTOM_ID: h:b7282635-4fe9-415a-abdf-962b736ff5b6
    :END:
@@ -511,6 +551,11 @@ package which offers live colour previews.  This is how I 
configure it:
   (setq rainbow-x-colors nil))
 #+end_src
 
+As for the means to check the contrast in perceived luminance between a
+foreground colour and its expected background combination, refer to the
+methods documented in my 
[[https://protesilaos.com/codelog/2020-05-10-modus-operandi-palette-review/][Modus
 Operandi theme subtle palette review]]
+(2020-05-10).
+
 ** Font configurations for Org (and others)
    :PROPERTIES:
    :CUSTOM_ID: h:ea30ff0e-3bb6-4801-baf1-d49169d94cd5
@@ -836,10 +881,6 @@ Use =M-x list-faces-display= to get these.
 
 + tty-menu
 
-Note that the themes do provide support for =org-mode=, but some of
-these interfaces have been decided based on indirect experience.  If you
-encounter anything that does not "feel right", please let me know.
-
 ** Will NOT be supported
    :PROPERTIES:
    :CUSTOM_ID: h:46756fcc-0d85-4f77-b0e3-64f890e1c2ea
@@ -974,8 +1015,7 @@ section).
   :CUSTOM_ID: h:25ba8d6f-6604-4338-b774-bbe531d467f6
   :END:
 
-A few tasks you can help me with, sorted from the most probable to the
-least likely:
+A few tasks you can help me with:
 
 + Suggest refinements to packages that are covered.
 + Report packages not covered thus far.