mirror of
git://git.sv.gnu.org/emacs.git
synced 2025-12-26 23:31:55 -08:00
8fb33bae32
This syncs with the following upstream revision:
Update to version 1.2.3
0a36239 2021-03-05 19:43:30 +0200
0a36239baf
For discussion, see bug#45068 and the following upstream issue:
https://gitlab.com/protesilaos/modus-themes/-/issues/162
* doc/misc/modus-themes.org:
* etc/themes/modus-operandi-theme.el:
* etc/themes/modus-themes.el:
* etc/themes/modus-vivendi-theme.el: Update to version 1.2.3.
3303 lines
120 KiB
Org Mode
3303 lines
120 KiB
Org Mode
#+title: Modus themes for GNU Emacs
|
||
#+author: Protesilaos Stavrou
|
||
#+email: info@protesilaos.com
|
||
#+language: en
|
||
#+options: ':t toc:nil author:t email:t
|
||
|
||
#+macro: stable-version 1.2.3
|
||
#+macro: release-date 2021-03-05
|
||
#+macro: development-version 1.3.0-dev
|
||
#+macro: export-date (eval (format-time-string "%F %R %z" (current-time)))
|
||
#+macro: file @@texinfo:@file{@@$1@@texinfo:}@@
|
||
#+macro: space @@texinfo:@: @@
|
||
# The "kbd" macro turns KBD into @kbd{KBD}. Additionally, it
|
||
# encloses case-sensitive special keys (SPC, RET...) within @key{...}.
|
||
# I got this from the Org source code.
|
||
#+macro: kbd (eval (let ((case-fold-search nil) (regexp (regexp-opt '("SPC" "RET" "LFD" "TAB" "BS" "ESC" "DELETE" "SHIFT" "Ctrl" "Meta" "Alt" "Cmd" "Super" "UP" "LEFT" "RIGHT" "DOWN") 'words))) (format "@@texinfo:@kbd{@@%s@@texinfo:}@@" (replace-regexp-in-string regexp "@@texinfo:@key{@@\\&@@texinfo:}@@" $1 t))))
|
||
|
||
#+texinfo_filename: modus-themes.info
|
||
#+texinfo_dir_category: Emacs misc features
|
||
#+texinfo_dir_title: Modus Themes: (modus-themes)
|
||
#+texinfo_dir_desc: Highly accessible themes (WCAG AAA)
|
||
#+texinfo_header: @set MAINTAINERSITE @uref{https://protesilaos.com,maintainer webpage}
|
||
#+texinfo_header: @set MAINTAINER Protesilaos Stavrou
|
||
#+texinfo_header: @set MAINTAINEREMAIL @email{info@protesilaos.com}
|
||
#+texinfo_header: @set MAINTAINERCONTACT @uref{mailto:info@protesilaos.com,contact the maintainer}
|
||
|
||
#+texinfo: @insertcopying
|
||
|
||
This manual, written by Protesilaos Stavrou, describes the customization
|
||
options for the ~modus-operandi~ and ~modus-vivendi~ themes, and provides
|
||
every other piece of information pertinent to them.
|
||
|
||
The documentation furnished herein corresponds to stable version
|
||
{{{stable-version}}}, released on {{{release-date}}}. Any reference to a newer
|
||
feature which does not yet form part of the latest tagged commit, is
|
||
explicitly marked as such.
|
||
|
||
Current development target is {{{development-version}}}. This manual was
|
||
built on {{{export-date}}}.
|
||
|
||
#+toc: headlines 8 insert TOC here, with eight headline levels
|
||
|
||
* COPYING
|
||
:properties:
|
||
:copying: t
|
||
:custom_id: h:b14c3fcb-13dd-4144-9d92-2c58b3ed16d3
|
||
:end:
|
||
|
||
Copyright (C) 2020-2021 Free Software Foundation, Inc.
|
||
|
||
#+begin_quote
|
||
Permission is granted to copy, distribute and/or modify this
|
||
document under the terms of the GNU Free Documentation License,
|
||
Version 1.3 or any later version published by the Free Software
|
||
Foundation; with no Invariant Sections, with no Front-Cover Texts,
|
||
and with no Back-Cover Texts.
|
||
#+end_quote
|
||
|
||
* Overview
|
||
:properties:
|
||
:custom_id: h:f0f3dbcb-602d-40cf-b918-8f929c441baf
|
||
:end:
|
||
|
||
The Modus themes are designed for accessible readability. They conform
|
||
with the highest standard for color contrast between any given
|
||
combination of background and foreground values. This corresponds to
|
||
the WCAG AAA standard, which specifies a minimum rate of distance in
|
||
relative luminance of 7:1.
|
||
|
||
Modus Operandi (~modus-operandi~) is a light theme, while Modus Vivendi
|
||
(~modus-vivendi~) is dark. Each theme's color palette is designed to meet
|
||
the needs of the numerous interfaces that are possible in the Emacs
|
||
computing environment.
|
||
|
||
The overarching objective of this project is to always offer accessible
|
||
color combinations. There shall never be a compromise on this
|
||
principle. If there arises an inescapable trade-off between readability
|
||
and stylistic considerations, we will always opt for the former.
|
||
|
||
To ensure that users have a consistently accessible experience, the
|
||
themes strive to achieve as close to full face coverage as possible
|
||
([[#h:a9c8f29d-7f72-4b54-b74b-ddefe15d6a19][Face coverage]]).
|
||
|
||
Starting with version 0.12.0 and onwards, the themes are built into GNU
|
||
Emacs.
|
||
|
||
** How do the themes look like
|
||
:properties:
|
||
:custom_id: h:69b92089-069c-4ba1-9d94-cc3415fc4f87
|
||
:end:
|
||
#+cindex: Screenshots
|
||
|
||
Check the web page with [[https://protesilaos.com/modus-themes-pictures/][the screen shots]]. There are lots of scenarios
|
||
on display that draw attention to details and important aspects in the
|
||
design of the themes. They also showcase the numerous customization
|
||
options.
|
||
|
||
[[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization options]].
|
||
|
||
** Learn about the latest changes
|
||
:properties:
|
||
:custom_id: h:2cc37c36-6c1a-48b2-a010-1050b270ee18
|
||
:end:
|
||
#+cindex: Changelog
|
||
|
||
Please refer to the [[https://protesilaos.com/modus-themes-changelog][web page with the change log]]. It is comprehensive
|
||
and covers everything that goes into every tagged release of the themes.
|
||
|
||
* Installation
|
||
:properties:
|
||
:custom_id: h:1af85373-7f81-4c35-af25-afcef490c111
|
||
:end:
|
||
|
||
The Modus themes are distributed with Emacs starting with version 28.1.
|
||
On older versions of Emacs, they can be installed using Emacs' package
|
||
manager or manually from their code repository. There also exist
|
||
packages for distributions of GNU/Linux.
|
||
|
||
** Install manually from source
|
||
:properties:
|
||
:custom_id: h:da3414b7-1426-46b8-8e76-47b845b76fd0
|
||
:end:
|
||
|
||
In the following example, we are assuming that your Emacs files are
|
||
stored in =~/.emacs.d= and that you want to place the Modus themes in
|
||
=~/.emacs.d/modus-themes=.
|
||
|
||
1. Get the source and store it in the desired path by running the
|
||
following in the command line shell:
|
||
|
||
: $ git clone https://gitlab.com/protesilaos/modus-themes.git ~/.emacs.d/modus-themes
|
||
|
||
2. Add that path to your known Elisp libraries' list, by placing this
|
||
snippet of Emacs Lisp in your init file (e.g. {{{file(init.el)}}}):
|
||
|
||
#+begin_src emacs-lisp
|
||
(add-to-list 'load-path "~/.emacs.d/modus-themes")
|
||
#+end_src
|
||
|
||
The themes are now ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]].
|
||
|
||
** Install from the archives
|
||
:properties:
|
||
:custom_id: h:c4b10085-149f-43e2-bd4d-347f33aee054
|
||
:end:
|
||
|
||
The =modus-themes= package is available from the GNU ELPA archive, which
|
||
is configured by default.
|
||
|
||
Prior to querying any package archive, make sure to have updated the
|
||
index, with {{{kbd(M-x package-refresh-contents)}}}. Then all you need to do
|
||
is type {{{kbd(M-x package-install)}}} and specify the ~modus-themes~.
|
||
|
||
Note that older versions of the themes used to be distributed as
|
||
standalone packages. This practice has been discontinued starting with
|
||
version 1.0.0 of this project.
|
||
|
||
Once installed, the themes are ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]].
|
||
|
||
** Install on GNU/Linux
|
||
:properties:
|
||
:custom_id: h:da640eb1-95dd-4e86-bb4e-1027b27885f0
|
||
:end:
|
||
|
||
The themes are also available from the archives of some distributions of
|
||
GNU/Linux. These should correspond to a tagged release rather than
|
||
building directly from the latest Git commit. It all depends on the
|
||
distro's packaging policies.
|
||
|
||
*** Debian 11 Bullseye
|
||
:properties:
|
||
:custom_id: h:7e570360-9ee6-4bc5-8c04-9dc11418a3e4
|
||
:end:
|
||
|
||
The themes are part of Debian 11 Bullseye. Get them with:
|
||
|
||
#+begin_src sh
|
||
sudo apt install elpa-modus-themes
|
||
#+end_src
|
||
|
||
They are now ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]].
|
||
|
||
*** GNU Guix
|
||
:properties:
|
||
:custom_id: h:a4ca52cd-869f-46a5-9e16-4d9665f5b88e
|
||
:end:
|
||
|
||
Users of Guix can get the themes with this command:
|
||
|
||
#+begin_src sh
|
||
guix package -i emacs-modus-themes
|
||
#+end_src
|
||
|
||
They are now ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]].
|
||
|
||
* Enable and load
|
||
:properties:
|
||
:custom_id: h:3f3c3728-1b34-437d-9d0c-b110f5b161a9
|
||
:end:
|
||
#+findex: modus-themes-load-themes
|
||
#+findex: modus-themes-toggle
|
||
#+findex: modus-themes-load-operandi
|
||
#+findex: modus-themes-load-vivendi
|
||
#+cindex: Essential configuration
|
||
#+vindex: modus-themes-after-load-theme-hook
|
||
|
||
Users of the built-in themes can load and automatically enable the theme
|
||
of their preference by adding either form to their init file:
|
||
|
||
#+begin_src emacs-lisp
|
||
(load-theme 'modus-operandi) ; Light theme
|
||
(load-theme 'modus-vivendi) ; Dark theme
|
||
#+end_src
|
||
|
||
This is all one needs.
|
||
|
||
Users of packaged variants of the themes must add a few more lines to
|
||
ensure that everything works as intended. First, one has to require the
|
||
main library before loading either theme:
|
||
|
||
#+begin_src emacs-lisp
|
||
(require 'modus-themes)
|
||
#+end_src
|
||
|
||
Then it is recommended to load the individual theme files with the
|
||
helper function ~modus-themes-load-themes~:
|
||
|
||
#+begin_src emacs-lisp
|
||
;; Load the theme files before enabling a theme (else you get an error).
|
||
(modus-themes-load-themes)
|
||
#+end_src
|
||
|
||
Once the libraries that define the themes are enabled, one can activate
|
||
a theme with either of the following expressions:
|
||
|
||
#+begin_src emacs-lisp
|
||
(modus-themes-load-operandi) ; Light theme
|
||
;; OR
|
||
(modus-themes-load-vivendi) ; Dark theme
|
||
#+end_src
|
||
|
||
Changes to the available customization options must always be evaluated
|
||
before loading a theme ([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization Options]]). This is how a basic
|
||
setup could look like:
|
||
|
||
#+begin_src emacs-lisp
|
||
(require 'modus-themes)
|
||
|
||
;; Your customisations here. For example:
|
||
(setq modus-themes-bold-constructs t
|
||
modus-themes-mode-line '3d)
|
||
|
||
;; Load the theme files before enabling a theme (else you get an error).
|
||
(modus-themes-load-themes)
|
||
|
||
;; Enable the theme of your preference:
|
||
(modus-themes-load-operandi)
|
||
|
||
;; Optionally add a key binding for the toggle between the themes:
|
||
(define-key global-map (kbd "<f5>") #'modus-themes-toggle)
|
||
#+end_src
|
||
|
||
[[#h:e979734c-a9e1-4373-9365-0f2cd36107b8][Sample configuration for use-package]].
|
||
|
||
With those granted, bear in mind a couple of technical points on
|
||
~modus-themes-load-operandi~ and ~modus-themes-load-vivendi~, as well as
|
||
~modus-themes-toggle~ which relies on them:
|
||
|
||
1. Those functions call ~load-theme~. Some users prefer to opt for
|
||
~enable-theme~ instead ([[#h:e68560b3-7fb0-42bc-a151-e015948f8a35][Differences between loading and enabling]]).
|
||
|
||
2. The functions will run the ~modus-themes-after-load-theme-hook~ as
|
||
their final step. This can be employed for bespoke configurations
|
||
([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization (do-it-yourself)]]). Experienced users may not
|
||
wish to rely on such a hook and the functions that run it: they may
|
||
prefer a custom solution ([[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][A theme-agnostic hook for theme loading]]).
|
||
|
||
** Sample configuration for use-package
|
||
:properties:
|
||
:custom_id: h:e979734c-a9e1-4373-9365-0f2cd36107b8
|
||
:end:
|
||
#+cindex: use-package configuration
|
||
|
||
It is common for Emacs users to rely on ~use-package~ for declaring
|
||
package configurations in their setup. We use this as an example:
|
||
|
||
#+begin_src emacs-lisp
|
||
(use-package modus-themes
|
||
:ensure ; omit this to use the built-in themes
|
||
:init
|
||
;; Add all your customizations prior to loading the themes
|
||
(setq modus-themes-slanted-constructs t
|
||
modus-themes-bold-constructs nil)
|
||
|
||
;; Load the theme files before enabling a theme (else you get an error).
|
||
(modus-themes-load-themes)
|
||
:config
|
||
;; Load the theme of your choice:
|
||
(modus-themes-load-operandi) ;; OR (modus-themes-load-vivendi)
|
||
:bind ("<f5>" . modus-themes-toggle))
|
||
#+end_src
|
||
|
||
[[#h:e68560b3-7fb0-42bc-a151-e015948f8a35][Differences between loading and enabling]].
|
||
|
||
Note: make sure not to customize the variable ~custom-theme-load-path~
|
||
or ~custom-theme-directory~ after the themes' package declaration. That
|
||
will lead to failures in loading the files. If either or both of those
|
||
variables need to be changed, their values should be defined before the
|
||
package declaration of the themes.
|
||
|
||
** Differences between loading and enabling
|
||
:properties:
|
||
:custom_id: h:e68560b3-7fb0-42bc-a151-e015948f8a35
|
||
:end:
|
||
#+cindex: load-theme VS enable-theme
|
||
|
||
The reason we recommend ~load-theme~ instead of the other option of
|
||
~enable-theme~ is that the former does a kind of "reset" on the face
|
||
specs. It quite literally loads (or re-loads) the theme. Whereas the
|
||
latter simply puts an already loaded theme at the top of the list of
|
||
enabled items, re-using whatever state was last loaded.
|
||
|
||
As such, ~load-theme~ reads all customizations that may happen during
|
||
any given Emacs session: even after the initial setup of a theme.
|
||
Examples are calls to ~custom-set-faces~, as well as new values assigned
|
||
to the options the Modus themes provide ([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization Options]]).
|
||
|
||
Our tests show that ~enable-theme~ does not read such variables anew, so
|
||
it might appear to the unsuspecting user that the themes are somehow
|
||
broken whenever they try to assign a new value to a customization option
|
||
or some face.
|
||
|
||
This "reset" that ~load-theme~ conducts does, however, come at the cost
|
||
of being somewhat slower than ~enable-theme~. Users who have a stable
|
||
setup and who seldom update their variables during a given Emacs
|
||
session, are better off using something like this:
|
||
|
||
#+begin_src emacs-lisp
|
||
(require 'modus-themes)
|
||
(load-theme 'modus-operandi t t)
|
||
(load-theme 'modus-vivendi t t)
|
||
|
||
(enable-theme 'modus-operandi) ;; OR (enable-theme 'modus-vivendi)
|
||
#+end_src
|
||
|
||
[[#h:e979734c-a9e1-4373-9365-0f2cd36107b8][Sample configuration for use-package]].
|
||
|
||
With the above granted, other sections of the manual discuss how to
|
||
configure custom faces, where ~load-theme~ is expected, though
|
||
~enable-theme~ could still apply in stable setups:
|
||
|
||
[[#h:1487c631-f4fe-490d-8d58-d72ffa3bd474][Case-by-case face specs using the themes' palette]].
|
||
|
||
[[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]].
|
||
|
||
* Customization Options
|
||
:properties:
|
||
:custom_id: h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f
|
||
:end:
|
||
|
||
The Modus themes are highly configurable, though they should work well
|
||
without any further tweaks. By default, all customization options are
|
||
set to nil.
|
||
|
||
Remember that all customization options must be evaluated before loading
|
||
a theme ([[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]).
|
||
|
||
** Option for more bold constructs
|
||
:properties:
|
||
:alt_title: Bold constructs
|
||
:description: Toggle bold constructs in code
|
||
:custom_id: h:b25714f6-0fbe-41f6-89b5-6912d304091e
|
||
:end:
|
||
#+vindex: modus-themes-bold-constructs
|
||
|
||
Symbol: ~modus-themes-bold-constructs~
|
||
|
||
Possible values:
|
||
|
||
1. =nil= (default)
|
||
2. =t=
|
||
|
||
The default is to use a bold typographic weight only when it is
|
||
required.
|
||
|
||
With a non-nil value (=t=) display several syntactic constructs in bold
|
||
weight. This concerns keywords and other important aspects of code
|
||
syntax. It also affects certain mode line indicators and command-line
|
||
prompts.
|
||
|
||
** Option for more slanted constructs
|
||
:properties:
|
||
:alt_title: Slanted constructs
|
||
:description: Toggle slanted constructs (italics) in code
|
||
:custom_id: h:977c900d-0d6d-4dbb-82d9-c2aae69543d6
|
||
:end:
|
||
#+vindex: modus-themes-slanted-constructs
|
||
|
||
Symbol: ~modus-themes-slanted-constructs~
|
||
|
||
Possible values:
|
||
|
||
1. =nil= (default)
|
||
2. =t=
|
||
|
||
The default is to not use slanted text (italics) unless it is absolutely
|
||
necessary.
|
||
|
||
With a non-nil value (=t=) choose to render more faces in slanted text.
|
||
This typically affects documentation strings and code comments.
|
||
|
||
** Option for syntax highlighting
|
||
:properties:
|
||
:alt_title: Syntax styles
|
||
:description: Choose the overall aesthetic of code syntax
|
||
:custom_id: h:c119d7b2-fcd4-4e44-890e-5e25733d5e52
|
||
:end:
|
||
#+vindex: modus-themes-syntax
|
||
|
||
Symbol: ~modus-themes-syntax~
|
||
|
||
Possible values:
|
||
|
||
1. =nil= (default)
|
||
2. ~faint~
|
||
3. ~yellow-comments~
|
||
4. ~green-strings~
|
||
5. ~yellow-comments-green-strings~
|
||
6. ~alt-syntax~
|
||
7. ~alt-syntax-yellow-comments~
|
||
8. ~faint-yellow-comments~
|
||
|
||
The default style (nil) for code syntax highlighting is a balanced
|
||
combination of colors on the cyan-blue-magenta side of the spectrum.
|
||
There is little to no use of greens, yellows, or reds, except when it is
|
||
necessary.
|
||
|
||
Option ~faint~ is like the default in terms of the choice of palette but
|
||
applies desaturated color values.
|
||
|
||
Option ~yellow-comments~ adds a yellow tint to comments. The rest of the
|
||
syntax is the same as the default.
|
||
|
||
Option ~green-strings~ replaces the blue/cyan/cold color variants in
|
||
strings with greener alternatives. The rest of the syntax remains the
|
||
same.
|
||
|
||
Option ~yellow-comments-green-strings~ combines yellow comments with green
|
||
strings and the rest of the default syntax highlighting style.
|
||
|
||
Option ~alt-syntax~ expands the active spectrum by applying color
|
||
combinations with more contrasting hues between them. Expect to find
|
||
red and green variants in addition to cyan, blue, magenta.
|
||
|
||
Option ~alt-syntax-yellow-comments~ combines ~alt-syntax~ with
|
||
~yellow-comments~.
|
||
|
||
Option ~faint-yellow-comments~ combines the ~faint~ style with
|
||
~yellow-comments~.
|
||
|
||
** Option for no font mixing
|
||
:properties:
|
||
:alt_title: No mixed fonts
|
||
:description: Toggle mixing of font families
|
||
:custom_id: h:115e6c23-ee35-4a16-8cef-e2fcbb08e28b
|
||
:end:
|
||
#+vindex: modus-themes-no-mixed-fonts
|
||
|
||
Symbol: ~modus-themes-no-mixed-fonts~
|
||
|
||
Possible values:
|
||
|
||
1. =nil= (default)
|
||
2. =t=
|
||
|
||
By default, the themes configure some spacing-sensitive faces like Org
|
||
tables and code blocks to always inherit from the ~fixed-pitch~ face.
|
||
This is to ensure that those constructs remain monospaced even when
|
||
users opt for a mode that remaps typeface families, such as the built-in
|
||
{{{kbd(M-x variable-pitch-mode)}}}. Otherwise the layout would appear
|
||
broken, due to how spacing is done. To disable this behaviour, set the
|
||
option to =t=.
|
||
|
||
Users may prefer to use another package for handling mixed typeface
|
||
configurations, rather than letting the theme do it, perhaps because a
|
||
purpose-specific package has extra functionality. Two possible options
|
||
are ~org-variable-pitch~ and ~mixed-pitch~.
|
||
|
||
[[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org (and others)]].
|
||
|
||
** Option for links
|
||
:properties:
|
||
:alt_title: Link styles
|
||
:description: Choose among several styles, with or without underline
|
||
:custom_id: h:c119d7b2-fcd4-4e44-890e-5e25733d5e52
|
||
:end:
|
||
#+vindex: modus-themes-links
|
||
|
||
Symbol: ~modus-themes-links~
|
||
|
||
Possible values:
|
||
|
||
1. =nil= (default)
|
||
2. ~faint~
|
||
3. ~neutral-underline~
|
||
4. ~faint-neutral-underline~
|
||
5. ~no-underline~
|
||
6. ~underline-only~
|
||
7. ~neutral-underline-only~
|
||
|
||
The default style (nil) for links is to apply an underline and a
|
||
saturated color to the affected text. The color of the two is the same,
|
||
which makes the link fairly prominent.
|
||
|
||
Option ~faint~ follows the same approach as the default, but uses less
|
||
intense colors.
|
||
|
||
Option ~neutral-underline~ changes the underline's color to a subtle gray,
|
||
while retaining the default text color.
|
||
|
||
Option ~faint-neutral-underline~ combines a desaturated text color with a
|
||
subtle gray underline.
|
||
|
||
Option ~no-underline~ removes link underlines altogether, while retaining
|
||
their original fairly vivid color.
|
||
|
||
Option ~underline-only~ applies a prominent underline while making the
|
||
affected text colorless (it uses the same foreground as the theme's
|
||
default).
|
||
|
||
Option ~neutral-underline-only~ makes the text colorless while using a
|
||
subtle gray underline below it.
|
||
|
||
NOTE: The placement of the underline, i.e. its proximity to the affected
|
||
text, is controlled by the built-in ~x-underline-at-descent-line~,
|
||
~x-use-underline-position-properties~, ~underline-minimum-offset~. Please
|
||
refer to their documentation strings.
|
||
|
||
** Option for command prompt styles
|
||
:properties:
|
||
:alt_title: Command prompts
|
||
:description: Choose among plain, subtle, or intense prompts
|
||
:custom_id: h:db5a9a7c-2928-4a28-b0f0-6f2b9bd52ba1
|
||
:end:
|
||
#+vindex: modus-themes-prompts
|
||
|
||
Symbol: ~modus-themes-prompts~
|
||
|
||
Possible values:
|
||
|
||
1. =nil= (default)
|
||
2. ~subtle-accented~ (~subtle~ exists for backward compatibility)
|
||
3. ~intense-accented~ (~intense~ exists for backward compatibility)
|
||
4. ~subtle-gray~
|
||
5. ~intense-gray~
|
||
|
||
The default does not use any background for minibuffer and command line
|
||
prompts. It relies exclusively on an accented foreground color.
|
||
|
||
Options ~subtle-accented~ and ~intense-accented~ will change both the
|
||
background and the foreground values to use accented color combinations
|
||
that follow the hue of the default styles' foreground (e.g. the default
|
||
minibuffer prompt is cyan text, so these combinations will involved a
|
||
cyan background and an appropriate cyan foreground). The difference
|
||
between the two is that the latter has a more pronounced/noticeable
|
||
effect than the former.
|
||
|
||
Options ~subtle-gray~, ~intense-gray~ are like their accented counterparts,
|
||
except they use grayscale values.
|
||
|
||
** Option for mode line presentation
|
||
:properties:
|
||
:alt_title: Mode line
|
||
:description: Choose among several styles, with or without borders
|
||
:custom_id: h:27943af6-d950-42d0-bc23-106e43f50a24
|
||
:end:
|
||
#+vindex: modus-themes-mode-line
|
||
|
||
Symbol: ~modus-themes-mode-line~
|
||
|
||
Possible values:
|
||
|
||
1. =nil= (default)
|
||
2. ~3d~
|
||
3. ~moody~
|
||
4. ~borderless~
|
||
5. ~borderless-3d~
|
||
6. ~borderless-moody~
|
||
|
||
The default produces a two-dimensional effect both for the active and
|
||
inactive modelines. The differences between the two are limited to
|
||
distinct shades of grayscale values, with the active being more intense
|
||
than the inactive.
|
||
|
||
Option ~3d~ will make the active modeline look like a three-dimensional
|
||
rectangle. Inactive modelines remain 2D, though they are slightly toned
|
||
down relative to the default. This aesthetic is virtually the same as
|
||
what you get when you run Emacs without any customizations (=emacs -Q= on
|
||
the command line).
|
||
|
||
While ~moody~ removes all box effects from the modelines and applies
|
||
underline and overline properties instead. It also tones down a bit the
|
||
inactive modelines. This is meant to optimize things for use with the
|
||
[[https://github.com/tarsius/moody][moody package]] (hereinafter referred to as "Moody"), though it can work
|
||
fine even without it.
|
||
|
||
The ~borderless~ option uses the same colors as the default (nil value),
|
||
but removes the border effect. This is done by making the box property
|
||
use the same color as the background, effectively blending the two and
|
||
creating some padding.
|
||
|
||
The ~borderless-3d~ and ~borderless-moody~ approximate the ~3d~ and ~moody~
|
||
options respectively, while removing the borders. However, to ensure
|
||
that the inactive modelines remain visible, they apply a slightly more
|
||
prominent background to them than what their counterparts do (same
|
||
inactive background as with the default).
|
||
|
||
Note that Moody does not expose any faces that the themes could style
|
||
directly. Instead it re-purposes existing ones to render its tabs and
|
||
ribbons. As such, there may be cases where the contrast ratio falls
|
||
below the 7:1 target that the themes conform with (WCAG AAA). To hedge
|
||
against this, we configure a fallback foreground for the ~moody~ option,
|
||
which will come into effect when the background of the modeline changes
|
||
to something less accessible, such as Moody ribbons (read the doc string
|
||
of ~set-face-attribute~, specifically ~:distant-foreground~). This fallback
|
||
is activated when Emacs determines that the background and foreground of
|
||
the given construct are too close to each other in terms of color
|
||
distance. In effect, users would need to experiment with the variable
|
||
~face-near-same-color-threshold~ to trigger the effect. We find that a
|
||
value of =45000= will suffice, contrary to the default =30000=. Do not set
|
||
the value too high, because that would have the adverse effect of always
|
||
overriding the default color (which has been carefully designed to be
|
||
highly accessible).
|
||
|
||
Furthermore, because Moody expects an underline and overline instead of
|
||
a box style, it is advised you include this in your setup:
|
||
|
||
#+begin_src emacs-lisp
|
||
(setq x-underline-at-descent-line t)
|
||
#+end_src
|
||
|
||
** Option for completion framework aesthetics
|
||
:properties:
|
||
:alt_title: Completion UIs
|
||
:description: Choose among standard, moderate, or opinionated looks
|
||
:custom_id: h:f1c20c02-7b34-4c35-9c65-99170efb2882
|
||
:end:
|
||
#+vindex: modus-themes-completions
|
||
|
||
Symbol: ~modus-themes-completions~
|
||
|
||
Possible values:
|
||
|
||
1. =nil= (default)
|
||
2. ~moderate~
|
||
3. ~opinionated~
|
||
|
||
This is a special option that has different effects depending on the
|
||
completion UI. The interfaces can be grouped in two categories, based
|
||
on their default aesthetics: (i) those that only or mostly use
|
||
foreground colors for their interaction model, and (ii) those that
|
||
combine background and foreground values for some of their metaphors.
|
||
The former category encompasses Icomplete, Ido, Selectrum as well as
|
||
pattern matching styles like Orderless and Flx. The latter covers Helm,
|
||
Ivy, and similar.
|
||
|
||
A value of =nil= will respect the metaphors of each completion framework.
|
||
|
||
Option ~moderate~ applies a combination of background and foreground that
|
||
is fairly subtle. For Icomplete and friends this constitutes a
|
||
departure from their default aesthetics, however the difference is
|
||
small. While Helm, Ivy et al appear slightly different than their
|
||
original looks, as they are toned down a bit.
|
||
|
||
Option ~opinionated~ uses color combinations that refashion the completion
|
||
UI. For the Icomplete camp this means that intense background and
|
||
foreground combinations are used: in effect their looks emulate those of
|
||
Helm, Ivy and co. in their original style. Whereas the other group of
|
||
packages will revert to an even more nuanced aesthetic with some
|
||
additional changes to the choice of hues.
|
||
|
||
To appreciate the scope of this customization option, you should spend
|
||
some time with every one of the =nil= (default), ~moderate~, and ~opinionated~
|
||
possibilities.
|
||
|
||
** Option for fringe visibility
|
||
:properties:
|
||
:alt_title: Fringes
|
||
:description: Choose among invisible, subtle, or intense fringe styles
|
||
:custom_id: h:1983c3fc-74f6-44f3-b917-967c403bebae
|
||
:end:
|
||
#+vindex: modus-themes-fringes
|
||
|
||
Symbol: ~modus-themes-fringes~
|
||
|
||
Possible values:
|
||
|
||
1. =nil= (default)
|
||
2. ~subtle~
|
||
3. ~intense~
|
||
|
||
The default is to use the same color 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~.
|
||
|
||
Options ~subtle~ and ~intense~ apply a gray background, making the fringes
|
||
visible. The difference between the two is one of degree, as their
|
||
names imply.
|
||
|
||
** Option for language checkers
|
||
:properties:
|
||
:alt_title: Language checkers
|
||
:description: Control the style of language checkers/linters
|
||
:custom_id: h:4b13743a-8ebf-4d2c-a043-cceba10b1eb4
|
||
:end:
|
||
#+vindex: modus-themes-lang-checkers
|
||
|
||
Symbol: ~modus-themes-lang-checkers~
|
||
|
||
Possible values:
|
||
|
||
1. =nil= (default)
|
||
2. ~subtle-foreground~
|
||
3. ~intense-foreground~
|
||
4. ~straight-underline~
|
||
5. ~subtle-foreground-straight-underline~
|
||
6. ~intense-foreground-straight-underline~
|
||
7. ~colored-background~
|
||
|
||
Nil (the default) applies a color-coded underline to the affected text,
|
||
while it leaves the original foreground in tact. If the display spec
|
||
where Emacs runs in has support for it (e.g. Emacs GUI), the underline's
|
||
style is that of a wave, otherwise it is a straight line.
|
||
|
||
Options ~subtle-foreground~ and ~intense-foreground~ follow the same
|
||
color-coding pattern and wavy underline of the default, while extending
|
||
it with a corresponding foreground value for the affected text. The
|
||
difference between the two options is one of degree, as their names
|
||
suggest.
|
||
|
||
Option ~straight-underline~ is like the default but always applies a
|
||
straight line under the affected text. Same principle for
|
||
~subtle-foreground-straight-underline~ and its counterpart
|
||
~intense-foreground-straight-underline~.
|
||
|
||
Option ~colored-background~ uses a straight underline, a tinted
|
||
background, and a suitable foreground. All are color-coded. This is
|
||
the most intense combination of face properties.
|
||
|
||
The present variable affects packages and/or face groups such as those
|
||
of =flyspell=, =flymake=, =flycheck=, ~artbollocks-mode~, and ~writegood-mode~.
|
||
|
||
NOTE: The placement of the straight underline, though not the wave
|
||
style, is controlled by the built-in ~x-underline-at-descent-line~,
|
||
~x-use-underline-position-properties~, ~underline-minimum-offset~. Please
|
||
refer to their documentation strings.
|
||
|
||
** Option for line highlighting (hl-line-mode)
|
||
:properties:
|
||
:alt_title: Line highlighting
|
||
:description: Toggle intense style for current line highlighting
|
||
:custom_id: h:1dba1cfe-d079-4c13-a810-f768e8789177
|
||
:end:
|
||
#+vindex: modus-themes-intense-hl-line
|
||
|
||
Symbol: ~modus-themes-intense-hl-line~
|
||
|
||
Possible values:
|
||
|
||
1. =nil= (default)
|
||
2. =t=
|
||
|
||
The default is to use a subtle gray background for ~hl-line-mode~ and its
|
||
global equivalent.
|
||
|
||
With a non-nil value (=t=) use a more prominent background color instead.
|
||
|
||
This affects several packages that enable ~hl-line-mode~, such as =elfeed=
|
||
and =mu4e=.
|
||
|
||
** Option for line numbers (display-line-numbers-mode)
|
||
:properties:
|
||
:alt_title: Line numbers
|
||
:description: Toggle subtle style for line numbers
|
||
:custom_id: h:8c4a6230-2e43-4aa2-a631-3b7179392e09
|
||
:end:
|
||
#+vindex: modus-themes-subtle-line-numbers
|
||
|
||
Symbol: ~modus-themes-subtle-line-numbers~
|
||
|
||
Possible value:
|
||
|
||
1. =nil= (default)
|
||
2. =t=
|
||
|
||
The default style for ~display-line-numbers-mode~ and its global variant
|
||
is to apply a subtle gray background to the line numbers. The current
|
||
line has a more pronounced background and foreground combination to
|
||
bring more attention to itself.
|
||
|
||
Similarly, the faces for ~display-line-numbers-major-tick~ and its
|
||
counterpart ~display-line-numbers-minor-tick~ use appropriate styles that
|
||
involve a bespoke background and foreground combination.
|
||
|
||
With a non-nil value (=t=), line numbers have no background of their own.
|
||
Instead they retain the primary background of the theme, blending with
|
||
the rest of the buffer. Foreground values for all relevant faces are
|
||
updated to accommodate this aesthetic.
|
||
|
||
** Option for parenthesis matching (show-paren-mode)
|
||
:properties:
|
||
:alt_title: Matching parentheses
|
||
:description: Choose between various styles for matching delimiters/parentheses
|
||
:custom_id: h:e66a7e4d-a512-4bc7-9f86-fbbb5923bf37
|
||
:end:
|
||
#+vindex: modus-themes-paren-match
|
||
|
||
Symbol: ~modus-themes-paren-match~
|
||
|
||
Possible values:
|
||
|
||
1. =nil= (default)
|
||
2. ~subtle-bold~
|
||
3. ~intense~
|
||
4. ~intense-bold~
|
||
|
||
Nil means to use a subtle tinted background color for the matching
|
||
delimiters.
|
||
|
||
Option ~intense~ applies a saturated background color.
|
||
|
||
Option ~subtle-bold~ is the same as the default, but also makes use of
|
||
bold typographic weight (inherits the ~bold~ face).
|
||
|
||
Option ~intense-bold~ is the same as ~intense~, while it also uses a bold
|
||
weight.
|
||
|
||
This customization variable affects tools such as the built-in
|
||
~show-paren-mode~ and the =smartparens= package.
|
||
|
||
** Option for active region
|
||
:properties:
|
||
:alt_title: Active region
|
||
:description: Choose between various styles for the active region
|
||
:custom_id: h:60798063-b4ad-45ea-b9a7-ff7b5c0ab74c
|
||
:end:
|
||
#+vindex: modus-themes-region
|
||
|
||
Symbol: ~modus-themes-region~
|
||
|
||
Possible values:
|
||
|
||
1. =nil= (default)
|
||
2. ~no-extend~
|
||
3. ~bg-only~
|
||
4. ~bg-only-no-extend~
|
||
|
||
Nil means to only use a prominent gray background with a neutral
|
||
foreground. The foreground overrides all syntax highlighting. The
|
||
region extends to the edge of the window.
|
||
|
||
Option ~no-extend~ preserves the default aesthetic but prevents the region
|
||
from extending to the edge of the window.
|
||
|
||
Option ~bg-only~ applies a faint tinted background that is distinct from
|
||
all others used in the theme, while it does not override any existing
|
||
colors. It extends to the edge of the window.
|
||
|
||
Option ~bg-only-no-extend~ is a combination of the ~bg-only~ and ~no-extend~
|
||
options.
|
||
|
||
** Option for diff buffer looks
|
||
:properties:
|
||
:alt_title: Diffs
|
||
:description: Choose among intense, desaturated, or text-only diffs
|
||
:custom_id: h:ea7ac54f-5827-49bd-b09f-62424b3b6427
|
||
:end:
|
||
#+vindex: modus-themes-diffs
|
||
|
||
Symbol: ~modus-themes-diffs~
|
||
|
||
Possible values:
|
||
|
||
1. =nil= (default)
|
||
2. ~desaturated~
|
||
3. ~fg-only~
|
||
4. ~bg-only~
|
||
5. ~deuteranopia~
|
||
|
||
By default the themes apply rich coloration to the output of diffs, such
|
||
as those of ~diff-mode~, ~ediff~, ~smerge-mode~, and Magit. These are
|
||
color combinations of an accented background and foreground so that, for
|
||
example, added lines have a pronounced green background with an
|
||
appropriate shade of green for the affected text. Word-wise or
|
||
"refined" changes follow this pattern but use different shades of those
|
||
colors to remain distinct.
|
||
|
||
Option ~desaturated~ tones down all relevant color values. It still
|
||
combines an accented background with an appropriate foreground, yet its
|
||
overall impression is fairly subtle. Refined changes are a bit more
|
||
intense to fulfil their intended function, though still less saturated
|
||
than default.
|
||
|
||
Option ~fg-only~ will remove most accented backgrounds and instead rely
|
||
on color-coded text to denote changes. For instance, added lines use a
|
||
green foreground, while their background is the same as the rest of the
|
||
buffer. Word-wise highlights still use a background value which is,
|
||
nonetheless, more subtle than its default equivalent.
|
||
|
||
Option ~bg-only~ applies color-coded backgrounds but does not override
|
||
any syntax highlighting that may be present. This makes it suitable for
|
||
use with a non-nil value for ~diff-font-lock-syntax~ (which is the
|
||
default for ~diff-mode~ buffers in Emacs 27 or higher).
|
||
|
||
Option ~deuteranopia~ optimizes for red-green color deficiency. It
|
||
replaces all instances of green with blue variants. This is to ensure
|
||
that indicators for "removed" and "added" states are not mistaken for
|
||
each other.
|
||
|
||
Concerning Magit, an extra set of tweaks are introduced for the effect
|
||
of highlighting the current diff hunk, so as to remain aligned with the
|
||
overall experience of that mode. Expect changes that are consistent
|
||
with the overall intent of the aforementioned. Note, however, that the
|
||
~bg-only~ option will not deliver the intended results in Magit diffs
|
||
because no syntax highlighting is used there (last checked with Magit
|
||
version 20201116.1057, though upstream has a plan to eventually support
|
||
such a feature---this entry shall be updated accordingly).
|
||
|
||
** Option for org-mode block styles
|
||
:properties:
|
||
:alt_title: Org mode blocks
|
||
:description: Choose among plain, grayscale, or rainbow styles
|
||
:custom_id: h:b7e328c0-3034-4db7-9cdf-d5ba12081ca2
|
||
:end:
|
||
#+vindex: modus-themes-org-blocks
|
||
|
||
Symbol: ~modus-themes-org-blocks~
|
||
|
||
Possible values:
|
||
|
||
1. =nil= (default)
|
||
2. ~grayscale~
|
||
3. ~rainbow~
|
||
|
||
The default is to use the same background as the rest of the buffer for
|
||
the contents of the block.
|
||
|
||
Option ~grayscale~ applies a subtle neutral gray background to the block's
|
||
contents. It will also extend to the edge of the window the background
|
||
of the "begin" and "end" block delimiter lines (only relevant for Emacs
|
||
versions >= 27 where the 'extend' keyword is part of the face
|
||
specifications).
|
||
|
||
Option ~rainbow~ uses an accented background for the contents of the
|
||
block. The exact color will depend on the programming language and is
|
||
controlled by the ~org-src-block-faces~ variable. This is most suitable
|
||
for users who work on literate programming documents that mix and match
|
||
several languages.
|
||
|
||
Note that the "rainbow" blocks may require you to also reload the
|
||
major-mode so that the colors are applied consistently throughout: use
|
||
{{{kbd(M-x org-mode)}}} or {{{kbd(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 org-habit graph styles
|
||
:properties:
|
||
:alt_title: Org agenda habits
|
||
:description: Choose among standard, simplified, or traffic light styles
|
||
:custom_id: h:b7e328c0-3034-4db7-9cdf-d5ba12081ca2
|
||
:end:
|
||
#+vindex: modus-themes-org-habit
|
||
|
||
Symbol: ~modus-themes-org-habit~
|
||
|
||
Possible values:
|
||
|
||
1. =nil= (default)
|
||
2. ~simplified~
|
||
3. ~traffic-light~
|
||
|
||
The default is meant to conform with the original aesthetic of
|
||
=org-habit=. It employs all four color codes that correspond to the
|
||
org-habit states---clear, ready, alert, and overdue---while
|
||
distinguishing between their present and future variants. This results
|
||
in a total of eight colors in use: red, yellow, green, blue, in tinted
|
||
and shaded versions. They cover the full set of information provided by
|
||
the =org-habit= consistency graph.
|
||
|
||
Option ~simplified~ is like the default except that it removes the
|
||
dichotomy between current and future variants by applying uniform
|
||
color-coded values. It applies a total of four colors: red, yellow,
|
||
green, blue. They produce a simplified consistency graph that is more
|
||
legible (or less "busy") than the default. The intent is to shift focus
|
||
towards the distinction between the four states of a habit task, rather
|
||
than each state's present/future outlook.
|
||
|
||
Option ~traffic-light~ further reduces the available colors to red,
|
||
yellow, and green. As in ~simplified~, present and future variants appear
|
||
uniformly, but differently from it, the 'clear' state is rendered in a
|
||
green hue, instead of the original blue. This is meant to capture the
|
||
use-case where a habit task being "too early" is less important than it
|
||
being "too late". The difference between ready and clear states is
|
||
attenuated by painting both of them using shades of green. This option
|
||
thus highlights the alert and overdue states.
|
||
|
||
** Option for the headings' overall style
|
||
:properties:
|
||
:alt_title: Heading styles
|
||
:description: Choose among several styles, also per heading level
|
||
:custom_id: h:271eff19-97aa-4090-9415-a6463c2f9ae1
|
||
:end:
|
||
#+vindex: modus-themes-headings
|
||
|
||
This is defined as an alist and, therefore, uses a different approach
|
||
than other customization options documented in this manual.
|
||
|
||
Symbol: ~modus-themes-headings~
|
||
|
||
Possible values, which can be specified for each heading level (examples
|
||
further below):
|
||
|
||
+ nil (default fallback option---covers all heading levels)
|
||
+ =t= (default style for a single heading, when the fallback differs)
|
||
+ ~no-bold~
|
||
+ ~line~
|
||
+ ~line-no-bold~
|
||
+ ~rainbow~
|
||
+ ~rainbow-line~
|
||
+ ~rainbow-line-no-bold~
|
||
+ ~highlight~
|
||
+ ~highlight-no-bold~
|
||
+ ~rainbow-highlight~
|
||
+ ~rainbow-highlight-no-bold~
|
||
+ ~section~
|
||
+ ~section-no-bold~
|
||
+ ~rainbow-section~
|
||
+ ~rainbow-section-no-bold~
|
||
+ ~no-color~
|
||
+ ~no-color-no-bold~
|
||
|
||
To control faces per level from 1-8, use something like this:
|
||
|
||
#+begin_src emacs-lisp
|
||
(setq modus-themes-headings
|
||
'((1 . section)
|
||
(2 . section-no-bold)
|
||
(3 . rainbow-line)
|
||
(t . rainbow-line-no-bold)))
|
||
#+end_src
|
||
|
||
The above uses the ~section~ value for heading levels 1, ~section-no-bold~
|
||
for headings 2, ~rainbow-line~ for 3. All other levels fall back to
|
||
~rainbow-line-no-bold~.
|
||
|
||
To set a uniform value for all heading levels, use this pattern:
|
||
|
||
#+begin_src emacs-lisp
|
||
;; A given style for every heading
|
||
(setq modus-themes-headings
|
||
'((t . section)))
|
||
|
||
;; Default aesthetic for every heading
|
||
(setq modus-themes-headings
|
||
'())
|
||
#+end_src
|
||
|
||
The default style for headings uses a fairly desaturated foreground
|
||
value in combination with 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:
|
||
|
||
#+begin_src emacs-lisp
|
||
(setq modus-themes-headings
|
||
'((1 . t)
|
||
(2 . line)
|
||
(t . rainbow-line-no-bold)))
|
||
#+end_src
|
||
|
||
A description of all other possible styles beyond the default:
|
||
|
||
+ ~no-bold~ retains the default text color while removing the bold
|
||
typographic weight.
|
||
|
||
+ ~line~ is the same as the default plus an overline across the
|
||
heading's length.
|
||
|
||
+ ~line-no-bold~ is the same as ~line~ without bold weight.
|
||
|
||
+ ~rainbow~ uses a more colorful foreground in combination with bold
|
||
typographic weight.
|
||
|
||
+ ~rainbow-line~ is the same as ~rainbow~ plus an overline.
|
||
|
||
+ ~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 adds 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
|
||
colorful 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 colorful
|
||
foreground.
|
||
|
||
+ ~rainbow-section-no-bold~ is the same as ~rainbow-section~ without a
|
||
bold weight.
|
||
|
||
+ ~no-color~ does not apply any color to the heading, meaning that it
|
||
uses the foreground of the ~default~ face. It still renders the text
|
||
with a bold typographic weight.
|
||
|
||
+ ~no-color-no-bold~ is like ~no-color~ but without the bold weight.
|
||
|
||
** Option for scaled headings
|
||
:properties:
|
||
:alt_title: Scaled headings
|
||
:description: Toggle scaling of headings
|
||
:custom_id: h:075eb022-37a6-41a4-a040-cc189f6bfa1f
|
||
:end:
|
||
#+vindex: modus-themes-scale-headings
|
||
|
||
Symbol: ~modus-themes-scale-headings~
|
||
|
||
Possible values:
|
||
|
||
1. =nil= (default)
|
||
2. =t=
|
||
|
||
The default is to use the same size for headings and paragraph text.
|
||
|
||
With a non-nil value (=t=) make headings larger in height relative to the
|
||
main text. This is noticeable in modes like Org, Markdown, and Info.
|
||
|
||
*** Control the scale of headings
|
||
:properties:
|
||
:alt_title: Scaled heading sizes
|
||
:description: Specify rate of increase for scaled headings
|
||
:custom_id: h:6868baa1-beba-45ed-baa5-5fd68322ccb3
|
||
:end:
|
||
|
||
In addition to the toggle for enabling scaled headings, users can also
|
||
specify a number of their own.
|
||
|
||
+ If it is a floating point, say, =1.5=, it is interpreted as a multiple
|
||
of the base font size. This is the recommended method, because it
|
||
will always adapt to changes in the base font size, such as while
|
||
using the ~text-scale-adjust~ command.
|
||
|
||
+ If it is an integer, it is read as an absolute font height that is
|
||
1/10 of the typographic point size. Thus a value of =18pt= must be
|
||
expressed as =180=. Setting an absolute value is discouraged, as it
|
||
will break the layout in cases where the base font size must change,
|
||
such as with the ~text-scale-adjust~ command ([[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations]]).
|
||
While we discourage using absolute values, we still provide for this
|
||
option for users who do not need to perform text-scaling operations or
|
||
who are content with whatever discrepancies in height.
|
||
|
||
Below are the variables in their default values, using the floating
|
||
point paradigm. The numbers are very conservative, but one is free to
|
||
change them to their liking, such as =1.2=, =1.4=, =1.6=, =1.8=, =2.0=---or use a
|
||
resource for finding a consistent scale:
|
||
|
||
#+begin_src emacs-lisp
|
||
(setq modus-themes-scale-1 1.05
|
||
modus-themes-scale-2 1.1
|
||
modus-themes-scale-3 1.15
|
||
modus-themes-scale-4 1.2
|
||
modus-themes-scale-5 1.3)
|
||
#+end_src
|
||
|
||
As for the application of that scale, the variables that range from
|
||
~modus-themes-scale-1~ up to ~modus-themes-scale-4~ apply to regular
|
||
headings within the context of the given major mode. The former is the
|
||
smallest, while the latter is the largest. "Regular headings" are those
|
||
that have a standard syntax for their scale, such as Org mode's eight
|
||
levels of asterisks or Markdown's six columns.
|
||
|
||
Whereas ~modus-themes-scale-5~ is applied to special headings that do not
|
||
conform with the aforementioned syntax, yet which are expected to be
|
||
larger than the largest value on that implied scale. Put concretely,
|
||
Org's =#+title= meta datum is not part of the eight levels of headings in
|
||
an Org file, yet is supposed to signify the primary header. Similarly,
|
||
the Org Agenda's structure headings are not part of a recognisable scale
|
||
and so they also get ~modus-themes-scale-5~.
|
||
|
||
Users who wish to maintain scaled headings for the normal syntax while
|
||
preventing special headings from standing out, can assign a value of =1.0=
|
||
to ~modus-themes-scale-5~ to make it the same as body text (or whatever
|
||
value would render it indistinguishable from the desired point of
|
||
reference).
|
||
|
||
Note that in earlier versions of Org, scaling would only increase the
|
||
size of the heading, but not of keywords that were added to it, like
|
||
"TODO". The issue has been fixed upstream:
|
||
<https://protesilaos.com/codelog/2020-09-24-org-headings-adapt/>.
|
||
|
||
** Option for variable-pitch font in UI elements
|
||
:properties:
|
||
:alt_title: UI typeface
|
||
:description: Toggle the use of variable-pitch across the User Interface
|
||
:custom_id: h:16cf666c-5e65-424c-a855-7ea8a4a1fcac
|
||
:end:
|
||
#+vindex: modus-themes-variable-pitch-ui
|
||
|
||
Symbol: ~modus-themes-variable-pitch-ui~
|
||
|
||
Possible values:
|
||
|
||
1. =nil= (default)
|
||
2. =t=
|
||
|
||
This option concerns User Interface elements that are under the direct
|
||
control of Emacs. In particular: the mode line, header line, tab bar,
|
||
and tab line.
|
||
|
||
The default is to use the same font as the rest of Emacs, which usually
|
||
is a monospaced family.
|
||
|
||
With a non-nil value (=t=) apply a proportionately spaced typeface. This
|
||
is done by assigning the ~variable-pitch~ face to the relevant items.
|
||
|
||
[[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]].
|
||
|
||
** Option for variable-pitch font in headings
|
||
:properties:
|
||
:alt_title: Headings' typeface
|
||
:description: Toggle the use of variable-pitch in headings
|
||
:custom_id: h:97caca76-fa13-456c-aef1-a2aa165ea274
|
||
:end:
|
||
#+vindex: modus-themes-variable-pitch-headings
|
||
|
||
Symbol: ~modus-themes-variable-pitch-headings~
|
||
|
||
Possible values:
|
||
|
||
1. =nil= (default)
|
||
2. =t=
|
||
|
||
The default is to use the main font family, which typically is
|
||
monospaced.
|
||
|
||
With a non-nil value (=t=) apply a proportionately spaced typeface, else
|
||
"variable-pitch", to headings (such as in Org mode).
|
||
|
||
[[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]].
|
||
|
||
* Advanced customization (do-it-yourself)
|
||
:properties:
|
||
:custom_id: h:f4651d55-8c07-46aa-b52b-bed1e53463bb
|
||
:end:
|
||
|
||
Unlike the predefined customization options which follow a clear pattern
|
||
of allowing the user to quickly specify their preference, the themes
|
||
also provide a more flexible, albeit difficult, mechanism to control
|
||
things with precision ([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization Options]]).
|
||
|
||
This section is of interest only to users who are prepared to maintain
|
||
their own local tweaks and who are willing to deal with any possible
|
||
incompatibilities between versioned releases of the themes. As such,
|
||
they are labelled as "do-it-yourself" or "DIY".
|
||
|
||
** Per-theme customization settings (DIY)
|
||
:properties:
|
||
:custom_id: h:a897b302-8e10-4a26-beab-3caaee1e1193
|
||
:end:
|
||
|
||
If you prefer to maintain different customization options between the
|
||
two themes, it is best you write your own functions that first set those
|
||
options and then load the relevant theme. The following code does
|
||
exactly that by simply differentiating the two themes on the choice of
|
||
bold constructs in code syntax (enabled for one, disabled for the
|
||
other).
|
||
|
||
#+begin_src emacs-lisp
|
||
(defun my-demo-modus-operandi ()
|
||
(interactive)
|
||
(setq modus-themes-bold-constructs t) ; ENABLE bold
|
||
(modus-themes-load-operandi))
|
||
|
||
(defun my-demo-modus-vivendi ()
|
||
(interactive)
|
||
(setq modus-themes-bold-constructs nil) ; DISABLE bold
|
||
(modus-themes-load-vivendi))
|
||
|
||
(defun my-demo-modus-themes-toggle ()
|
||
(if (eq (car custom-enabled-themes) 'modus-operandi)
|
||
(my-demo-modus-vivendi)
|
||
(my-demo-modus-operandi)))
|
||
#+end_src
|
||
|
||
Then assign ~my-demo-modus-themes-toggle~ to a key instead of the
|
||
equivalent the themes provide.
|
||
|
||
For a more elaborate design, it is better to inspect the source code of
|
||
~modus-themes-toggle~ and relevant functions.
|
||
|
||
** Case-by-case face specs using the themes' palette (DIY)
|
||
:properties:
|
||
:custom_id: h:1487c631-f4fe-490d-8d58-d72ffa3bd474
|
||
:end:
|
||
#+findex: modus-themes-color
|
||
#+findex: modus-themes-color-alts
|
||
#+cindex: Extracting individual colors
|
||
|
||
This section is about tweaking individual faces. If you plan to do
|
||
things at scale, consult the next section: [[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Set multiple faces]].
|
||
|
||
We already covered in previous sections how to toggle between the themes
|
||
and how to configure options prior to loading. We also explained that
|
||
some of the functions made available to users will fire up a hook that
|
||
can be used to pass tweaks in the post-theme-load phase.
|
||
|
||
Now assume you wish to change a single face, say, the ~cursor~. And you
|
||
would like to get the standard "blue" color value of the active Modus
|
||
theme, whether it is Modus Operandi or Modus Vivendi. To do that, you
|
||
can use the ~modus-themes-color~ function. It accepts a symbol that is
|
||
associated with a color in ~modus-themes-operandi-colors~ and
|
||
~modus-themes-vivendi-colors~. Like this:
|
||
|
||
#+begin_src emacs-lisp
|
||
(modus-themes-color 'blue)
|
||
#+end_src
|
||
|
||
The function always extracts the color value of the active Modus theme.
|
||
|
||
#+begin_src emacs-lisp
|
||
(progn
|
||
(load-theme 'modus-operandi t)
|
||
(modus-themes-color 'blue)) ; "#0031a9" for `modus-operandi'
|
||
|
||
(progn
|
||
(load-theme 'modus-vivendi t)
|
||
(modus-themes-color 'blue)) ; "#2fafff" for `modus-vivendi'
|
||
#+end_src
|
||
|
||
Do {{{kbd(C-h v)}}} on the aforementioned variables to check all the available
|
||
symbols that can be passed to this function.
|
||
|
||
With that granted, let us expand the example to actually change the
|
||
~cursor~ face's background property. We employ the built-in function of
|
||
~set-face-attribute~:
|
||
|
||
#+begin_src emacs-lisp
|
||
(set-face-attribute 'cursor nil :background (modus-themes-color 'blue))
|
||
#+end_src
|
||
|
||
If you evaluate this form, your cursor will become blue. But if you
|
||
change themes, such as with ~modus-themes-toggle~, your edits will be
|
||
lost, because the newly loaded theme will override the =:background=
|
||
attribute you had assigned to that face.
|
||
|
||
For such changes to persist, we need to make them after loading the
|
||
theme. So we rely on ~modus-themes-after-load-theme-hook~, which gets
|
||
called from ~modus-themes-load-operandi~, ~modus-themes-load-vivendi~, as
|
||
well as the command ~modus-themes-toggle~. Here is a sample function that
|
||
tweaks two faces and then gets added to the hook:
|
||
|
||
#+begin_src emacs-lisp
|
||
(defun my-modus-themes-custom-faces ()
|
||
(set-face-attribute 'cursor nil :background (modus-themes-color 'blue))
|
||
(set-face-attribute 'font-lock-type-face nil :foreground (modus-themes-color 'magenta-alt)))
|
||
|
||
(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces)
|
||
#+end_src
|
||
|
||
[[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][A theme-agnostic hook for theme loading]].
|
||
|
||
Using this principle, it is possible to override the styles of faces
|
||
without having to find color values for each case.
|
||
|
||
Another application is to control the precise weight for bold
|
||
constructs. This is particularly useful if your typeface has several
|
||
variants such as "heavy", "extrabold", "semibold". All you have to do
|
||
is edit the ~bold~ face. For example:
|
||
|
||
#+begin_src emacs-lisp
|
||
(set-face-attribute 'bold nil :weight 'semibold)
|
||
#+end_src
|
||
|
||
Remember to use the custom function and hook combo we demonstrated
|
||
above. Because the themes do not hard-wire a specific weight, this
|
||
simple form is enough to change the weight of all bold constructs
|
||
throughout the interface.
|
||
|
||
Finally, there are cases where you want to tweak colors though wish to
|
||
apply different ones to each theme, say, a blue hue for Modus Operandi
|
||
and a shade of red for Modus Vivendi. To this end, we provide
|
||
~modus-themes-color-alts~ as a convenience function to save you from the
|
||
trouble of writing separate wrappers for each theme. It still returns a
|
||
single value by querying either of ~modus-themes-operandi-colors~ and
|
||
~modus-themes-vivendi-colors~, only here you pass the two keys you want,
|
||
first for ~modus-operandi~ then ~modus-vivendi~.
|
||
|
||
Take the previous example with the ~cursor~ face:
|
||
|
||
#+begin_src emacs-lisp
|
||
;; Blue for `modus-operandi' and red for `modus-vivendi'
|
||
(set-face-attribute 'cursor nil :background (modus-themes-color-alts 'blue 'red))
|
||
#+end_src
|
||
|
||
** Face specs at scale using the themes' palette (DIY)
|
||
:properties:
|
||
:custom_id: h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae
|
||
:end:
|
||
#+findex: modus-themes-with-colors
|
||
#+cindex: Extracting colors en masse
|
||
|
||
The examples here are for large scale operations. For simple, one-off
|
||
tweaks, you may prefer the approach documented in the previous section
|
||
([[#h:1487c631-f4fe-490d-8d58-d72ffa3bd474][Case-by-case face specs using the themes' palette]]).
|
||
|
||
The ~modus-themes-with-colors~ macro lets you retrieve multiple color
|
||
values by employing the backquote/backtick and comma notation. The
|
||
values are stored in the alists ~modus-themes-operandi-colors~ and
|
||
~modus-themes-vivendi-colors~, while the macro always queries that of the
|
||
active Modus theme.
|
||
|
||
Here is an abstract example that just returns a list of color values
|
||
while ~modus-operandi~ is enabled:
|
||
|
||
#+begin_src emacs-lisp
|
||
(modus-themes-with-colors
|
||
(list fg-main
|
||
blue-faint
|
||
magenta
|
||
magenta-alt-other
|
||
cyan-alt-other
|
||
fg-special-cold
|
||
blue-alt
|
||
magenta-faint
|
||
cyan
|
||
fg-main
|
||
green-faint
|
||
red-alt-faint
|
||
blue-alt-faint
|
||
fg-special-warm
|
||
cyan-alt
|
||
blue))
|
||
;; =>
|
||
;; ("#000000" "#002f88" "#721045" "#5317ac"
|
||
;; "#005a5f" "#093060" "#2544bb" "#752f50"
|
||
;; "#00538b" "#000000" "#104410" "#702f00"
|
||
;; "#003f78" "#5d3026" "#30517f" "#0031a9")
|
||
#+end_src
|
||
|
||
Getting a list of colors may have its applications, though what you are
|
||
most likely interested in is how to use those variables to configure
|
||
several faces at once. To do so we can rely on the built-in
|
||
~custom-set-faces~ function, which sets face specifications for the
|
||
special =user= theme. That "theme" gets applied on top of regular themes
|
||
like ~modus-operandi~ and ~modus-vivendi~.
|
||
|
||
This is how it works:
|
||
|
||
#+begin_src emacs-lisp
|
||
(modus-themes-with-colors
|
||
(custom-set-faces
|
||
`(cursor ((,class :background ,blue)))
|
||
`(mode-line ((,class :background ,yellow-nuanced-bg
|
||
:foreground ,yellow-nuanced-fg)))
|
||
`(mode-line-inactive ((,class :background ,blue-nuanced-bg
|
||
:foreground ,blue-nuanced-fg)))))
|
||
#+end_src
|
||
|
||
The above snippet will immediately refashion the faces it names once it
|
||
is evaluated. However, if you switch between the Modus themes, say,
|
||
from ~modus-operandi~ to ~modus-vivendi~, the colors will not get updated to
|
||
match those of the new theme. To make things work across the themes, we
|
||
need to employ the same technique we discussed in the previous section,
|
||
namely, to pass our changes at the post-theme-load phase via a hook.
|
||
|
||
The themes provide the ~modus-themes-after-load-theme-hook~, which gets
|
||
called from ~modus-themes-load-operandi~, ~modus-themes-load-vivendi~, as
|
||
well as the command ~modus-themes-toggle~. With this knowledge, you can
|
||
wrap the macro in a function and then assign that function to the hook.
|
||
Thus:
|
||
|
||
#+begin_src emacs-lisp
|
||
(defun my-modus-themes-custom-faces ()
|
||
(modus-themes-with-colors
|
||
(custom-set-faces
|
||
`(cursor ((,class :background ,blue)))
|
||
`(mode-line ((,class :background ,yellow-nuanced-bg
|
||
:foreground ,yellow-nuanced-fg)))
|
||
`(mode-line-inactive ((,class :background ,blue-nuanced-bg
|
||
:foreground ,blue-nuanced-fg))))))
|
||
|
||
(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces)
|
||
#+end_src
|
||
|
||
[[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][A theme-agnostic hook for theme loading]].
|
||
|
||
To discover the faces defined by all loaded libraries, you may do
|
||
{{{kbd(M-x list-faces-display)}}}. Be warned that when you =:inherit= a face
|
||
you are introducing an implicit dependency, so try to avoid doing so for
|
||
libraries other than the built-in {{{file(faces.el)}}} (or at least understand
|
||
that things may break if you inherit from a yet-to-be-loaded face).
|
||
|
||
Also bear in mind that these examples are meant to work with the Modus
|
||
themes. If you are cycling between multiple themes you may encounter
|
||
unforeseen issues, such as the colors of the Modus themes being applied
|
||
to a non-Modus item.
|
||
|
||
Finally, note that you can still use other functions where those make
|
||
sense. For example, the ~modus-themes-color-alts~ that was discussed in
|
||
the previous section. Adapt the above example like this:
|
||
|
||
#+begin_src emacs-lisp
|
||
...
|
||
(modus-themes-with-colors
|
||
(custom-set-faces
|
||
`(cursor ((,class :background ,(modus-themes-color-alts 'blue 'green))))
|
||
...))
|
||
#+end_src
|
||
|
||
** Override colors (DIY)
|
||
:properties:
|
||
:custom_id: h:307d95dd-8dbd-4ece-a543-10ae86f155a6
|
||
:end:
|
||
#+vindex: modus-themes-operandi-color-overrides
|
||
#+vindex: modus-themes-vivendi-color-overrides
|
||
#+cindex: Change a theme's colors
|
||
|
||
The themes provide a mechanism for overriding their color values. This
|
||
is controlled by the variables ~modus-themes-operandi-color-overrides~ and
|
||
~modus-themes-vivendi-color-overrides~, which are alists that should
|
||
mirror a subset of the associations in ~modus-themes-operandi-colors~ and
|
||
~modus-themes-vivendi-colors~ respectively. As with all customisations,
|
||
overriding must be done before loading the affected theme.
|
||
|
||
Let us approach the present topic one step at a time. Here is a
|
||
simplified excerpt of the default palette for Modus Operandi with some
|
||
basic background values that apply to buffers and the mode line
|
||
(remember to inspect the actual value to find out all the associations
|
||
that can be overridden):
|
||
|
||
#+begin_src emacs-lisp
|
||
(defconst modus-themes-colors-operandi
|
||
'((bg-main . "#ffffff")
|
||
(bg-dim . "#f8f8f8")
|
||
(bg-alt . "#f0f0f0")
|
||
(bg-active . "#d7d7d7")
|
||
(bg-inactive . "#efefef")))
|
||
#+end_src
|
||
|
||
As one can tell, we bind a key to a hexadecimal RGB color value. Now
|
||
say we wish to override those specific values and have our changes
|
||
propagate to all faces that use those keys. We could write something
|
||
like this, which adds a subtle ochre tint:
|
||
|
||
#+begin_src emacs-lisp
|
||
(setq modus-themes-operandi-color-overrides
|
||
'((bg-main . "#fefcf4")
|
||
(bg-dim . "#faf6ef")
|
||
(bg-alt . "#f7efe5")
|
||
(bg-active . "#e8dfd1")
|
||
(bg-inactive . "#f6ece5")))
|
||
#+end_src
|
||
|
||
Once this is evaluated, any subsequent loading of ~modus-operandi~ will
|
||
use those values instead of the defaults. No further intervention is
|
||
required.
|
||
|
||
To reset the changes, we apply this and reload the theme:
|
||
|
||
#+begin_src emacs-lisp
|
||
(setq modus-themes-operandi-color-overrides nil)
|
||
#+end_src
|
||
|
||
Users who wish to leverage such a mechanism can opt to implement it
|
||
on-demand by means of a global minor mode. The following snippet covers
|
||
both themes and expands to some more assosiations in the palette:
|
||
|
||
#+begin_src emacs-lisp
|
||
(define-minor-mode my-modus-themes-tinted
|
||
"Tweak some Modus themes colors."
|
||
:init-value nil
|
||
:global t
|
||
(if my-modus-themes-tinted
|
||
(setq modus-themes-operandi-color-overrides
|
||
'((bg-main . "#fefcf4")
|
||
(bg-dim . "#faf6ef")
|
||
(bg-alt . "#f7efe5")
|
||
(bg-hl-line . "#f4f0e3")
|
||
(bg-active . "#e8dfd1")
|
||
(bg-inactive . "#f6ece5")
|
||
(bg-region . "#c6bab1")
|
||
(bg-header . "#ede3e0")
|
||
(bg-tab-bar . "#dcd3d3")
|
||
(bg-tab-active . "#fdf6eb")
|
||
(bg-tab-inactive . "#c8bab8")
|
||
(fg-unfocused . "#55556f"))
|
||
modus-themes-vivendi-color-overrides
|
||
'((bg-main . "#100b17")
|
||
(bg-dim . "#161129")
|
||
(bg-alt . "#181732")
|
||
(bg-hl-line . "#191628")
|
||
(bg-active . "#282e46")
|
||
(bg-inactive . "#1a1e39")
|
||
(bg-region . "#393a53")
|
||
(bg-header . "#202037")
|
||
(bg-tab-bar . "#262b41")
|
||
(bg-tab-active . "#120f18")
|
||
(bg-tab-inactive . "#3a3a5a")
|
||
(fg-unfocused . "#9a9aab")))
|
||
(setq modus-themes-operandi-color-overrides nil
|
||
modus-themes-vivendi-color-overrides nil)))
|
||
#+end_src
|
||
|
||
With this in place, one can invoke {{{kbd(M-x my-modus-themes-tinted)}}} and
|
||
then load the Modus theme of their choice. The new palette subset will
|
||
come into effect: subtle ochre tints for Modus Operandi and night sky
|
||
shades for Modus Vivendi. Switching between the two themes, such as
|
||
with {{{kbd(M-x modus-themes-toggle)}}} will also use the overrides.
|
||
|
||
Given that this is a user-level customisation, one is free to implement
|
||
whatever color values they desire, even if the possible combinations
|
||
fall below the minimum 7:1 contrast ratio that governs the design of the
|
||
themes (the WCAG AAA legibility standard). Preferences aside, it is
|
||
advised to inspect the source code of ~modus-themes-operandi-colors~ and
|
||
~modus-themes-vivendi-colors~ to read the inline commentary: it explains
|
||
what the intended use of each palette subset is.
|
||
|
||
Furthermore, users may benefit from the ~modus-themes-contrast~ function
|
||
that we provide: [[#h:02e25930-e71a-493d-828a-8907fc80f874][test color combinations]]. It measures the contrast
|
||
ratio between two color values, so it can help in overriding the palette
|
||
(or a subset thereof) without making the end result inaccessible.
|
||
|
||
** Font configurations for Org and others (DIY)
|
||
:properties:
|
||
:custom_id: h:defcf4fc-8fa8-4c29-b12e-7119582cc929
|
||
:end:
|
||
#+cindex: Font configurations
|
||
|
||
The themes are designed to cope well with mixed font configurations.
|
||
|
||
[[#h:115e6c23-ee35-4a16-8cef-e2fcbb08e28b][Option for no font mixing]].
|
||
|
||
This mostly concerns ~org-mode~ and ~markdown-mode~, though expect to find
|
||
it elsewhere like in ~Info-mode~.
|
||
|
||
In practice it means that the user can safely opt for a more
|
||
prose-friendly proportionately spaced typeface as their default, while
|
||
letting spacing-sensitive elements like tables and inline code always
|
||
use a monospaced font, by inheriting from the ~fixed-pitch~ face.
|
||
|
||
Users can try the built-in {{{kbd(M-x variable-pitch-mode)}}} to see the
|
||
effect in action.
|
||
|
||
To make everything use your desired font families, you need to configure
|
||
the ~variable-pitch~ (proportional spacing) and ~fixed-pitch~ (monospaced)
|
||
faces respectively. It may also be convenient to set your main typeface
|
||
by configuring the ~default~ face the same way.
|
||
|
||
Put something like this in your initialization file (also consider
|
||
reading the doc string of ~set-face-attribute~):
|
||
|
||
#+begin_src emacs-lisp
|
||
;; Main typeface
|
||
(set-face-attribute 'default nil :family "DejaVu Sans Mono" :height 110)
|
||
|
||
;; Proportionately spaced typeface
|
||
(set-face-attribute 'variable-pitch nil :family "DejaVu Serif" :height 1.0)
|
||
|
||
;; Monospaced typeface
|
||
(set-face-attribute 'fixed-pitch nil :family "DejaVu Sans Mono" :height 1.0)
|
||
#+end_src
|
||
|
||
Note the differences in the =:height= property. The =default= face must
|
||
specify an absolute value, which is the point size × 10. So if you want
|
||
to use a font at point size =11=, you set the height to =110=.[fn:: =:height=
|
||
values do not need to be rounded to multiples of ten: the likes of =115=
|
||
are perfectly valid—some typefaces will change to account for those
|
||
finer increments.] Whereas every other face must have a value that is
|
||
relative to the default, represented as a floating point (if you use an
|
||
integer, then that means an absolute height). This is of paramount
|
||
importance: it ensures that all fonts can scale gracefully when using
|
||
something like the ~text-scale-adjust~ command which only operates on the
|
||
base font size (i.e. the ~default~ face's absolute height).
|
||
|
||
** Custom Org user faces (DIY)
|
||
:properties:
|
||
:custom_id: h:89f0678d-c5c3-4a57-a526-668b2bb2d7ad
|
||
:end:
|
||
#+cindex: Org extra faces
|
||
|
||
Users of ~org-mode~ have the option to configure various keywords and
|
||
priority cookies to better match their workflow. User options are
|
||
~org-todo-keyword-faces~ and ~org-priority-faces~.
|
||
|
||
As those are meant to be custom faces, it is futile to have the themes
|
||
guess what each user wants to use, which keywords to target, and so on.
|
||
Instead, we can provide guidelines on how to customize things to one's
|
||
liking with the intent of retaining the overall aesthetic of the themes.
|
||
|
||
Please bear in mind that the end result of those is not controlled by
|
||
the active Modus theme but by how Org maps faces to its constructs.
|
||
Editing those while ~org-mode~ is active requires re-initialization of the
|
||
mode with {{{kbd(M-x org-mode-restart)}}} for changes to take effect.
|
||
|
||
Let us assume you wish to visually differentiate your keywords. You
|
||
have something like this:
|
||
|
||
#+begin_src emacs-lisp
|
||
(setq org-todo-keywords
|
||
'((sequence "TODO(t)" "|" "DONE(D)" "CANCEL(C)")
|
||
(sequence "MEET(m)" "|" "MET(M)")
|
||
(sequence "STUDY(s)" "|" "STUDIED(S)")
|
||
(sequence "WRITE(w)" "|" "WROTE(W)")))
|
||
#+end_src
|
||
|
||
You could then use a variant of the following to inherit from a face
|
||
that uses the styles you want and also to preserve the properties
|
||
applied by the ~org-todo~ face:
|
||
|
||
#+begin_src emacs-lisp
|
||
(setq org-todo-keyword-faces
|
||
'(("MEET" . '(font-lock-preprocessor-face org-todo))
|
||
("STUDY" . '(font-lock-variable-name-face org-todo))
|
||
("WRITE" . '(font-lock-type-face org-todo))))
|
||
#+end_src
|
||
|
||
This will refashion the keywords you specify, while letting the other
|
||
items in ~org-todo-keywords~ use their original styles (which are defined
|
||
in the ~org-todo~ and ~org-done~ faces).
|
||
|
||
If you want back the defaults, try specifying just the ~org-todo~ face:
|
||
|
||
#+begin_src emacs-lisp
|
||
(setq org-todo-keyword-faces
|
||
'(("MEET" . org-todo)
|
||
("STUDY" . org-todo)
|
||
("WRITE" . org-todo)))
|
||
#+end_src
|
||
|
||
When you inherit from multiple faces, you need to quote the list as
|
||
shown further above. The order is important: the last item is applied
|
||
over the previous ones. If you do not want to blend multiple faces, you
|
||
do not need a quoted list. A pattern of =keyword . face= will suffice.
|
||
|
||
Both approaches can be used simultaneously, as illustrated in this
|
||
configuration of the priority cookies:
|
||
|
||
#+begin_src emacs-lisp
|
||
(setq org-priority-faces
|
||
'((?A . '(org-scheduled-today org-priority))
|
||
(?B . org-priority)
|
||
(?C . '(shadow org-priority))))
|
||
#+end_src
|
||
|
||
To find all the faces that are loaded in your current Emacs session, use
|
||
{{{kbd(M-x list-faces-display)}}}. Try {{{kbd(M-x describe-variable)}}} as well and
|
||
then specify the name of each of those Org variables demonstrated above.
|
||
Their documentation strings will offer you further guidance.
|
||
|
||
Recall that the themes let you retrieve a color from their palette. Do
|
||
it if you plan to control face attributes.
|
||
|
||
[[#h:1487c631-f4fe-490d-8d58-d72ffa3bd474][Custom face specs using the themes' palette]].
|
||
|
||
[[#h:02e25930-e71a-493d-828a-8907fc80f874][Check color combinations]].
|
||
|
||
** Measure color contrast (DIY)
|
||
:properties:
|
||
:custom_id: h:02e25930-e71a-493d-828a-8907fc80f874
|
||
:end:
|
||
#+findex: modus-themes-contrast
|
||
#+findex: modus-themes-wcag-formula
|
||
#+cindex: Color contrast
|
||
|
||
The themes provide the functions ~modus-themes-wcag-formula~ and
|
||
~modus-themes-contrast~. The former is a direct implementation of the
|
||
WCAG formula: <https://www.w3.org/TR/WCAG20-TECHS/G18.html>. It
|
||
calculates the relative luminance of a color value that is expressed in
|
||
hexadecimal RGB notation. While the latter function is just a
|
||
convenient wrapper for comparing the relative luminance between two
|
||
colors.
|
||
|
||
In practice, one needs to work only with ~modus-themes-contrast~. It
|
||
accepts two color values and returns their contrast ratio. Values range
|
||
from 1 to 21 (lowest to highest). The themes are designed to always be
|
||
equal or higher than 7 for each combination of background and foreground
|
||
that they use (this is the WCAG AAA standard---the most demanding of its
|
||
kind).
|
||
|
||
A couple of examples (rounded numbers):
|
||
|
||
#+begin_src emacs-lisp
|
||
;; Pure white with pure green
|
||
(modus-themes-contrast "#ffffff" "#00ff00")
|
||
;; => 1.37
|
||
;; That is an outright inaccessible combo
|
||
|
||
;; Pure black with pure green
|
||
(modus-themes-contrast "#000000" "#00ff00")
|
||
;; => 15.3
|
||
;; That is is a highly accessible combo
|
||
#+end_src
|
||
|
||
It does not matter which color value comes first. The ratio is always
|
||
the same.
|
||
|
||
If one does not wish to read all the decimal points, it is possible to
|
||
try something like this:
|
||
|
||
#+begin_src emacs-lisp
|
||
(format "%0.2f" (modus-themes-contrast "#000000" "#00ff00"))
|
||
#+end_src
|
||
|
||
While it is fine to perform such calculations on a case-by-case basis,
|
||
it is preferable to implement formulas and tables for more demanding
|
||
tasks. Such instruments are provided by ~org-mode~ or ~orgtbl-mode~, both
|
||
of which are built into Emacs. Below is such a table that derives the
|
||
contrast ratio of all colors in the first column (pure red, green, blue)
|
||
relative to the color specified in the first row of the second column
|
||
(pure white) and rounds the results:
|
||
|
||
#+begin_example
|
||
| | #ffffff |
|
||
|---------+---------|
|
||
| #ff0000 | 4.00 |
|
||
| #00ff00 | 1.37 |
|
||
| #0000ff | 8.59 |
|
||
#+tblfm: $2='(modus-themes-contrast $1 @1$2);%0.2f
|
||
#+end_example
|
||
|
||
To measure color contrast one needs to start from a known value. This
|
||
typically is the background. The Modus themes define an expanded
|
||
palette in large part because certain colors are only meant to be used
|
||
in combination with some others. Consult the source code for the
|
||
minutia and relevant commentary.
|
||
|
||
Such knowledge may prove valuable while attempting to override some of
|
||
the themes' colors: [[#h:307d95dd-8dbd-4ece-a543-10ae86f155a6][Override colors]].
|
||
|
||
** Load theme depending on time of day
|
||
:properties:
|
||
:custom_id: h:1d1ef4b4-8600-4a09-993c-6de3af0ddd26
|
||
:end:
|
||
|
||
While we do provide ~modus-themes-toggle~ to manually switch between the
|
||
themes, users may also set up their system to perform such a task
|
||
automatically at sunrise and sunset.
|
||
|
||
This can be accomplished by specifying the coordinates of one's location
|
||
using the built-in {{{file(solar.el)}}} and then configuring the =circadian=
|
||
package:
|
||
|
||
#+begin_src emacs-lisp
|
||
(use-package solar ; built-in
|
||
:config
|
||
(setq calendar-latitude 35.17
|
||
calendar-longitude 33.36))
|
||
|
||
(use-package circadian ; you need to install this
|
||
:ensure
|
||
:after solar
|
||
(setq circadian-themes '((:sunrise . modus-operandi)
|
||
(:sunset . modus-vivendi)))
|
||
(circadian-setup))
|
||
#+end_src
|
||
|
||
** A theme-agnostic hook for theme loading (DIY)
|
||
:properties:
|
||
:custom_id: h:86f6906b-f090-46cc-9816-1fe8aeb38776
|
||
:end:
|
||
|
||
The themes are designed with the intent to be useful to Emacs users of
|
||
varying skill levels, from beginners to experts. This means that we try
|
||
to make things easier by not expecting anyone reading this document to
|
||
be proficient in Emacs Lisp or programming in general.
|
||
|
||
Such a case is with the use of the ~modus-themes-after-load-theme-hook~,
|
||
which runs after ~modus-themes-toggle~, ~modus-themes-load-operandi~, or
|
||
~modus-themes-load-vivendi~ is evaluated. We recommend using that hook
|
||
for advanced customizations, because (1) we know for sure that it is
|
||
available once the themes are loaded, and (2) anyone consulting this
|
||
manual, especially the sections on enabling and loading the themes, will
|
||
be in a good position to benefit from that hook.
|
||
|
||
Advanced users who have a need to switch between the Modus themes and
|
||
other items will find that such a hook does not meet their requirements:
|
||
it only works with the Modus themes and only with the aforementioned
|
||
functions.
|
||
|
||
A theme-agnostic setup can be configured thus:
|
||
|
||
#+begin_src emacs-lisp
|
||
(defvar after-enable-theme-hook nil
|
||
"Normal hook run after enabling a theme.")
|
||
|
||
(defun run-after-enable-theme-hook (&rest _args)
|
||
"Run `after-enable-theme-hook'."
|
||
(run-hooks 'after-enable-theme-hook))
|
||
|
||
(advice-add 'enable-theme :after #'run-after-enable-theme-hook)
|
||
#+end_src
|
||
|
||
This creates the ~after-enable-theme-hook~ and makes it run after each
|
||
call to ~enable-theme~, which means that it will work for all themes and
|
||
also has the benefit that it does not depend on functions such as
|
||
~modus-themes-toggle~ and the others mentioned above. ~enable-theme~ is
|
||
called internally by ~load-theme~, so the hook works everywhere.
|
||
|
||
Now this specific piece of Elisp may be simple for experienced users,
|
||
but it is not easy to read for newcomers, including the author of the
|
||
Modus themes for the first several months of their time as an Emacs
|
||
user. Hence our hesitation to recommend it as part of the standard
|
||
setup of the Modus themes (it is generally a good idea to understand
|
||
what the implications are of advising a function).
|
||
|
||
* Face coverage
|
||
:properties:
|
||
:custom_id: h:a9c8f29d-7f72-4b54-b74b-ddefe15d6a19
|
||
:end:
|
||
|
||
The Modus themes try to provide as close to full face coverage as
|
||
possible. This is necessary to ensure a consistently accessible reading
|
||
experience across all available interfaces.
|
||
|
||
** Full support for packages or face groups
|
||
:properties:
|
||
:alt_title: Supported packages
|
||
:description: Full list of covered face groups
|
||
:custom_id: h:60ed4275-60d6-49f8-9287-9a64e54bea0e
|
||
:end:
|
||
#+cindex: Explicitly supported packages
|
||
|
||
This list will always be updated to reflect the current state of the
|
||
project. The idea is to offer an overview of the known status of all
|
||
affected face groups. The items with an appended asterisk =*= tend to
|
||
have lots of extensions, so the "full support" may not be 100% true…
|
||
|
||
+ ace-window
|
||
+ ag
|
||
+ alert
|
||
+ all-the-icons
|
||
+ annotate
|
||
+ anzu
|
||
+ apropos
|
||
+ apt-sources-list
|
||
+ artbollocks-mode
|
||
+ auctex and TeX
|
||
+ auto-dim-other-buffers
|
||
+ avy
|
||
+ awesome-tray
|
||
+ bbdb
|
||
+ binder
|
||
+ bm
|
||
+ bongo
|
||
+ boon
|
||
+ breakpoint (provided by the built-in {{{file(gdb-mi.el)}}} library)
|
||
+ buffer-expose
|
||
+ calendar and diary
|
||
+ calfw
|
||
+ centaur-tabs
|
||
+ cfrs
|
||
+ change-log and log-view (such as ~vc-print-log~, ~vc-print-root-log~)
|
||
+ cider
|
||
+ circe
|
||
+ color-rg
|
||
+ column-enforce-mode
|
||
+ company-mode*
|
||
+ company-posframe
|
||
+ compilation-mode
|
||
+ completions
|
||
+ consult
|
||
+ counsel*
|
||
+ counsel-css
|
||
+ counsel-notmuch
|
||
+ counsel-org-capture-string
|
||
+ cov
|
||
+ cperl-mode
|
||
+ csv-mode
|
||
+ ctrlf
|
||
+ custom (what you get with {{{kbd(M-x customize)}}})
|
||
+ dap-mode
|
||
+ dashboard (emacs-dashboard)
|
||
+ deadgrep
|
||
+ debbugs
|
||
+ define-word
|
||
+ deft
|
||
+ dictionary
|
||
+ diff-hl
|
||
+ diff-mode
|
||
+ dim-autoload
|
||
+ dir-treeview
|
||
+ dired
|
||
+ dired-async
|
||
+ dired-git
|
||
+ dired-git-info
|
||
+ dired-narrow
|
||
+ dired-subtree
|
||
+ diredc
|
||
+ diredfl
|
||
+ diredp (dired+)
|
||
+ disk-usage
|
||
+ display-fill-column-indicator-mode
|
||
+ doom-modeline
|
||
+ dynamic-ruler
|
||
+ easy-jekyll
|
||
+ easy-kill
|
||
+ ebdb
|
||
+ ediff
|
||
+ eglot
|
||
+ el-search
|
||
+ eldoc-box
|
||
+ elfeed
|
||
+ elfeed-score
|
||
+ emms
|
||
+ enhanced-ruby-mode
|
||
+ epa
|
||
+ equake
|
||
+ erc
|
||
+ eros
|
||
+ ert
|
||
+ eshell
|
||
+ eshell-fringe-status
|
||
+ eshell-git-prompt
|
||
+ eshell-prompt-extras (epe)
|
||
+ eshell-syntax-highlighting
|
||
+ evil* (evil-mode)
|
||
+ evil-goggles
|
||
+ evil-snipe
|
||
+ evil-visual-mark-mode
|
||
+ eww
|
||
+ exwm
|
||
+ eyebrowse
|
||
+ fancy-dabbrev
|
||
+ flycheck
|
||
+ flycheck-color-mode-line
|
||
+ flycheck-indicator
|
||
+ flycheck-posframe
|
||
+ flymake
|
||
+ flyspell
|
||
+ flyspell-correct
|
||
+ flx
|
||
+ freeze-it
|
||
+ frog-menu
|
||
+ focus
|
||
+ fold-this
|
||
+ font-lock (generic syntax highlighting)
|
||
+ forge
|
||
+ fountain (fountain-mode)
|
||
+ geiser
|
||
+ git-commit
|
||
+ git-gutter (and variants)
|
||
+ git-lens
|
||
+ git-rebase
|
||
+ git-timemachine
|
||
+ git-walktree
|
||
+ gnus
|
||
+ golden-ratio-scroll-screen
|
||
+ helm*
|
||
+ helm-ls-git
|
||
+ helm-switch-shell
|
||
+ helm-xref
|
||
+ helpful
|
||
+ highlight-blocks
|
||
+ highlight-defined
|
||
+ highlight-escape-sequences (~hes-mode~)
|
||
+ highlight-indentation
|
||
+ highlight-numbers
|
||
+ highlight-symbol
|
||
+ highlight-tail
|
||
+ highlight-thing
|
||
+ hl-defined
|
||
+ hl-fill-column
|
||
+ hl-line-mode
|
||
+ hl-todo
|
||
+ hydra
|
||
+ hyperlist
|
||
+ ibuffer
|
||
+ icomplete
|
||
+ icomplete-vertical
|
||
+ ido-mode
|
||
+ iedit
|
||
+ iflipb
|
||
+ imenu-list
|
||
+ indium
|
||
+ info
|
||
+ info-colors
|
||
+ interaction-log
|
||
+ ioccur
|
||
+ isearch, occur, etc.
|
||
+ isl (isearch-light)
|
||
+ ivy*
|
||
+ ivy-posframe
|
||
+ jira (org-jira)
|
||
+ journalctl-mode
|
||
+ js2-mode
|
||
+ julia
|
||
+ jupyter
|
||
+ kaocha-runner
|
||
+ keycast
|
||
+ line numbers (~display-line-numbers-mode~ and global variant)
|
||
+ lsp-mode
|
||
+ lsp-ui
|
||
+ macrostep
|
||
+ magit
|
||
+ magit-imerge
|
||
+ make-mode
|
||
+ man
|
||
+ marginalia
|
||
+ markdown-mode
|
||
+ markup-faces (~adoc-mode~)
|
||
+ mentor
|
||
+ messages
|
||
+ minibuffer-line
|
||
+ minimap
|
||
+ mmm-mode
|
||
+ modeline
|
||
+ mood-line
|
||
+ moody
|
||
+ mpdel
|
||
+ mu4e
|
||
+ mu4e-conversation
|
||
+ multiple-cursors
|
||
+ neotree
|
||
+ no-emoji
|
||
+ notmuch
|
||
+ num3-mode
|
||
+ nxml-mode
|
||
+ objed
|
||
+ orderless
|
||
+ org*
|
||
+ org-journal
|
||
+ org-noter
|
||
+ org-pomodoro
|
||
+ org-recur
|
||
+ org-roam
|
||
+ org-superstar
|
||
+ org-table-sticky-header
|
||
+ org-tree-slide
|
||
+ org-treescope
|
||
+ origami
|
||
+ outline-mode
|
||
+ outline-minor-faces
|
||
+ package (what you get with {{{kbd(M-x list-packages)}}})
|
||
+ page-break-lines
|
||
+ paradox
|
||
+ paren-face
|
||
+ parrot
|
||
+ pass
|
||
+ pdf-tools
|
||
+ persp-mode
|
||
+ perspective
|
||
+ phi-grep
|
||
+ phi-search
|
||
+ pkgbuild-mode
|
||
+ pomidor
|
||
+ popup
|
||
+ powerline
|
||
+ powerline-evil
|
||
+ prism ([[#h:a94272e0-99da-4149-9e80-11a7e67a2cf2][Note for prism.el]])
|
||
+ proced
|
||
+ prodigy
|
||
+ quick-peek
|
||
+ racket-mode
|
||
+ rainbow-blocks
|
||
+ rainbow-identifiers
|
||
+ rainbow-delimiters
|
||
+ rcirc
|
||
+ recursion-indicator
|
||
+ regexp-builder (also known as ~re-builder~)
|
||
+ rg (rg.el)
|
||
+ ripgrep
|
||
+ rmail
|
||
+ ruler-mode
|
||
+ sallet
|
||
+ selectrum
|
||
+ selectrum-prescient
|
||
+ semantic
|
||
+ sesman
|
||
+ shell-script-mode
|
||
+ shortdoc
|
||
+ show-paren-mode
|
||
+ shr
|
||
+ side-notes
|
||
+ sieve-mode
|
||
+ skewer-mode
|
||
+ smart-mode-line
|
||
+ smartparens
|
||
+ smerge
|
||
+ solaire
|
||
+ spaceline
|
||
+ speedbar
|
||
+ spell-fu
|
||
+ spray
|
||
+ stripes
|
||
+ suggest
|
||
+ switch-window
|
||
+ swiper
|
||
+ swoop
|
||
+ sx
|
||
+ symbol-overlay
|
||
+ syslog-mode
|
||
+ table (built-in table.el)
|
||
+ telephone-line
|
||
+ terraform-mode
|
||
+ term
|
||
+ tomatinho
|
||
+ transient (pop-up windows such as Magit's)
|
||
+ trashed
|
||
+ treemacs
|
||
+ tty-menu
|
||
+ tuareg
|
||
+ typescript
|
||
+ undo-tree
|
||
+ vc (built-in mode line status for version control)
|
||
+ vc-annotate (the out put of {{{kbd(C-x v g)}}})
|
||
+ vdiff
|
||
+ vimish-fold
|
||
+ visible-mark
|
||
+ visual-regexp
|
||
+ volatile-highlights
|
||
+ vterm
|
||
+ wcheck-mode
|
||
+ web-mode
|
||
+ wgrep
|
||
+ which-function-mode
|
||
+ which-key
|
||
+ whitespace-mode
|
||
+ window-divider-mode
|
||
+ winum
|
||
+ writegood-mode
|
||
+ woman
|
||
+ xah-elisp-mode
|
||
+ xref
|
||
+ xterm-color (and ansi-colors)
|
||
+ yaml-mode
|
||
+ yasnippet
|
||
+ ztree
|
||
|
||
Plus many other miscellaneous faces that are provided by the upstream
|
||
GNU Emacs distribution.
|
||
|
||
** Indirectly covered packages
|
||
:properties:
|
||
:custom_id: h:2cb359c7-3a84-4262-bab3-dcdc1d0034d7
|
||
:end:
|
||
#+cindex: Implicitly supported packages
|
||
|
||
These do not require any extra styles because they are configured to
|
||
inherit from some basic faces. Please confirm.
|
||
|
||
+ edit-indirect
|
||
+ evil-owl
|
||
+ fortran-mode
|
||
+ goggles
|
||
+ i3wm-config-mode
|
||
+ perl-mode
|
||
+ php-mode
|
||
+ rjsx-mode
|
||
+ swift-mode
|
||
+ tab-bar-echo-area
|
||
|
||
* Notes for individual packages
|
||
:properties:
|
||
:custom_id: h:4c4d901a-84d7-4f20-bd99-0808c2b06eba
|
||
:end:
|
||
|
||
This section covers information that may be of interest to users of
|
||
individual packages.
|
||
|
||
** Note for display-fill-column-indicator-mode
|
||
:properties:
|
||
:custom_id: h:2a602816-bc1b-45bf-9675-4cbbd7bf6cab
|
||
:end:
|
||
|
||
While designing the style for ~display-fill-column-indicator-mode~, we
|
||
stayed close to the mode's defaults: to apply a subtle foreground color
|
||
to the ~fill-column-indicator~ face, which blends well with the rest of
|
||
theme and is consistent with the role of that mode. This is to not
|
||
upset the expectations of users.
|
||
|
||
Nevertheless, ~display-fill-column-indicator-mode~ has some known
|
||
limitations pertaining to its choice of using typographic characters to
|
||
draw its indicator. What should be a continuous vertical line might
|
||
appear as a series of dashes in certain contexts or under specific
|
||
conditions: a non-default value for ~line-spacing~, scaled and/or
|
||
variable-pitch headings have been observed to cause this effect.
|
||
|
||
Given that we cannot control such factors, it may be better for affected
|
||
users to deviate from the default style of the ~fill-column-indicator~
|
||
face. Instead of setting a foreground color, one could use a background
|
||
and have the foreground be indistinguishable from it. For example:
|
||
|
||
#+begin_src emacs-lisp
|
||
(modus-themes-with-colors
|
||
(custom-set-faces
|
||
`(fill-column-indicator ((,class :background ,bg-inactive
|
||
:foreground ,bg-inactive)))))
|
||
#+end_src
|
||
|
||
[[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]].
|
||
|
||
** Note for mmm-mode.el background colors
|
||
:properties:
|
||
:custom_id: h:99cf0d6c-e478-4e26-9932-3bf3427d13f6
|
||
:end:
|
||
|
||
The faces used by {{{file(mmm-mode.el)}}} are expected to have a colorful
|
||
background, while they should not touch any foreground value. The idea
|
||
is that they must not interfere with existing fontification. Those
|
||
background colors need to be distinct from each other, such as an
|
||
unambiguous red juxtaposed with a clear blue.
|
||
|
||
While this design may be internally consistent with the raison d'être of
|
||
that library, it inevitably produces inaccessible color combinations.
|
||
|
||
There are two competing goals at play:
|
||
|
||
1. Legibility of the text, understood as the contrast ratio between the
|
||
background and the foreground.
|
||
|
||
2. Semantic precision of each face which entails faithfulness to
|
||
color-coding of the underlying background.
|
||
|
||
As the Modus themes are designed with the express purpose of conforming
|
||
with the first point, we have to forgo the apparent color-coding of the
|
||
background elements. Instead we use subtle colors that do not undermine
|
||
the legibility of the affected text while they still offer a sense of
|
||
added context.
|
||
|
||
Users who might prefer to fall below the minimum 7:1 contrast ratio in
|
||
relative luminance (the accessibility target we conform with), can opt
|
||
to configure the relevant faces on their own.
|
||
|
||
[[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]].
|
||
|
||
This example uses more vivid background colors, though it comes at the
|
||
very high cost of degraded legibility.
|
||
|
||
#+begin_src emacs-lisp
|
||
(modus-themes-with-colors
|
||
(custom-set-faces
|
||
`(mmm-cleanup-submode-face ((,class :background ,yellow-refine-bg)))
|
||
`(mmm-code-submode-face ((,class :background ,bg-active)))
|
||
`(mmm-comment-submode-face ((,class :background ,blue-refine-bg)))
|
||
`(mmm-declaration-submode-face ((,class :background ,cyan-refine-bg)))
|
||
`(mmm-default-submode-face ((,class :background ,bg-alt)))
|
||
`(mmm-init-submode-face ((,class :background ,magenta-refine-bg)))
|
||
`(mmm-output-submode-face ((,class :background ,red-refine-bg)))
|
||
`(mmm-special-submode-face ((,class :background ,green-refine-bg)))))
|
||
#+end_src
|
||
|
||
** Note for prism.el
|
||
:properties:
|
||
:alt_title: Note for prism
|
||
:custom_id: h:a94272e0-99da-4149-9e80-11a7e67a2cf2
|
||
:end:
|
||
|
||
This package by Adam Porter, aka "alphapapa" or "github-alphapapa",
|
||
implements an alternative to the typical coloration of code. Instead of
|
||
highlighting the syntactic constructs, it applies color to different
|
||
levels of depth in the code structure.
|
||
|
||
As {{{file(prism.el)}}} offers a broad range of customisations, we cannot
|
||
style it directly at the theme level: that would run contrary to the
|
||
spirit of the package. Instead, we may offer preset color schemes.
|
||
Those should offer a starting point for users to adapt to their needs.
|
||
|
||
In the following code snippets, we employ the ~modus-themes-with-colors~
|
||
macro: [[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]].
|
||
|
||
These are the minimum recommended settings with 16 colors:
|
||
|
||
#+begin_src emacs-lisp
|
||
(setq prism-num-faces 16)
|
||
|
||
(prism-set-colors
|
||
:desaturations '(0) ; do not change---may lower the contrast ratio
|
||
:lightens '(0) ; same
|
||
:colors (modus-themes-with-colors
|
||
(list fg-main
|
||
magenta
|
||
cyan-alt-other
|
||
magenta-alt-other
|
||
blue
|
||
magenta-alt
|
||
cyan-alt
|
||
red-alt-other
|
||
green
|
||
fg-main
|
||
cyan
|
||
yellow
|
||
blue-alt
|
||
red-alt
|
||
green-alt-other
|
||
fg-special-warm)))
|
||
#+end_src
|
||
|
||
With 8 colors:
|
||
|
||
#+begin_src emacs-lisp
|
||
(setq prism-num-faces 8)
|
||
|
||
(prism-set-colors
|
||
:desaturations '(0) ; do not change---may lower the contrast ratio
|
||
:lightens '(0) ; same
|
||
:colors (modus-themes-with-colors
|
||
(list fg-special-cold
|
||
magenta
|
||
magenta-alt-other
|
||
cyan-alt-other
|
||
fg-main
|
||
blue-alt
|
||
red-alt-other
|
||
cyan)))
|
||
#+end_src
|
||
|
||
And this is with 4 colors, which produces results that are the closest
|
||
to the themes' default aesthetic:
|
||
|
||
#+begin_src emacs-lisp
|
||
(setq prism-num-faces 4)
|
||
|
||
(prism-set-colors
|
||
:desaturations '(0) ; do not change---may lower the contrast ratio
|
||
:lightens '(0) ; same
|
||
:colors (modus-themes-with-colors
|
||
(list fg-main
|
||
cyan-alt-other
|
||
magenta-alt-other
|
||
magenta)))
|
||
#+end_src
|
||
|
||
If you need to apply desaturation and lightening, you can use what the
|
||
{{{file(prism.el)}}} documentation recommends, like this (adapting to the
|
||
examples with the 4, 8, 16 colors):
|
||
|
||
#+begin_src emacs-lisp
|
||
(prism-set-colors
|
||
:desaturations (cl-loop for i from 0 below 16 collect (* i 2.5))
|
||
:lightens (cl-loop for i from 0 below 16 collect (* i 2.5))
|
||
:colors (modus-themes-with-colors
|
||
(list fg-main
|
||
cyan-alt-other
|
||
magenta-alt-other
|
||
magenta)))
|
||
#+end_src
|
||
|
||
** Note on company-mode overlay pop-up
|
||
:properties:
|
||
:custom_id: h:20cef8c4-d11f-4053-8b2c-2872925780b1
|
||
:end:
|
||
|
||
By default, the ~company-mode~ pop-up that lists completion candidates is
|
||
drawn using an overlay. This creates alignment issues every time it is
|
||
placed above a piece of text that has a different height than the
|
||
default.
|
||
|
||
The solution recommended by the project's maintainer is to use an
|
||
alternative front-end for drawing the pop-up which draws child frames
|
||
instead of overlays.[fn::
|
||
https://github.com/company-mode/company-mode/issues/1010][fn::
|
||
https://github.com/tumashu/company-posframe/]
|
||
|
||
** Note for ERC escaped color sequences
|
||
:properties:
|
||
:custom_id: h:98bdf319-1e32-4469-8a01-771200fba65c
|
||
:end:
|
||
|
||
The built-in IRC client ~erc~ has the ability to colorise any text using
|
||
escape sequences that start with =^C= (inserted with {{{kbd(C-q C-c)}}}) and are
|
||
followed by a number for the foreground and background.[fn:: This page
|
||
explains the basics, though it is not specific to Emacs:
|
||
https://www.mirc.com/colors.html] Possible numbers are 0-15, with the
|
||
first entry being the foreground and the second the background,
|
||
separated by a comma. Like this =^C1,6=. The minimum setup is this:
|
||
|
||
#+begin_src emacs-lisp
|
||
(add-to-list 'erc-modules 'irccontrols)
|
||
(setq erc-interpret-controls-p t
|
||
erc-interpret-mirc-color t)
|
||
#+end_src
|
||
|
||
As this allows users the chance to make arbitrary combinations, it is
|
||
impossible to guarantee a consistently high contrast ratio. All we can
|
||
we do is provide guidance on the combinations that satisfy the
|
||
accessibility standard of the themes:
|
||
|
||
+ Modus Operandi :: Use foreground color 1 for all backgrounds from
|
||
2-15. Like so: {{{kbd(C-q C-c1,N)}}} where =N= is the background.
|
||
|
||
+ Modus Vivendi :: Use foreground color 0 for all backgrounds from
|
||
2-13. Use foreground =1= for backgrounds 14, 15.
|
||
|
||
Colors 0 and 1 are white and black respectively. So combine them
|
||
together, if you must.
|
||
|
||
** Note for powerline or spaceline
|
||
:properties:
|
||
:custom_id: h:9130a8ba-d8e3-41be-a58b-3cb1eb7b6d17
|
||
:end:
|
||
|
||
Both Powerline and Spaceline package users will likely need to use the
|
||
command ~powerline-reset~ whenever they make changes to their themes
|
||
and/or modeline setup.
|
||
|
||
** Note on SHR colors
|
||
:properties:
|
||
:custom_id: h:4cc767dc-ffef-4c5c-9f10-82eb7b8921bf
|
||
:end:
|
||
|
||
Emacs' HTML rendering library ({{{file(shr.el)}}}) may need explicit
|
||
configuration to respect the theme's colors instead of whatever
|
||
specifications the webpage provides.
|
||
|
||
Consult {{{kbd(C-h v shr-use-colors)}}}.
|
||
|
||
** Note for Helm grep
|
||
:properties:
|
||
:custom_id: h:d28879a2-8e4b-4525-986e-14c0f873d229
|
||
:end:
|
||
|
||
There is one face from the Helm package that is meant to highlight the
|
||
matches of a grep or grep-like command (=ag= or =ripgrep=). It is
|
||
~helm-grep-match~. However, this face can only apply when the user does
|
||
not pass =--color=always= as a command-line option for their command.
|
||
|
||
Here is the docstring for that face, which is defined in the
|
||
{{{file(helm-grep.el)}}} library (you can always visit the source code with
|
||
{{{kbd(M-x find-library)}}}).
|
||
|
||
#+begin_quote
|
||
Face used to highlight grep matches. Have no effect when grep backend
|
||
use "--color="
|
||
#+end_quote
|
||
|
||
The user must either remove =--color= from the flags passed to the grep
|
||
function, or explicitly use =--color=never= (or equivalent). Helm
|
||
provides user-facing customization options for controlling the grep
|
||
function's parameters, such as ~helm-grep-default-command~ and
|
||
~helm-grep-git-grep-command~.
|
||
|
||
When =--color=always= is in effect, the grep output will use red text in
|
||
bold letter forms to present the matching part in the list of
|
||
candidates. That style still meets the contrast ratio target of >= 7:1
|
||
(accessibility standard WCAG AAA), because it draws the reference to
|
||
ANSI color number 1 (red) from the already-supported array of
|
||
~ansi-color-names-vector~.
|
||
|
||
** Note on vc-annotate-background-mode
|
||
:properties:
|
||
:custom_id: h:5095cbd1-e17a-419c-93e8-951c186362a3
|
||
:end:
|
||
|
||
Due to the unique way ~vc-annotate~ ({{{kbd(C-x v g)}}}) applies colors, support
|
||
for its background mode (~vc-annotate-background-mode~) is disabled at the
|
||
theme level.
|
||
|
||
Normally, such a drastic measure should not belong in a theme: assuming
|
||
the user's preferences is bad practice. However, it has been deemed
|
||
necessary in the interest of preserving color contrast accessibility
|
||
while still supporting a useful built-in tool.
|
||
|
||
If there actually is a way to avoid such a course of action, without
|
||
prejudice to the accessibility standard of this project, then please
|
||
report as much or send patches ([[#h:9c3cd842-14b7-44d7-84b2-a5c8bc3fc3b1][Contributing]]).
|
||
|
||
** Note on pdf-tools link hints
|
||
:properties:
|
||
:custom_id: h:2659d13e-b1a5-416c-9a89-7c3ce3a76574
|
||
:end:
|
||
|
||
Hints are drawn by [[https://imagemagick.org/][ImageMagick]], not Emacs, i.e., ImageMagick doesn't
|
||
know about the hint face unless you tell ImageMagick about it. By
|
||
default, only the foreground and background color attributes are
|
||
passed. The below snippet adds to those the various font attributes. As
|
||
it queries various faces, specifically ~pdf-links-read-link~ and the faces
|
||
it inherits, it needs to be added to your initialization file after
|
||
you've customized any faces.
|
||
|
||
#+begin_src emacs-lisp
|
||
(use-package pdf-links
|
||
:config
|
||
(let ((spec
|
||
(apply #'append
|
||
(mapcar
|
||
(lambda (name)
|
||
(list name
|
||
(face-attribute 'pdf-links-read-link
|
||
name nil 'default)))
|
||
'(:family :width :weight :slant)))))
|
||
(setq pdf-links-read-link-convert-commands
|
||
`("-density" "96"
|
||
"-family" ,(plist-get spec :family)
|
||
"-stretch" ,(let* ((width (plist-get spec :width))
|
||
(name (symbol-name width)))
|
||
(replace-regexp-in-string "-" ""
|
||
(capitalize name)))
|
||
"-weight" ,(pcase (plist-get spec :weight)
|
||
('ultra-light "Thin")
|
||
('extra-light "ExtraLight")
|
||
('light "Light")
|
||
('semi-bold "SemiBold")
|
||
('bold "Bold")
|
||
('extra-bold "ExtraBold")
|
||
('ultra-bold "Black")
|
||
(_weight "Normal"))
|
||
"-style" ,(pcase (plist-get spec :slant)
|
||
('italic "Italic")
|
||
('oblique "Oblique")
|
||
(_slant "Normal"))
|
||
"-pointsize" "%P"
|
||
"-undercolor" "%f"
|
||
"-fill" "%b"
|
||
"-draw" "text %X,%Y '%c'"))))
|
||
#+end_src
|
||
|
||
* Contributing
|
||
:properties:
|
||
:custom_id: h:9c3cd842-14b7-44d7-84b2-a5c8bc3fc3b1
|
||
:end:
|
||
|
||
This section documents the canonical sources of the themes and the ways
|
||
in which you can contribute to their ongoing development.
|
||
|
||
** Sources of the themes
|
||
:properties:
|
||
:custom_id: h:89504f1c-c9a1-4bd9-ab39-78fd0eddb47c
|
||
:end:
|
||
#+cindex: Sources of the themes
|
||
|
||
The ~modus-operandi~ and ~modus-vivendi~ themes are built into Emacs.
|
||
Currently they are in Emacs' git main branch (trunk), which is tracking
|
||
the next development release target.
|
||
|
||
The source code of the themes is [[https://gitlab.com/protesilaos/modus-themes/][available on Gitlab]], for the time
|
||
being. A [[https://github.com/protesilaos/modus-themes/][mirror on Github]] is also on offer.
|
||
|
||
An HTML version of this manual is provided as an extension of the
|
||
[[https://protesilaos.com/modus-themes/][author's personal website]] (does not rely on any non-free code).
|
||
|
||
** Issues you can help with
|
||
:properties:
|
||
:custom_id: h:6536c8d5-3f98-43ab-a787-b94120e735e8
|
||
:end:
|
||
#+cindex: Contributing
|
||
|
||
A few tasks you can help with:
|
||
|
||
+ Suggest refinements to packages that are covered.
|
||
+ Report packages not covered thus far.
|
||
+ Report bugs, inconsistencies, shortcomings.
|
||
+ Help expand the documentation of covered-but-not-styled packages.
|
||
+ Suggest refinements to the color palette.
|
||
+ Help expand this document or any other piece of documentation.
|
||
+ Merge requests for code refinements.
|
||
|
||
[[#h:111773e2-f26f-4b68-8c4f-9794ca6b9633][Patches require copyright assignment to the FSF]].
|
||
|
||
It is preferable that your feedback includes some screenshots, GIFs, or
|
||
short videos, as well as further instructions to reproduce a given
|
||
setup. Though this is not a requirement.
|
||
|
||
Whatever you do, bear in mind the overarching objective of the Modus
|
||
themes: to keep a contrast ratio that is greater or equal to 7:1 between
|
||
background and foreground colors. If a compromise is ever necessary
|
||
between aesthetics and accessibility, it shall always be made in the
|
||
interest of the latter.
|
||
|
||
** Patches require copyright assignment to the FSF
|
||
:properties:
|
||
:custom_id: h:111773e2-f26f-4b68-8c4f-9794ca6b9633
|
||
:end:
|
||
|
||
Code contributions are most welcome. For any major edit (more than 15
|
||
lines, or so, in aggregate per person), you need to make a copyright
|
||
assignment to the Free Software Foundation. This is necessary because
|
||
the themes are part of the upstream Emacs distribution: the FSF must at
|
||
all times be in a position to enforce the GNU General Public License.
|
||
|
||
Copyright assignment is a simple process. Check the request form below
|
||
(please adapt it accordingly). You must write an email to the address
|
||
mentioned in the form and then wait for the FSF to send you a legal
|
||
agreement. Sign the document and file it back to them. This could all
|
||
happen via email and take about a week. You are encouraged to go
|
||
through this process. You only need to do it once. It will allow you
|
||
to make contributions to Emacs in general.
|
||
|
||
#+begin_example text
|
||
Please email the following information to assign@gnu.org, and we
|
||
will send you the assignment form for your past and future changes.
|
||
|
||
Please use your full legal name (in ASCII characters) as the subject
|
||
line of the message.
|
||
----------------------------------------------------------------------
|
||
REQUEST: SEND FORM FOR PAST AND FUTURE CHANGES
|
||
|
||
[What is the name of the program or package you're contributing to?]
|
||
|
||
GNU Emacs
|
||
|
||
[Did you copy any files or text written by someone else in these changes?
|
||
Even if that material is free software, we need to know about it.]
|
||
|
||
Copied a few snippets from the same files I edited. Their author,
|
||
Protesilaos Stavrou, has already assigned copyright to the Free Software
|
||
Foundation.
|
||
|
||
[Do you have an employer who might have a basis to claim to own
|
||
your changes? Do you attend a school which might make such a claim?]
|
||
|
||
|
||
[For the copyright registration, what country are you a citizen of?]
|
||
|
||
|
||
[What year were you born?]
|
||
|
||
|
||
[Please write your email address here.]
|
||
|
||
|
||
[Please write your postal address here.]
|
||
|
||
|
||
|
||
|
||
|
||
[Which files have you changed so far, and which new files have you written
|
||
so far?]
|
||
|
||
#+end_example
|
||
|
||
* Acknowledgements
|
||
:properties:
|
||
:custom_id: h:95c3da23-217f-404e-b5f3-56c75760ebcf
|
||
:end:
|
||
#+cindex: Contributors
|
||
|
||
The Modus themes are a collective effort. Every bit of work matters.
|
||
|
||
+ Author/maintainer :: Protesilaos Stavrou.
|
||
|
||
+ Contributions to code or documentation :: Anders Johansson, Basil
|
||
L.{{{space()}}} Contovounesios, Carlo Zancanaro, Eli Zaretskii, Kostadin
|
||
Ninev, Madhavan Krishnan, Markus Beppler, Matthew Stevenson, Nicolas
|
||
De Jaeghere, Shreyas Ragavan, Stefan Kangas, Vincent Murphy, Xinglu
|
||
Chen.
|
||
|
||
+ Ideas and user feedback :: Aaron Jensen, Adam Spiers, Adrian Manea,
|
||
Alex Griffin, Alex Peitsinis, Alexey Shmalko, Alok Singh, Anders
|
||
Johansson, André Alexandre Gomes, Arif Rezai, Basil L.{{{space()}}}
|
||
Contovounesios, Burgess Chang, Christian Tietze, Christopher Dimech,
|
||
Damien Cassou, Daniel Mendler, Dario Gjorgjevski, David Edmondson,
|
||
Davor Rotim, Divan Santana, Gerry Agbobada, Gianluca Recchia, Gustavo
|
||
Barros, Hörmetjan Yiltiz, Ilja Kocken, Iris Garcia, Jeremy Friesen,
|
||
John Haman, Joshua O'Connor, Kevin Fleming, Kostadin Ninev, Len Trigg,
|
||
Manuel Uberti, Mark Burton, Markus Beppler, Michael Goldenberg, Morgan
|
||
Smith, Murilo Pereira, Nicolas De Jaeghere, Paul Poloskov, Pete
|
||
Kazmier, Peter Wu, Philip K., Pierre Téchoueyres, Roman Rudakov, Ryan
|
||
Phillips, Sam Kleinman, Shreyas Ragavan, Simon Pugnet, Tassilo Horn,
|
||
Thibaut Verron, Trey Merkley, Togan Muftuoglu, Toon Claes, Uri Sharf,
|
||
Utkarsh Singh, Vincent Foley. As well as users: Ben, CsBigDataHub1,
|
||
Emacs Contrib, Eugene, Fourchaux, Fredrik, Moesasji, Nick, TheBlob42,
|
||
bepolymathe, doolio, fleimgruber, iSeeU, jixiuf, okamsn.
|
||
|
||
+ Packaging :: Basil L.{{{space()}}} Contovounesios, Eli Zaretskii, Glenn
|
||
Morris, Mauro Aranda, Richard Stallman, Stefan Kangas (core Emacs),
|
||
Stefan Monnier (GNU Elpa), André Alexandre Gomes, Dimakakos Dimos,
|
||
Morgan Smith, Nicolas Goaziou (Guix), Dhavan Vaidya (Debian).
|
||
|
||
+ Inspiration for certain features :: Bozhidar Batsov (zenburn-theme),
|
||
Fabrice Niessen (leuven-theme).
|
||
|
||
Special thanks, in no particular order, to Manuel Uberti and Omar
|
||
Antolín Camarena for their long time contributions and insightful
|
||
commentary.
|
||
|
||
* Meta
|
||
:properties:
|
||
:custom_id: h:13752581-4378-478c-af17-165b6e76bc1b
|
||
:end:
|
||
#+cindex: Development notes
|
||
|
||
If you are curious about the principles that govern the development of
|
||
this project read the essay [[https://protesilaos.com/codelog/2020-03-17-design-modus-themes-emacs/][On the design of the Modus themes]]
|
||
(2020-03-17).
|
||
|
||
Here are some more publications for those interested in the kind of work
|
||
that goes into this project (sometimes the commits also include details
|
||
of this sort):
|
||
|
||
+ [[https://protesilaos.com/codelog/2020-05-10-modus-operandi-palette-review/][Modus Operandi theme subtle palette review]] (2020-05-10)
|
||
+ [[https://protesilaos.com/codelog/2020-06-13-modus-vivendi-palette-review/][Modus Vivendi theme subtle palette review]] (2020-06-13)
|
||
+ [[https://protesilaos.com/codelog/2020-07-04-modus-themes-faint-colours/][Modus themes: new "faint syntax" option]] (2020-07-04)
|
||
+ [[https://protesilaos.com/codelog/2020-07-08-modus-themes-nuanced-colours/][Modus themes: major review of "nuanced" colours]] (2020-07-08)
|
||
+ [[https://protesilaos.com/codelog/2020-09-14-modus-themes-review-blues/][Modus themes: review of blue colours]] (2020-09-14)
|
||
+ [[https://protesilaos.com/codelog/2020-12-27-modus-themes-review-rainbow-delimiters/][Modus themes: review rainbow-delimiters faces]] (2020-12-27)
|
||
+ [[https://protesilaos.com/codelog/2021-01-11-modus-themes-review-select-faint-colours/][Modus themes: review of select "faint" colours]] (2021-01-11)
|
||
+ [[https://protesilaos.com/codelog/2021-02-25-modus-themes-diffs-deuteranopia/][The Modus themes now cover deuteranopia in diffs]] (2021-02-25)
|
||
|
||
And here are the canonical sources of this project's documentation:
|
||
|
||
+ Manual :: <https://protesilaos.com/modus-themes>
|
||
+ Change Log :: <https://protesilaos.com/modus-themes-changelog>
|
||
+ Screenshots :: <https://protesilaos.com/modus-themes-pictures>
|
||
|
||
* GNU Free Documentation License
|
||
:properties:
|
||
:appendix: t
|
||
:custom_id: h:3077c3d2-7f90-4228-8f0a-73124f4026f6
|
||
:end:
|
||
|
||
#+texinfo: @include doclicense.texi
|
||
|
||
#+begin_export html
|
||
|
||
GNU Free Documentation License
|
||
Version 1.3, 3 November 2008
|
||
|
||
|
||
Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
|
||
<https://fsf.org/>
|
||
Everyone is permitted to copy and distribute verbatim copies
|
||
of this license document, but changing it is not allowed.
|
||
|
||
0. PREAMBLE
|
||
|
||
The purpose of this License is to make a manual, textbook, or other
|
||
functional and useful document "free" in the sense of freedom: to
|
||
assure everyone the effective freedom to copy and redistribute it,
|
||
with or without modifying it, either commercially or noncommercially.
|
||
Secondarily, this License preserves for the author and publisher a way
|
||
to get credit for their work, while not being considered responsible
|
||
for modifications made by others.
|
||
|
||
This License is a kind of "copyleft", which means that derivative
|
||
works of the document must themselves be free in the same sense. It
|
||
complements the GNU General Public License, which is a copyleft
|
||
license designed for free software.
|
||
|
||
We have designed this License in order to use it for manuals for free
|
||
software, because free software needs free documentation: a free
|
||
program should come with manuals providing the same freedoms that the
|
||
software does. But this License is not limited to software manuals;
|
||
it can be used for any textual work, regardless of subject matter or
|
||
whether it is published as a printed book. We recommend this License
|
||
principally for works whose purpose is instruction or reference.
|
||
|
||
|
||
1. APPLICABILITY AND DEFINITIONS
|
||
|
||
This License applies to any manual or other work, in any medium, that
|
||
contains a notice placed by the copyright holder saying it can be
|
||
distributed under the terms of this License. Such a notice grants a
|
||
world-wide, royalty-free license, unlimited in duration, to use that
|
||
work under the conditions stated herein. The "Document", below,
|
||
refers to any such manual or work. Any member of the public is a
|
||
licensee, and is addressed as "you". You accept the license if you
|
||
copy, modify or distribute the work in a way requiring permission
|
||
under copyright law.
|
||
|
||
A "Modified Version" of the Document means any work containing the
|
||
Document or a portion of it, either copied verbatim, or with
|
||
modifications and/or translated into another language.
|
||
|
||
A "Secondary Section" is a named appendix or a front-matter section of
|
||
the Document that deals exclusively with the relationship of the
|
||
publishers or authors of the Document to the Document's overall
|
||
subject (or to related matters) and contains nothing that could fall
|
||
directly within that overall subject. (Thus, if the Document is in
|
||
part a textbook of mathematics, a Secondary Section may not explain
|
||
any mathematics.) The relationship could be a matter of historical
|
||
connection with the subject or with related matters, or of legal,
|
||
commercial, philosophical, ethical or political position regarding
|
||
them.
|
||
|
||
The "Invariant Sections" are certain Secondary Sections whose titles
|
||
are designated, as being those of Invariant Sections, in the notice
|
||
that says that the Document is released under this License. If a
|
||
section does not fit the above definition of Secondary then it is not
|
||
allowed to be designated as Invariant. The Document may contain zero
|
||
Invariant Sections. If the Document does not identify any Invariant
|
||
Sections then there are none.
|
||
|
||
The "Cover Texts" are certain short passages of text that are listed,
|
||
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
|
||
the Document is released under this License. A Front-Cover Text may
|
||
be at most 5 words, and a Back-Cover Text may be at most 25 words.
|
||
|
||
A "Transparent" copy of the Document means a machine-readable copy,
|
||
represented in a format whose specification is available to the
|
||
general public, that is suitable for revising the document
|
||
straightforwardly with generic text editors or (for images composed of
|
||
pixels) generic paint programs or (for drawings) some widely available
|
||
drawing editor, and that is suitable for input to text formatters or
|
||
for automatic translation to a variety of formats suitable for input
|
||
to text formatters. A copy made in an otherwise Transparent file
|
||
format whose markup, or absence of markup, has been arranged to thwart
|
||
or discourage subsequent modification by readers is not Transparent.
|
||
An image format is not Transparent if used for any substantial amount
|
||
of text. A copy that is not "Transparent" is called "Opaque".
|
||
|
||
Examples of suitable formats for Transparent copies include plain
|
||
ASCII without markup, Texinfo input format, LaTeX input format, SGML
|
||
or XML using a publicly available DTD, and standard-conforming simple
|
||
HTML, PostScript or PDF designed for human modification. Examples of
|
||
transparent image formats include PNG, XCF and JPG. Opaque formats
|
||
include proprietary formats that can be read and edited only by
|
||
proprietary word processors, SGML or XML for which the DTD and/or
|
||
processing tools are not generally available, and the
|
||
machine-generated HTML, PostScript or PDF produced by some word
|
||
processors for output purposes only.
|
||
|
||
The "Title Page" means, for a printed book, the title page itself,
|
||
plus such following pages as are needed to hold, legibly, the material
|
||
this License requires to appear in the title page. For works in
|
||
formats which do not have any title page as such, "Title Page" means
|
||
the text near the most prominent appearance of the work's title,
|
||
preceding the beginning of the body of the text.
|
||
|
||
The "publisher" means any person or entity that distributes copies of
|
||
the Document to the public.
|
||
|
||
A section "Entitled XYZ" means a named subunit of the Document whose
|
||
title either is precisely XYZ or contains XYZ in parentheses following
|
||
text that translates XYZ in another language. (Here XYZ stands for a
|
||
specific section name mentioned below, such as "Acknowledgements",
|
||
"Dedications", "Endorsements", or "History".) To "Preserve the Title"
|
||
of such a section when you modify the Document means that it remains a
|
||
section "Entitled XYZ" according to this definition.
|
||
|
||
The Document may include Warranty Disclaimers next to the notice which
|
||
states that this License applies to the Document. These Warranty
|
||
Disclaimers are considered to be included by reference in this
|
||
License, but only as regards disclaiming warranties: any other
|
||
implication that these Warranty Disclaimers may have is void and has
|
||
no effect on the meaning of this License.
|
||
|
||
2. VERBATIM COPYING
|
||
|
||
You may copy and distribute the Document in any medium, either
|
||
commercially or noncommercially, provided that this License, the
|
||
copyright notices, and the license notice saying this License applies
|
||
to the Document are reproduced in all copies, and that you add no
|
||
other conditions whatsoever to those of this License. You may not use
|
||
technical measures to obstruct or control the reading or further
|
||
copying of the copies you make or distribute. However, you may accept
|
||
compensation in exchange for copies. If you distribute a large enough
|
||
number of copies you must also follow the conditions in section 3.
|
||
|
||
You may also lend copies, under the same conditions stated above, and
|
||
you may publicly display copies.
|
||
|
||
|
||
3. COPYING IN QUANTITY
|
||
|
||
If you publish printed copies (or copies in media that commonly have
|
||
printed covers) of the Document, numbering more than 100, and the
|
||
Document's license notice requires Cover Texts, you must enclose the
|
||
copies in covers that carry, clearly and legibly, all these Cover
|
||
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
|
||
the back cover. Both covers must also clearly and legibly identify
|
||
you as the publisher of these copies. The front cover must present
|
||
the full title with all words of the title equally prominent and
|
||
visible. You may add other material on the covers in addition.
|
||
Copying with changes limited to the covers, as long as they preserve
|
||
the title of the Document and satisfy these conditions, can be treated
|
||
as verbatim copying in other respects.
|
||
|
||
If the required texts for either cover are too voluminous to fit
|
||
legibly, you should put the first ones listed (as many as fit
|
||
reasonably) on the actual cover, and continue the rest onto adjacent
|
||
pages.
|
||
|
||
If you publish or distribute Opaque copies of the Document numbering
|
||
more than 100, you must either include a machine-readable Transparent
|
||
copy along with each Opaque copy, or state in or with each Opaque copy
|
||
a computer-network location from which the general network-using
|
||
public has access to download using public-standard network protocols
|
||
a complete Transparent copy of the Document, free of added material.
|
||
If you use the latter option, you must take reasonably prudent steps,
|
||
when you begin distribution of Opaque copies in quantity, to ensure
|
||
that this Transparent copy will remain thus accessible at the stated
|
||
location until at least one year after the last time you distribute an
|
||
Opaque copy (directly or through your agents or retailers) of that
|
||
edition to the public.
|
||
|
||
It is requested, but not required, that you contact the authors of the
|
||
Document well before redistributing any large number of copies, to
|
||
give them a chance to provide you with an updated version of the
|
||
Document.
|
||
|
||
|
||
4. MODIFICATIONS
|
||
|
||
You may copy and distribute a Modified Version of the Document under
|
||
the conditions of sections 2 and 3 above, provided that you release
|
||
the Modified Version under precisely this License, with the Modified
|
||
Version filling the role of the Document, thus licensing distribution
|
||
and modification of the Modified Version to whoever possesses a copy
|
||
of it. In addition, you must do these things in the Modified Version:
|
||
|
||
A. Use in the Title Page (and on the covers, if any) a title distinct
|
||
from that of the Document, and from those of previous versions
|
||
(which should, if there were any, be listed in the History section
|
||
of the Document). You may use the same title as a previous version
|
||
if the original publisher of that version gives permission.
|
||
B. List on the Title Page, as authors, one or more persons or entities
|
||
responsible for authorship of the modifications in the Modified
|
||
Version, together with at least five of the principal authors of the
|
||
Document (all of its principal authors, if it has fewer than five),
|
||
unless they release you from this requirement.
|
||
C. State on the Title page the name of the publisher of the
|
||
Modified Version, as the publisher.
|
||
D. Preserve all the copyright notices of the Document.
|
||
E. Add an appropriate copyright notice for your modifications
|
||
adjacent to the other copyright notices.
|
||
F. Include, immediately after the copyright notices, a license notice
|
||
giving the public permission to use the Modified Version under the
|
||
terms of this License, in the form shown in the Addendum below.
|
||
G. Preserve in that license notice the full lists of Invariant Sections
|
||
and required Cover Texts given in the Document's license notice.
|
||
H. Include an unaltered copy of this License.
|
||
I. Preserve the section Entitled "History", Preserve its Title, and add
|
||
to it an item stating at least the title, year, new authors, and
|
||
publisher of the Modified Version as given on the Title Page. If
|
||
there is no section Entitled "History" in the Document, create one
|
||
stating the title, year, authors, and publisher of the Document as
|
||
given on its Title Page, then add an item describing the Modified
|
||
Version as stated in the previous sentence.
|
||
J. Preserve the network location, if any, given in the Document for
|
||
public access to a Transparent copy of the Document, and likewise
|
||
the network locations given in the Document for previous versions
|
||
it was based on. These may be placed in the "History" section.
|
||
You may omit a network location for a work that was published at
|
||
least four years before the Document itself, or if the original
|
||
publisher of the version it refers to gives permission.
|
||
K. For any section Entitled "Acknowledgements" or "Dedications",
|
||
Preserve the Title of the section, and preserve in the section all
|
||
the substance and tone of each of the contributor acknowledgements
|
||
and/or dedications given therein.
|
||
L. Preserve all the Invariant Sections of the Document,
|
||
unaltered in their text and in their titles. Section numbers
|
||
or the equivalent are not considered part of the section titles.
|
||
M. Delete any section Entitled "Endorsements". Such a section
|
||
may not be included in the Modified Version.
|
||
N. Do not retitle any existing section to be Entitled "Endorsements"
|
||
or to conflict in title with any Invariant Section.
|
||
O. Preserve any Warranty Disclaimers.
|
||
|
||
If the Modified Version includes new front-matter sections or
|
||
appendices that qualify as Secondary Sections and contain no material
|
||
copied from the Document, you may at your option designate some or all
|
||
of these sections as invariant. To do this, add their titles to the
|
||
list of Invariant Sections in the Modified Version's license notice.
|
||
These titles must be distinct from any other section titles.
|
||
|
||
You may add a section Entitled "Endorsements", provided it contains
|
||
nothing but endorsements of your Modified Version by various
|
||
parties--for example, statements of peer review or that the text has
|
||
been approved by an organization as the authoritative definition of a
|
||
standard.
|
||
|
||
You may add a passage of up to five words as a Front-Cover Text, and a
|
||
passage of up to 25 words as a Back-Cover Text, to the end of the list
|
||
of Cover Texts in the Modified Version. Only one passage of
|
||
Front-Cover Text and one of Back-Cover Text may be added by (or
|
||
through arrangements made by) any one entity. If the Document already
|
||
includes a cover text for the same cover, previously added by you or
|
||
by arrangement made by the same entity you are acting on behalf of,
|
||
you may not add another; but you may replace the old one, on explicit
|
||
permission from the previous publisher that added the old one.
|
||
|
||
The author(s) and publisher(s) of the Document do not by this License
|
||
give permission to use their names for publicity for or to assert or
|
||
imply endorsement of any Modified Version.
|
||
|
||
|
||
5. COMBINING DOCUMENTS
|
||
|
||
You may combine the Document with other documents released under this
|
||
License, under the terms defined in section 4 above for modified
|
||
versions, provided that you include in the combination all of the
|
||
Invariant Sections of all of the original documents, unmodified, and
|
||
list them all as Invariant Sections of your combined work in its
|
||
license notice, and that you preserve all their Warranty Disclaimers.
|
||
|
||
The combined work need only contain one copy of this License, and
|
||
multiple identical Invariant Sections may be replaced with a single
|
||
copy. If there are multiple Invariant Sections with the same name but
|
||
different contents, make the title of each such section unique by
|
||
adding at the end of it, in parentheses, the name of the original
|
||
author or publisher of that section if known, or else a unique number.
|
||
Make the same adjustment to the section titles in the list of
|
||
Invariant Sections in the license notice of the combined work.
|
||
|
||
In the combination, you must combine any sections Entitled "History"
|
||
in the various original documents, forming one section Entitled
|
||
"History"; likewise combine any sections Entitled "Acknowledgements",
|
||
and any sections Entitled "Dedications". You must delete all sections
|
||
Entitled "Endorsements".
|
||
|
||
|
||
6. COLLECTIONS OF DOCUMENTS
|
||
|
||
You may make a collection consisting of the Document and other
|
||
documents released under this License, and replace the individual
|
||
copies of this License in the various documents with a single copy
|
||
that is included in the collection, provided that you follow the rules
|
||
of this License for verbatim copying of each of the documents in all
|
||
other respects.
|
||
|
||
You may extract a single document from such a collection, and
|
||
distribute it individually under this License, provided you insert a
|
||
copy of this License into the extracted document, and follow this
|
||
License in all other respects regarding verbatim copying of that
|
||
document.
|
||
|
||
|
||
7. AGGREGATION WITH INDEPENDENT WORKS
|
||
|
||
A compilation of the Document or its derivatives with other separate
|
||
and independent documents or works, in or on a volume of a storage or
|
||
distribution medium, is called an "aggregate" if the copyright
|
||
resulting from the compilation is not used to limit the legal rights
|
||
of the compilation's users beyond what the individual works permit.
|
||
When the Document is included in an aggregate, this License does not
|
||
apply to the other works in the aggregate which are not themselves
|
||
derivative works of the Document.
|
||
|
||
If the Cover Text requirement of section 3 is applicable to these
|
||
copies of the Document, then if the Document is less than one half of
|
||
the entire aggregate, the Document's Cover Texts may be placed on
|
||
covers that bracket the Document within the aggregate, or the
|
||
electronic equivalent of covers if the Document is in electronic form.
|
||
Otherwise they must appear on printed covers that bracket the whole
|
||
aggregate.
|
||
|
||
|
||
8. TRANSLATION
|
||
|
||
Translation is considered a kind of modification, so you may
|
||
distribute translations of the Document under the terms of section 4.
|
||
Replacing Invariant Sections with translations requires special
|
||
permission from their copyright holders, but you may include
|
||
translations of some or all Invariant Sections in addition to the
|
||
original versions of these Invariant Sections. You may include a
|
||
translation of this License, and all the license notices in the
|
||
Document, and any Warranty Disclaimers, provided that you also include
|
||
the original English version of this License and the original versions
|
||
of those notices and disclaimers. In case of a disagreement between
|
||
the translation and the original version of this License or a notice
|
||
or disclaimer, the original version will prevail.
|
||
|
||
If a section in the Document is Entitled "Acknowledgements",
|
||
"Dedications", or "History", the requirement (section 4) to Preserve
|
||
its Title (section 1) will typically require changing the actual
|
||
title.
|
||
|
||
|
||
9. TERMINATION
|
||
|
||
You may not copy, modify, sublicense, or distribute the Document
|
||
except as expressly provided under this License. Any attempt
|
||
otherwise to copy, modify, sublicense, or distribute it is void, and
|
||
will automatically terminate your rights under this License.
|
||
|
||
However, if you cease all violation of this License, then your license
|
||
from a particular copyright holder is reinstated (a) provisionally,
|
||
unless and until the copyright holder explicitly and finally
|
||
terminates your license, and (b) permanently, if the copyright holder
|
||
fails to notify you of the violation by some reasonable means prior to
|
||
60 days after the cessation.
|
||
|
||
Moreover, your license from a particular copyright holder is
|
||
reinstated permanently if the copyright holder notifies you of the
|
||
violation by some reasonable means, this is the first time you have
|
||
received notice of violation of this License (for any work) from that
|
||
copyright holder, and you cure the violation prior to 30 days after
|
||
your receipt of the notice.
|
||
|
||
Termination of your rights under this section does not terminate the
|
||
licenses of parties who have received copies or rights from you under
|
||
this License. If your rights have been terminated and not permanently
|
||
reinstated, receipt of a copy of some or all of the same material does
|
||
not give you any rights to use it.
|
||
|
||
|
||
10. FUTURE REVISIONS OF THIS LICENSE
|
||
|
||
The Free Software Foundation may publish new, revised versions of the
|
||
GNU Free Documentation License from time to time. Such new versions
|
||
will be similar in spirit to the present version, but may differ in
|
||
detail to address new problems or concerns. See
|
||
https://www.gnu.org/licenses/.
|
||
|
||
Each version of the License is given a distinguishing version number.
|
||
If the Document specifies that a particular numbered version of this
|
||
License "or any later version" applies to it, you have the option of
|
||
following the terms and conditions either of that specified version or
|
||
of any later version that has been published (not as a draft) by the
|
||
Free Software Foundation. If the Document does not specify a version
|
||
number of this License, you may choose any version ever published (not
|
||
as a draft) by the Free Software Foundation. If the Document
|
||
specifies that a proxy can decide which future versions of this
|
||
License can be used, that proxy's public statement of acceptance of a
|
||
version permanently authorizes you to choose that version for the
|
||
Document.
|
||
|
||
11. RELICENSING
|
||
|
||
"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
|
||
World Wide Web server that publishes copyrightable works and also
|
||
provides prominent facilities for anybody to edit those works. A
|
||
public wiki that anybody can edit is an example of such a server. A
|
||
"Massive Multiauthor Collaboration" (or "MMC") contained in the site
|
||
means any set of copyrightable works thus published on the MMC site.
|
||
|
||
"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
|
||
license published by Creative Commons Corporation, a not-for-profit
|
||
corporation with a principal place of business in San Francisco,
|
||
California, as well as future copyleft versions of that license
|
||
published by that same organization.
|
||
|
||
"Incorporate" means to publish or republish a Document, in whole or in
|
||
part, as part of another Document.
|
||
|
||
An MMC is "eligible for relicensing" if it is licensed under this
|
||
License, and if all works that were first published under this License
|
||
somewhere other than this MMC, and subsequently incorporated in whole or
|
||
in part into the MMC, (1) had no cover texts or invariant sections, and
|
||
(2) were thus incorporated prior to November 1, 2008.
|
||
|
||
The operator of an MMC Site may republish an MMC contained in the site
|
||
under CC-BY-SA on the same site at any time before August 1, 2009,
|
||
provided the MMC is eligible for relicensing.
|
||
|
||
|
||
ADDENDUM: How to use this License for your documents
|
||
|
||
To use this License in a document you have written, include a copy of
|
||
the License in the document and put the following copyright and
|
||
license notices just after the title page:
|
||
|
||
Copyright (c) YEAR YOUR NAME.
|
||
Permission is granted to copy, distribute and/or modify this document
|
||
under the terms of the GNU Free Documentation License, Version 1.3
|
||
or any later version published by the Free Software Foundation;
|
||
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
|
||
A copy of the license is included in the section entitled "GNU
|
||
Free Documentation License".
|
||
|
||
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
|
||
replace the "with...Texts." line with this:
|
||
|
||
with the Invariant Sections being LIST THEIR TITLES, with the
|
||
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
|
||
|
||
If you have Invariant Sections without Cover Texts, or some other
|
||
combination of the three, merge those two alternatives to suit the
|
||
situation.
|
||
|
||
If your document contains nontrivial examples of program code, we
|
||
recommend releasing these examples in parallel under your choice of
|
||
free software license, such as the GNU General Public License,
|
||
to permit their use in free software.
|
||
#+end_export
|
||
|
||
#+html: <!--
|
||
|
||
* Indices
|
||
:properties:
|
||
:custom_id: h:55104b26-8e94-46cf-9975-43ea00316489
|
||
:end:
|
||
|
||
** Function index
|
||
:properties:
|
||
:index: fn
|
||
:custom_id: h:6bec5005-529c-4521-ae05-3d990baffb5b
|
||
:end:
|
||
|
||
** Variable index
|
||
:properties:
|
||
:index: vr
|
||
:custom_id: h:16ad8df6-b015-40a9-9259-03d4f7a23ee4
|
||
:end:
|
||
|
||
** Concept index
|
||
:properties:
|
||
:index: cp
|
||
:custom_id: h:6aa7a656-884b-4c39-b759-087e412eec13
|
||
:end:
|
||
|
||
#+html: -->
|