diff options
Diffstat (limited to 'doc/misc/modus-themes.texi')
| -rw-r--r-- | doc/misc/modus-themes.texi | 2834 |
1 files changed, 0 insertions, 2834 deletions
diff --git a/doc/misc/modus-themes.texi b/doc/misc/modus-themes.texi deleted file mode 100644 index b16aece2ee5..00000000000 --- a/doc/misc/modus-themes.texi +++ /dev/null @@ -1,2834 +0,0 @@ -\input texinfo @c -*- texinfo -*- -@c %**start of header -@setfilename ../../info/modus-themes.info -@settitle Modus themes for GNU Emacs -@include docstyle.texi -@documentencoding UTF-8 -@documentlanguage en -@c %**end of header - -@include emacsver.texi - -@dircategory Emacs misc features -@direntry -* Modus Themes: (modus-themes). Highly accessible themes (WCAG AAA). -@end direntry - -@finalout -@titlepage -@title Modus themes for GNU Emacs -@author Protesilaos Stavrou (@email{info@@protesilaos.com}) -@end titlepage - -@ifnottex -@node Top -@top Modus themes for GNU Emacs - -This manual, written by Protesilaos Stavrou, describes the customization -options for the @samp{modus-operandi} and @samp{modus-vivendi} themes, and provides -every other piece of information pertinent to them. - -The documentation furnished herein corresponds to version 0.13.0, -released on 2020-10-08. Any reference to a newer feature which does -not yet form part of the latest tagged commit, is explicitly marked as -such. - -Copyright (C) 2020--2021 Free Software Foundation, Inc. - -@quotation -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 quotation - -@end ifnottex - -@menu -* Overview:: -* Installation:: -* Enable and load:: -* Customization Options:: -* Advanced customization (do-it-yourself):: -* Face coverage:: -* Notes for individual packages:: -* Contributing:: -* Acknowledgements:: -* Meta:: -* External projects (ports):: -* GNU Free Documentation License:: - -@detailmenu ---- The Detailed Node Listing --- - -Overview - -* How do the themes look like:: -* Learn about the latest changes:: - -Installation - -* Install from the archives:: -* Install on GNU/Linux:: - -Install on GNU/Linux - -* Debian 11 Bullseye:: -* GNU Guix:: - -Enable and load - -* Load automatically:: -* Load at a given time or at sunset/sunrise:: -* Toggle between the themes on demand:: -* Configure options prior to loading:: - -Customization Options - -* Bold constructs:: Toggle bold constructs in code -* Slanted constructs:: Toggle slanted constructs (italics) in code -* Syntax highlighting:: Toggle subtle coloration in programming modes -* No mixed fonts:: Toggle mixing of font families -* Link underline:: Toggle underlined text in links -* Command prompts:: Choose among plain, subtle, or intense prompts -* Mode line:: Choose among plain, three-dimension, or moody-compliant styles -* Completion UIs:: Choose among standard, moderate, or opinionated looks -* Fringes:: Choose among plain, subtle, or intense fringe visibility -* Line highlighting:: Toggle intense style for current line highlighting -* Matching parentheses:: Toggle intense style for matching delimiters/parentheses -* Diffs:: Choose among intense, desaturated, or text-only diffs -* Org mode blocks:: Choose among plain, greyscale, or rainbow styles -* Heading styles:: Choose among several styles, also per heading level -* Scaled headings:: Toggle scaling of headings -* Headings' font:: Toggle proportionately spaced fonts in headings - -Scaled headings - -* Scaled heading sizes:: Specify rate of increase for scaled headings - -Advanced customization (do-it-yourself) - -* Tweak colors (DIY):: Declare your own palette overrides -* Font configs (DIY):: Optimise for mixed typeface buffers -* Org user faces (DIY):: Extend styles for org-mode keywords and priorities - -Face coverage - -* Supported packages:: Full list of covered face groups -* Covered indirectly:: -* Will NOT be supported:: - -Notes for individual packages - -* Note on company-mode overlay pop-up:: -* Note for ERC escaped color sequences:: -* Note for powerline or spaceline:: -* Note on shr colors:: -* Note for Helm grep:: -* Note on vc-annotate-background-mode:: - -Contributing - -* Sources of the themes:: -* Issues you can help with:: -* Merge requests:: Legal considerations for code patches - -@end detailmenu -@end menu - -@node Overview -@chapter Overview - -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 (@samp{modus-operandi}) is a light theme, while Modus Vivendi -(@samp{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 -(see @ref{Face coverage}). - -Starting with version 0.12.0 and onwards, the themes are built into GNU -Emacs (current version is 0.13.0). - -@menu -* How do the themes look like:: -* Learn about the latest changes:: -@end menu - -@node How do the themes look like -@section How do the themes look like - -Check the web page with @uref{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. - -@xref{Customization Options}. - -@node Learn about the latest changes -@section Learn about the latest changes - -Please refer to the @uref{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. - -@node Installation -@chapter Installation - -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. - -Modus Operandi (light theme) and Modus Vivendi (dark) are normally -distributed as standalone packages in Emacs-specific archives. There -also exist packages for GNU/Linux distributions. - -@menu -* Install from the archives:: -* Install on GNU/Linux:: -@end menu - -@node Install from the archives -@section Install from the archives - -@samp{modus-operandi-theme} and @samp{modus-vivendi-theme} are -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 @samp{M-x package-refresh-contents}. Then all you need to do is -type @samp{M-x package-install} and specify the theme of your choice. - -@node Install on GNU/Linux -@section Install on GNU/Linux - -The themes are also available from the archives of some GNU/Linux -distributions. 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. - -@menu -* Debian 11 Bullseye:: -* GNU Guix:: -@end menu - -@node Debian 11 Bullseye -@subsection Debian 11 Bullseye - -The two themes are distributed as a single package for Debian and its -derivatives. Currently in the unstable and testing suites and should be -available in time for Debian 11 Bullseye (next stable). - -Get them with: - -@example -sudo apt install elpa-modus-themes -@end example - -@node GNU Guix -@subsection GNU Guix - -Users of either the Guix System (the distro) or just Guix (the package -manager) can get each theme as a standalone package. - -@example -guix package -i emacs-modus-operandi-theme -@end example - -And/or: - -@example -guix package -i emacs-modus-vivendi-theme -@end example - -@node Enable and load -@chapter Enable and load - -This section documents how to load the theme of your choice and how to -further control its initialization. It also includes some sample code -snippets that could help you in the task, especially if you intend to -use both Modus Operandi and Modus Vivendi. - -@menu -* Load automatically:: -* Load at a given time or at sunset/sunrise:: -* Toggle between the themes on demand:: -* Configure options prior to loading:: -@end menu - -@node Load automatically -@section Load automatically - -A simple way to load the theme from your Emacs initialization file is to -include either of the following expressions: - -@lisp -(load-theme 'modus-operandi t) ; Light theme -(load-theme 'modus-vivendi t) ; Dark theme -@end lisp - -Make sure to remove any other theme that is being loaded, otherwise you -might run into unexpected issues. - -Note that you can always @samp{M-x disable-theme} and specify an item. The -command does exactly what its name suggests. To deactivate all enabled -themes at once, in case you have multiple of them enabled, you may -evaluate the expression: - -@lisp -(mapc #'disable-theme custom-enabled-themes) -@end lisp - -@node Load at a given time or at sunset/sunrise -@section Load at a given time or at sunset/sunrise - -It is possible to schedule a time during the day at or after which a -given theme will be loaded.@footnote{Contributed on Reddit by user @samp{b3n} -@uref{https://www.reddit.com/r/emacs/comments/gdtqov/weekly_tipstricketc_thread/fq9186h/}.} - -@lisp -;; Light for the day -(load-theme 'modus-operandi t t) -(run-at-time "05:00" (* 60 60 24) - (lambda () - (enable-theme 'modus-operandi))) - -;; Dark for the night -(load-theme 'modus-vivendi t t) -(run-at-time "21:00" (* 60 60 24) - (lambda () - (enable-theme 'modus-vivendi))) -@end lisp - -A modified version of the above technique is to use the sunrise and -sunset as references, instead of specifying a fixed hour value.@footnote{Contributed directly by André Alexandre Gomes @uref{https://gitlab.com/aadcg}.} -If you set @samp{calendar-latitude} and @samp{calendar-longitude} (defined in the -built-in @samp{solar.el} library---read it with @samp{M-x find-library}), you can -automatically switch between both themes at the appropriate time-of-day. -Note that @emph{those calendar variables need to be set before loading the -themes}. - -@lisp -;; Define coordinates -(setq calendar-latitude 35.17 - calendar-longitude 33.36) - -;; Light at sunrise -(load-theme 'modus-operandi t t) -(run-at-time (nth 1 (split-string (sunrise-sunset))) - (* 60 60 24) - (lambda () - (enable-theme 'modus-operandi))) - -;; Dark at sunset -(load-theme 'modus-vivendi t t) -(run-at-time (nth 4 (split-string (sunrise-sunset))) - (* 60 60 24) - (lambda () - (enable-theme 'modus-vivendi))) -@end lisp - -For the sake of completeness, the @samp{load-theme} call in these snippets is -slightly different than the one shown in @ref{Load automatically}, because it -does not enable the theme directly: the subsequent @samp{enable-theme} does -that when needed. - -@node Toggle between the themes on demand -@section Toggle between the themes on demand - -With both themes available, it is possible to design a simple command to -switch between them on demand. - -@lisp -(defun modus-themes-toggle () - "Toggle between `modus-operandi' and `modus-vivendi' themes." - (interactive) - (if (eq (car custom-enabled-themes) 'modus-operandi) - (progn - (disable-theme 'modus-operandi) - (load-theme 'modus-vivendi t)) - (disable-theme 'modus-vivendi) - (load-theme 'modus-operandi t))) -@end lisp - -You could use @samp{(mapc #'disable-theme custom-enabled-themes)} instead of -disabling a single target, but you get the idea. - -@node Configure options prior to loading -@section Configure options prior to loading - -If you plan to use both themes and wish to apply styles consistently -(see @ref{Customization Options}), you could define wrapper functions around -the standard @samp{load-theme} command. These extend the simple function we -presented in @ref{Toggle between the themes on demand}. - -Here is a comprehensive setup (the values assigned to the variables are -just for the sake of this demonstration):@footnote{The @samp{defmacro} and @samp{dolist} -method were contributed on Reddit by user @samp{b3n}, -@uref{https://www.reddit.com/r/emacs/comments/gqsz8u/weekly_tipstricketc_thread/fsfakhg/}.} - -@lisp -(defmacro modus-themes-format-sexp (sexp &rest objects) - `(eval (read (format ,(format "%S" sexp) ,@@objects)))) - -(dolist (theme '("operandi" "vivendi")) - (modus-themes-format-sexp - (defun modus-%1$s-theme-load () - (setq modus-%1$s-theme-slanted-constructs t - modus-%1$s-theme-bold-constructs t - modus-%1$s-theme-fringes 'subtle ; @{nil,'subtle,'intense@} - modus-%1$s-theme-mode-line '3d ; @{nil,'3d,'moody@} - modus-%1$s-theme-faint-syntax nil - modus-%1$s-theme-intense-hl-line nil - modus-%1$s-theme-intense-paren-match nil - modus-%1$s-theme-no-link-underline t - modus-%1$s-theme-no-mixed-fonts nil - modus-%1$s-theme-prompts nil ; @{nil,'subtle,'intense@} - modus-%1$s-theme-completions 'moderate ; @{nil,'moderate,'opinionated@} - modus-%1$s-theme-diffs nil ; @{nil,'desaturated,'fg-only@} - modus-%1$s-theme-org-blocks 'greyscale ; @{nil,'greyscale,'rainbow@} - modus-%1$s-theme-headings ; Read further below in the manual for this one - '((1 . section) - (2 . line) - (t . rainbow-line-no-bold)) - modus-%1$s-theme-variable-pitch-headings nil - modus-%1$s-theme-scale-headings t - modus-%1$s-theme-scale-1 1.1 - modus-%1$s-theme-scale-2 1.15 - modus-%1$s-theme-scale-3 1.21 - modus-%1$s-theme-scale-4 1.27 - modus-%1$s-theme-scale-5 1.33) - (load-theme 'modus-%1$s t)) - theme)) - -(defun modus-themes-toggle () - "Toggle between `modus-operandi' and `modus-vivendi' themes." - (interactive) - (if (eq (car custom-enabled-themes) 'modus-operandi) - (progn - (disable-theme 'modus-operandi) - (modus-vivendi-theme-load)) - (disable-theme 'modus-vivendi) - (modus-operandi-theme-load))) -@end lisp - -@node Customization Options -@chapter Customization Options - -The Modus themes are highly configurable, though they should work well -without any further tweaks. - -By default, all customization options are set to @samp{nil}. - -All customization options need to be evaluated before loading their -theme (@pxref{Enable and load}). - -@menu -* Bold constructs:: Toggle bold constructs in code -* Slanted constructs:: Toggle slanted constructs (italics) in code -* Syntax highlighting:: Toggle subtle coloration in programming modes -* No mixed fonts:: Toggle mixing of font families -* Link underline:: Toggle underlined text in links -* Command prompts:: Choose among plain, subtle, or intense prompts -* Mode line:: Choose among plain, three-dimension, or moody-compliant styles -* Completion UIs:: Choose among standard, moderate, or opinionated looks -* Fringes:: Choose among plain, subtle, or intense fringe visibility -* Line highlighting:: Toggle intense style for current line highlighting -* Matching parentheses:: Toggle intense style for matching delimiters/parentheses -* Diffs:: Choose among intense, desaturated, or text-only diffs -* Org mode blocks:: Choose among plain, greyscale, or rainbow styles -* Heading styles:: Choose among several styles, also per heading level -* Scaled headings:: Toggle scaling of headings -* Headings' font:: Toggle proportionately spaced fonts in headings -@end menu - -@node Bold constructs -@section Option for more bold constructs - -Symbol names: - -@itemize -@item -@samp{modus-operandi-theme-bold-constructs} -@item -@samp{modus-vivendi-theme-bold-constructs} -@end itemize - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{t} -@end enumerate - -Display several 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. - -The default is to only use a bold weight when it is required. - -Additionally, and while not necessary, to define the precise weight for -bold constructs, you can change the typographic intensity of the @samp{bold} -face. The standard is a bold weight. It requires no further -intervention. Assuming though that your typeface of choice supports a -``semibold'' weight, adding the following snippet to your init file should -suffice. - -@lisp -(set-face-attribute 'bold nil :weight 'semibold) -@end lisp - -Note that if you are switching themes, you need to re-evaluate this -expression after the new theme is loaded. - -@node Slanted constructs -@section Option for more slanted constructs - -Symbol names: - -@itemize -@item -@samp{modus-operandi-theme-slanted-constructs} -@item -@samp{modus-vivendi-theme-slanted-constructs} -@end itemize - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{t} -@end enumerate - -Choose to render more faces in slanted text (italics). This typically -affects documentation strings and code comments. - -The default is to not use italics unless it is absolutely necessary. - -@node Syntax highlighting -@section Option for faint code syntax highlighting - -Symbol names: - -@itemize -@item -@samp{modus-operandi-theme-faint-syntax} -@item -@samp{modus-vivendi-theme-faint-syntax} -@end itemize - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{t} -@end enumerate - -Use less saturated colors in programming modes for highlighting code -syntax. The default is to use saturated colors. - -This option essentially affects the font-lock faces, so it may also have -implications in other places that are hard-wired to rely directly on -them instead of specifying their own faces (which could inherit from -font-lock if that is the intent). The author is aware of @samp{vc-dir} as a -case in point. - -@node No mixed fonts -@section Option for no font mixing - -Symbol names: - -@itemize -@item -@samp{modus-operandi-theme-no-mixed-fonts} -@item -@samp{modus-vivendi-theme-no-mixed-fonts} -@end itemize - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{t} -@end enumerate - -By default, the themes configure some spacing-sensitive faces, such as -Org tables and code blocks, to always inherit from the @samp{fixed-pitch} face. -This is to ensure that those constructs remain monospaced when users opt -for something like the built-in @kbd{M-x variable-pitch-mode}. Otherwise the -layout would appear broken. To disable this behaviour, set the option -to @samp{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 @samp{org-variable-pitch} and @samp{mixed-pitch}. - -@node Link underline -@section Option for no link underline - -Symbol names: - -@itemize -@item -@samp{modus-operandi-theme-no-link-underline} -@item -@samp{modus-vivendi-theme-no-link-underline} -@end itemize - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{t} -@end enumerate - -Remove the underline effect from links, symbolic links, and buttons. -The default is to apply an underline. - -@node Command prompts -@section Option for command prompt styles - -Symbol names: - -@itemize -@item -@samp{modus-operandi-theme-prompts} -@item -@samp{modus-vivendi-theme-prompts} -@end itemize - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{subtle} -@item -@samp{intense} -@end enumerate - -The symbols ``subtle'' and ``intense'' will apply a combination of accented -background and foreground to the minibuffer and other REPL prompts (like -@samp{M-x shell} and @samp{M-x eshell}). The difference between the two is that the -latter has a more pronounced/noticeable effect than the former. - -The default does not use any background for such prompts, while relying -exclusively on an accented foreground color. - -@node Mode line -@section Option for mode line presentation - -Symbol names: - -@itemize -@item -@samp{modus-operandi-theme-mode-line} -@item -@samp{modus-vivendi-theme-mode-line} -@end itemize - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{3d} -@item -@samp{moody} -@end enumerate - -The default value (@samp{nil}) produces a two-dimensional effect both for the -active and inactive modelines. The differences between the two are -limited to distinct shades of greyscale values, with the active being -more intense than the inactive. - -A @samp{3d} symbol 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 the same as what you -get when you run Emacs without any customizations (@kbd{emacs -Q} on the -command line). - -While @samp{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 -@uref{https://github.com/tarsius/moody, moody package} (hereinafter referred to as ``Moody''), though it can work -fine even without it. - -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 @samp{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 @samp{set-face-attribute}, specifically @samp{:distant-foreground}). This fallback -comes into effect 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 @samp{face-near-same-color-threshold} to trigger the fallback color. -We find that a value of @samp{45000} would suffice, contrary to the default -@samp{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 recommended you also include this in your setup: - -@lisp -(setq x-underline-at-descent-line t) -@end lisp - -@node Completion UIs -@section Option for completion framework aesthetics - -Symbol names: - -@itemize -@item -@samp{modus-operandi-theme-completions} -@item -@samp{modus-vivendi-theme-completions} -@end itemize - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{moderate} -@item -@samp{opinionated} -@end enumerate - -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 @samp{nil} will respect the metaphors of each completion framework. - -The symbol @samp{moderate} will apply 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 et al will appear slightly different -than their original looks, as they are toned down a bit. - -The symbol @samp{opinionated} will apply 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 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 @samp{nil} (default), @samp{moderate}, and @samp{opinionated} -possibilities. - -@node Fringes -@section Option for fringe visibility - -Symbol names: - -@itemize -@item -@samp{modus-operandi-theme-fringes} -@item -@samp{modus-vivendi-theme-fringes} -@end itemize - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{subtle} -@item -@samp{intense} -@end enumerate - -The ``subtle'' symbol will apply a greyscale background that is visible, -yet close enough to the main background color. While the ``intense'' -symbol will use a more noticeable greyscale background. - -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 @samp{fringe-mode}. - -@node Line highlighting -@section Option for line highlighting (hl-line-mode) - -Symbol names: - -@itemize -@item -@samp{modus-operandi-theme-intense-hl-line} -@item -@samp{modus-vivendi-theme-intense-hl-line} -@end itemize - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{t} -@end enumerate - -Draw the current line of @samp{hl-line-mode} or its global equivalent in a more -prominent background color. This would also affect several packages -that enable @samp{hl-line-mode}, such as @samp{elfeed} and @samp{mu4e}. - -The default is to use a more subtle gray. - -@node Matching parentheses -@section Option for parenthesis matching (show-paren-mode) - -Symbol names: - -@itemize -@item -@samp{modus-operandi-theme-intense-paren-match} -@item -@samp{modus-vivendi-theme-intense-paren-match} -@end itemize - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{t} -@end enumerate - -Apply a more intense background to the matching parentheses (or -delimiters). This affects tools such as the built-in @samp{show-paren-mode}. -The default is to use a subtle warm color for the background of those -overlays. - -@node Diffs -@section Option for diff buffer looks - -Symbol names: - -@itemize -@item -@samp{modus-operandi-theme-diffs} -@item -@samp{modus-vivendi-theme-diffs} -@end itemize - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{desaturated} -@item -@samp{fg-only} -@end enumerate - -By default the themes will apply richly colored backgrounds to the -output of diffs, such as those of @samp{diff-mode}, @samp{ediff}, @samp{smerge-mode}, and -@samp{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. - -A @samp{desaturated} value tones down all relevant color values. It still -combines an accented background with an appropriate foreground, yet its -overall impression is very subtle. Refined changes are a bit more -intense to fulfil their intended function, though still less saturated -than default. - -While @samp{fg-only} will remove all accented backgrounds and instead rely on -color-coded text to denote changes. For instance, added lines use an -intense 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. - -Concerning @samp{magit}, an extra set of tweaks are introduced for the effect -of highlighting the current diff hunk, so as to remain consistent with -the overall experience of that mode. Expect changes that are consistent -with the overall intent of the aforementioned. - -@node Org mode blocks -@section Option for org-mode block styles - -Symbol names: - -@itemize -@item -@samp{modus-operandi-theme-org-blocks} -@item -@samp{modus-vivendi-theme-org-blocks} -@end itemize - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{greyscale} -@item -@samp{rainbow} -@end enumerate - -The default is to use the same background as the rest of the buffer for -the contents of the block. - -A value of @samp{greyscale} will apply 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 recognised by -@samp{set-face-attribute}). - -While @samp{rainbow} will instead use an accented background for the contents -of the block. The exact color will depend on the programming language -and is controlled by the @samp{org-src-block-faces} variable (refer to the -theme's source code for the current association list). 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 properly: 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). - -@node Heading styles -@section Option for headings' overall style - -This is defined as an alist and, therefore, uses a different approach -than other customization options documented in this manual. - -Symbol names: - -@itemize -@item -@samp{modus-operandi-theme-headings} -@item -@samp{modus-vivendi-theme-headings} -@end itemize - -Possible values, which can be specified for each heading level (examples -further below): - -@itemize -@item -nil (default fallback option---covers all heading levels) -@item -@samp{t} (default style for a single heading, when the fallback differs) -@item -@samp{no-bold} -@item -@samp{line} -@item -@samp{line-no-bold} -@item -@samp{rainbow} -@item -@samp{rainbow-line} -@item -@samp{rainbow-line-no-bold} -@item -@samp{highlight} -@item -@samp{highlight-no-bold} -@item -@samp{rainbow-highlight} -@item -@samp{rainbow-highlight-no-bold} -@item -@samp{section} -@item -@samp{section-no-bold} -@item -@samp{rainbow-section} -@item -@samp{rainbow-section-no-bold} -@end itemize - -To control faces per level from 1-8, use something like this (same for -@samp{modus-vivendi-theme-headings}): - -@lisp -(setq modus-operandi-theme-headings - '((1 . section) - (2 . line) - (3 . highlight) - (t . rainbow-no-bold))) -@end lisp - -The above uses the @samp{section} value for heading levels 1, the @samp{line} for -headings 2, @samp{highlight} for 3. All other levels fall back to -@samp{rainbow-line-no-bold}. - -To set a uniform value for all heading levels, use this pattern: - -@lisp -;; A given style for every heading -(setq modus-operandi-theme-headings - '((t . rainbow-line-no-bold))) - -;; Default aesthetic for every heading -(setq modus-operandi-theme-headings - '((t . nil))) -@end lisp - -The default style for headings uses a fairly desaturated foreground -value in combination with a bold typographic weight. To specify this -style for a given level N (assuming you wish to have another fallback -option), just specify the value @samp{t} like this: - -@lisp -(setq modus-operandi-theme-headings - '((1 . t) - (2 . line) - (t . rainbow-line-no-bold))) -@end lisp - -A description of all other possible styles: - -@itemize -@item -@samp{no-bold} retains the default text color while removing the typographic -weight. - -@item -@samp{line} is the same as the default plus an overline over the heading. - -@item -@samp{line-no-bold} is the same as @samp{line} without bold weight. - -@item -@samp{rainbow} uses a more colorful foreground in combination with bold -weight. - -@item -@samp{rainbow-line} is the same as @samp{rainbow} plus an overline. - -@item -@samp{rainbow-line-no-bold} is the same as @samp{rainbow-line} without the bold -weight. - -@item -@samp{highlight} retains the default style of a fairly desaturated foreground -combined with a bold weight and adds to it a subtle accented -background. - -@item -@samp{highlight-no-bold} is the same as @samp{highlight} without a bold weight. - -@item -@samp{rainbow-highlight} is the same as @samp{highlight} but with a more colorful -foreground. - -@item -@samp{rainbow-highlight-no-bold} is the same as @samp{rainbow-highlight} without a -bold weight. - -@item -@samp{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 @samp{line} and @samp{highlight} values. - -@item -@samp{section-no-bold} is the same as @samp{section} without a bold weight. - -@item -@samp{rainbow-section} is the same as @samp{section} but with a more colorful -foreground. - -@item -@samp{rainbow-section-no-bold} is the same as @samp{rainbow-section} without a bold -weight.`` -@end itemize - -@node Scaled headings -@section Option for scaled headings - -Symbol names: - -@itemize -@item -@samp{modus-operandi-theme-scale-headings} -@item -@samp{modus-vivendi-theme-scale-headings} -@end itemize - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{t} -@end enumerate - -Make headings larger in height relative to the main text. This is -noticeable in modes like Org. The default is to use the same size for -headings and body copy. - -@menu -* Scaled heading sizes:: Specify rate of increase for scaled headings -@end menu - -@node Scaled heading sizes -@subsection Control the scale of headings - -In addition to toggles for enabling scaled headings, users can also -specify a number of their own. - -@itemize -@item -If it is a floating point, say, @samp{1.5}, it is interpreted as a multiple -of the base font size. This is the recommended method. - -@item -If it is an integer, it is read as an absolute font height. The -number is basically the point size multiplied by ten. So if you want -it to be @samp{18pt} you must pass @samp{180}. Please understand that setting an -absolute value is discouraged, as it will break the layout when you -try to change font sizes with the built-in @samp{text-scale-adjust} command -(see @ref{Font configs (DIY), , Font configurations}). -@end itemize - -Below are the variables in their default values, using the floating -point paradigm. The numbers are very conservative, but you are free to -change them to your liking, such as @samp{1.2}, @samp{1.4}, @samp{1.6}, @samp{1.8}, @samp{2.0}---or use a -resource for finding a consistent scale: - -@lisp -(setq modus-operandi-theme-scale-1 1.05 - modus-operandi-theme-scale-2 1.1 - modus-operandi-theme-scale-3 1.15 - modus-operandi-theme-scale-4 1.2 - modus-operandi-theme-scale-5 1.3) - -(setq modus-vivendi-theme-scale-1 1.05 - modus-vivendi-theme-scale-2 1.1 - modus-vivendi-theme-scale-3 1.15 - modus-vivendi-theme-scale-4 1.2 - modus-vivendi-theme-scale-5 1.3) -@end lisp - -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: -@uref{https://protesilaos.com/codelog/2020-09-24-org-headings-adapt/}. - -@node Headings' font -@section Option for variable-pitch font in headings - -Symbol names: - -@itemize -@item -@samp{modus-operandi-theme-variable-pitch-headings} -@item -@samp{modus-vivendi-theme-variable-pitch-headings} -@end itemize - -Possible values: - -@enumerate -@item -@samp{nil} (default) -@item -@samp{t} -@end enumerate - -Choose to apply a proportionately spaced, else ``variable-pitch'', -typeface to headings (such as in Org mode). The default is to use the -main font family. - -@ref{Font configs (DIY), , Font configurations for Org (and others)}. - -@node Advanced customization (do-it-yourself) -@chapter Advanced customization (do-it-yourself) - -Unlike the predefined customization options which follow a -straightforward 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 (see @ref{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''. - -@menu -* Tweak colors (DIY):: Declare your own palette overrides -* Font configs (DIY):: Optimise for mixed typeface buffers -* Org user faces (DIY):: Extend styles for org-mode keywords and priorities -@end menu - -@node Tweak colors (DIY) -@section Full access to the themes' palette - -The variables are: - -@itemize -@item -@samp{modus-operandi-theme-override-colors-alist} -@item -@samp{modus-vivendi-theme-override-colors-alist} -@end itemize - -Users can specify an association list that maps the names of color -variables to hexadecimal RGB values (in the form of @samp{#RRGGBB}). This -means that it is possible to override the entire palette or subsets -thereof (see the source code for the actual names and values). - -Example: - -@lisp -;; Redefine the values of those three variables for the given theme -(setq modus-vivendi-theme-override-colors-alist - '(("magenta" . "#ffaabb") - ("magenta-alt" . "#ee88ff") - ("magenta-alt-other" . "#bbaaff"))) -@end lisp - -If you want to be creative, you can define a minor mode that refashions -the themes on demand. The following is a minor mode that gets activated -on demand. We combine it with the function to switch between Modus -Operandi and Modus Vivendi (@pxref{Toggle between the themes on demand}, for -a basic command, and/or @pxref{Configure options prior to loading}, for a more -comprehensive setup). - -@lisp -(define-minor-mode modus-themes-alt-mode - "Override Modus themes' palette variables with custom values. - -This is intended as a proof-of-concept. It is, nonetheless, a -perfectly accessible alternative, conforming with the design -principles of the Modus themes. It still is not as good as the -default colors." - :init-value nil - :global t - (if modus-themes-alt-mode - (setq modus-operandi-theme-override-colors-alist - '(("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-vivendi-theme-override-colors-alist - '(("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-operandi-theme-override-colors-alist nil - modus-vivendi-theme-override-colors-alist nil))) - -(defun modus-themes-toggle (&optional arg) - "Toggle between `modus-operandi' and `modus-vivendi' themes. - -With optional \\[universal-argument] prefix, enable -`modus-themes-alt-mode' for the loaded theme." - (interactive "P") - (if arg - (modus-themes-alt-mode 1) - (modus-themes-alt-mode -1)) - (if (eq (car custom-enabled-themes) 'modus-operandi) - (progn - (disable-theme 'modus-operandi) - (load-theme 'modus-vivendi t)) - (disable-theme 'modus-vivendi) - (load-theme 'modus-operandi t))) -@end lisp - -@printindex cp - -@node Font configs (DIY) -@section Font configurations for Org (and others) - -The themes are designed to cope well with mixed font settings (@ref{No mixed fonts, , Option -for no font mixing}). Currently this applies to @samp{org-mode} and -@samp{markdown-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 @samp{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 @samp{variable-pitch} (proportional spacing) and @samp{fixed-pitch} (monospaced) -faces respectively. It may also be convenient to set your main typeface -by configuring the @samp{default} face the same way. - -Put something like this in your initialization file (make sure to read -the documentation of @samp{set-face-attribute}, with @kbd{M-x describe-function}): - -@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 lisp - -Note the differences in the @samp{:height} property. The @samp{default} face must -specify an absolute value, which is the point size × 10. So if you want -to use a font at point size @samp{11}, you set the height at @samp{110}.@footnote{@samp{:height} -values do not need to be rounded to multiples of ten: the likes of @samp{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, say, @samp{15} then that means an absolute height). This is of -paramount importantance: it ensures that all fonts can scale gracefully -when using something like the @samp{text-scale-adjust} command which only -operates on the base font size (i.e. the @samp{default} face's absolute -height). - -An alternative syntax for the @samp{default} face, is to pass all typeface -parameters directly to a @samp{font} property.@footnote{Has the benefit of -accepting @samp{fontconfig} parameters (GNU/Linux), such as @samp{"DejaVu Sans -Mono-11:hintstyle=hintslight:autohint=false"}. -@uref{https://www.freedesktop.org/software/fontconfig/fontconfig-user.html}} -Note that here we use a standard point size: - -@lisp -(set-face-attribute 'default nil :font "DejaVu Sans Mono-11") -@end lisp - -Again, remember to only ever specify an absolute height for the @samp{default}. - -@printindex cp - -@node Org user faces (DIY) -@section Org user faces (DIY) - -Users of @samp{org-mode} have the option to configure various keywords and -priority cookies to better match their workflow. User options are -@samp{org-todo-keyword-faces} and @samp{org-priority-faces}. - -As those are meant to be custom faces, it would be futile to have the -themes try to guess what each user would want 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 aesthetics of the theme. - -Please bear in mind that the end result of those is not controlled by -the active theme but by how Org maps faces to its constructs. Editing -those while @samp{org-mode} is active requires @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: - -@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 lisp - -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 @samp{org-todo} face: - -@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 lisp - -This will refashion the keywords you specify, while letting the other -items in @samp{org-todo-keywords} use their original styles (which are defined -in the @samp{org-todo} and @samp{org-done} faces). - -If you want back the defaults, try specifying just the @samp{org-todo} face: - -@lisp -(setq org-todo-keyword-faces - '(("MEET" . org-todo) - ("STUDY" . org-todo) - ("WRITE" . org-todo))) -@end lisp - -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 @samp{keyword . face} would suffice. - -Both approaches can be used simultaneously, as illustrated in this -configuration of the priority cookies: - -@lisp -(setq org-priority-faces - '((?A . '(org-scheduled-today org-priority)) - (?B . org-priority) - (?C . '(shadow org-priority)))) -@end lisp - -To find all the faces that are loaded in your current Emacs session, use -@kbd{M-x list-faces-display}. Also try @kbd{M-x describe-variable} and then specify -the name of each of those Org variables demonstrated above. Their -documentation strings will offer you further guidance. - -Furthermore, consider reading the ``Notes for aspiring Emacs theme -developers'', published on 2020-08-28 by me (Protesilaos Stavrou): -@uref{https://protesilaos.com/codelog/2020-08-28-notes-emacs-theme-devs/}. - -@printindex cp - -@printindex cp - -@node Face coverage -@chapter Face coverage - -Modus Operandi and Modus Vivendi try to provide as close to full face -coverage as possible. This is necessary to ensure a consistently -accessible reading experience across all possible interfaces. - -@menu -* Supported packages:: Full list of covered face groups -* Covered indirectly:: -* Will NOT be supported:: -@end menu - -@node Supported packages -@section Full support for packages or face groups - -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 @samp{*} tend to -have lots of extensions, so the ``full support'' may not be 100% true… - -@itemize -@item -ace-window -@item -ag -@item -alert -@item -all-the-icons -@item -annotate -@item -anzu -@item -apropos -@item -apt-sources-list -@item -artbollocks-mode -@item -auctex and @TeX{} -@item -auto-dim-other-buffers -@item -avy -@item -awesome-tray -@item -binder -@item -bm -@item -bongo -@item -boon -@item -breakpoint (provided by the built-in @samp{gdb-mi.el} library) -@item -buffer-expose -@item -calendar and diary -@item -calfw -@item -centaur-tabs -@item -change-log and log-view (such as @samp{vc-print-log} and @samp{vc-print-root-log}) -@item -cider -@item -circe -@item -color-rg -@item -column-enforce-mode -@item -company-mode* -@item -company-posframe -@item -compilation-mode -@item -completions -@item -counsel* -@item -counsel-css -@item -counsel-notmuch -@item -counsel-org-capture-string -@item -cov -@item -cperl-mode -@item -csv-mode -@item -ctrlf -@item -custom (@kbd{M-x customize}) -@item -dap-mode -@item -dashboard (emacs-dashboard) -@item -deadgrep -@item -debbugs -@item -define-word -@item -deft -@item -dictionary -@item -diff-hl -@item -diff-mode -@item -dim-autoload -@item -dir-treeview -@item -dired -@item -dired-async -@item -dired-git -@item -dired-git-info -@item -dired-narrow -@item -dired-subtree -@item -diredfl -@item -disk-usage -@item -doom-modeline -@item -dynamic-ruler -@item -easy-jekyll -@item -easy-kill -@item -ebdb -@item -ediff -@item -eglot -@item -el-search -@item -eldoc-box -@item -elfeed -@item -elfeed-score -@item -emms -@item -enhanced-ruby-mode -@item -epa -@item -equake -@item -erc -@item -eros -@item -ert -@item -eshell -@item -eshell-fringe-status -@item -eshell-git-prompt -@item -eshell-prompt-extras (epe) -@item -eshell-syntax-highlighting -@item -evil* (evil-mode) -@item -evil-goggles -@item -evil-visual-mark-mode -@item -eww -@item -eyebrowse -@item -fancy-dabbrev -@item -flycheck -@item -flycheck-color-mode-line -@item -flycheck-indicator -@item -flycheck-posframe -@item -flymake -@item -flyspell -@item -flyspell-correct -@item -flx -@item -freeze-it -@item -frog-menu -@item -focus -@item -fold-this -@item -font-lock (generic syntax highlighting) -@item -forge -@item -fountain (fountain-mode) -@item -geiser -@item -git-commit -@item -git-gutter (and variants) -@item -git-lens -@item -git-rebase -@item -git-timemachine -@item -git-walktree -@item -gnus -@item -golden-ratio-scroll-screen -@item -helm* -@item -helm-ls-git -@item -helm-switch-shell -@item -helm-xref -@item -helpful -@item -highlight-blocks -@item -highlight-defined -@item -highlight-escape-sequences (@samp{hes-mode}) -@item -highlight-indentation -@item -highlight-numbers -@item -highlight-symbol -@item -highlight-tail -@item -highlight-thing -@item -hl-defined -@item -hl-fill-column -@item -hl-line-mode -@item -hl-todo -@item -hydra -@item -hyperlist -@item -ibuffer -@item -icomplete -@item -icomplete-vertical -@item -ido-mode -@item -iedit -@item -iflipb -@item -imenu-list -@item -indium -@item -info -@item -info-colors -@item -interaction-log -@item -ioccur -@item -isearch, occur, etc. -@item -ivy* -@item -ivy-posframe -@item -jira (org-jira) -@item -journalctl-mode -@item -js2-mode -@item -julia -@item -jupyter -@item -kaocha-runner -@item -keycast -@item -line numbers (@samp{display-line-numbers-mode} and global variant) -@item -lsp-mode -@item -lsp-ui -@item -magit -@item -magit-imerge -@item -man -@item -markdown-mode -@item -markup-faces (@samp{adoc-mode}) -@item -mentor -@item -messages -@item -minibuffer-line -@item -minimap -@item -modeline -@item -mood-line -@item -moody -@item -mpdel -@item -mu4e -@item -mu4e-conversation -@item -multiple-cursors -@item -neotree -@item -no-emoji -@item -notmuch -@item -num3-mode -@item -nxml-mode -@item -objed -@item -orderless -@item -org* -@item -org-journal -@item -org-noter -@item -org-pomodoro -@item -org-recur -@item -org-roam -@item -org-superstar -@item -org-table-sticky-header -@item -org-treescope -@item -origami -@item -outline-mode -@item -outline-minor-faces -@item -package (@kbd{M-x list-packages}) -@item -page-break-lines -@item -paradox -@item -paren-face -@item -parrot -@item -pass -@item -persp-mode -@item -perspective -@item -phi-grep -@item -phi-search -@item -pkgbuild-mode -@item -pomidor -@item -powerline -@item -powerline-evil -@item -proced -@item -prodigy -@item -racket-mode -@item -rainbow-blocks -@item -rainbow-identifiers -@item -rainbow-delimiters -@item -rcirc -@item -regexp-builder (also known as @samp{re-builder}) -@item -rg (rg.el) -@item -ripgrep -@item -rmail -@item -ruler-mode -@item -sallet -@item -selectrum -@item -semantic -@item -sesman -@item -shell-script-mode -@item -show-paren-mode -@item -side-notes -@item -skewer-mode -@item -smart-mode-line -@item -smartparens -@item -smerge -@item -spaceline -@item -speedbar -@item -spell-fu -@item -stripes -@item -suggest -@item -switch-window -@item -swiper -@item -swoop -@item -sx -@item -symbol-overlay -@item -syslog-mode -@item -table (built-in table.el) -@item -telephone-line -@item -term -@item -tomatinho -@item -transient (pop-up windows such as Magit's) -@item -trashed -@item -treemacs -@item -tty-menu -@item -tuareg -@item -typescript -@item -undo-tree -@item -vc (built-in mode line status for version control) -@item -vc-annotate (@kbd{C-x v g}) -@item -vdiff -@item -vimish-fold -@item -visible-mark -@item -visual-regexp -@item -volatile-highlights -@item -vterm -@item -wcheck-mode -@item -web-mode -@item -wgrep -@item -which-function-mode -@item -which-key -@item -whitespace-mode -@item -window-divider-mode -@item -winum -@item -writegood-mode -@item -woman -@item -xah-elisp-mode -@item -xref -@item -xterm-color (and ansi-colors) -@item -yaml-mode -@item -yasnippet -@item -ztree -@end itemize - -Plus many other miscellaneous faces that are provided by the upstream -GNU Emacs distribution. - -@node Covered indirectly -@section Covered indirectly - -These do not require any extra styles because they are configured to -inherit from some basic faces. Please confirm. - -@itemize -@item -edit-indirect -@item -evil-owl -@item -perl-mode -@item -php-mode -@item -rjsx-mode -@item -swift-mode -@end itemize - -@node Will NOT be supported -@section Will NOT be supported - -I have thus far identified a single package that does fit into the -overarching objective of this project: @uref{https://github.com/hlissner/emacs-solaire-mode, solaire}. It basically tries to -cast a less intense background on the main file-visiting buffers, so -that secondary elements like sidebars can have the default (pure -white/black) background. - -I will only cover this package if it ever supports the inverse effect: -less intense colors (but still accessible) for ancillary interfaces -and the intended styles for the content you are actually working on. - -@node Notes for individual packages -@chapter Notes for individual packages - -This section covers information that may be of interest to users of -individual packages. - -@menu -* Note on company-mode overlay pop-up:: -* Note for ERC escaped color sequences:: -* Note for powerline or spaceline:: -* Note on shr colors:: -* Note for Helm grep:: -* Note on vc-annotate-background-mode:: -@end menu - -@node Note on company-mode overlay pop-up -@section Note on company-mode overlay pop-up - -By default, the @samp{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 uses child frames -instead of overlays.@footnote{@uref{https://github.com/company-mode/company-mode/issues/1010}}@footnote{@uref{https://github.com/tumashu/company-posframe/}} - -@node Note for ERC escaped color sequences -@section Note for ERC escaped color sequences - -The built-in IRC client @samp{erc} has the ability to colorise any text using -escape sequences that start with @samp{^C} (inserted with @samp{C-q C-c}) and are -followed by a number for the foreground and background.@footnote{This page -explains the basics, though it is not specific to Emacs: -@uref{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 @samp{^C1,6}. The minimum setup is this: - -@lisp -(add-to-list 'erc-modules 'irccontrols) -(setq erc-interpret-controls-p t - erc-interpret-mirc-color t) -@end lisp - -As this allows users 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: - -@table @asis -@item Modus Operandi -Use foreground color 1 for all backgrounds from -2-15. Like so: @samp{C-q C-c1,N} where @samp{N} is the background. - -@item Modus Vivendi -Use foreground color 0 for all backgrounds from -2-13. Use foreground @samp{1} for backgrounds 14, 15. -@end table - -Colors 0 and 1 are white and black respectively. So combine them -together, if you must. - -@node Note for powerline or spaceline -@section Note for powerline or spaceline - -Both Powerline and Spaceline package users will likely need to use the -command @samp{powerline-reset} whenever they make changes to their themes -and/or modeline setup. - -@node Note on shr colors -@section Note on shr colors - -Emacs' HTML rendering mechanism (@samp{shr}) 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}. - -@node Note for Helm grep -@section Note for Helm grep - -There is one face from the Helm package that is meant to highlight the -matches of a grep or grep-like command (@samp{ag} or @samp{ripgrep}). It is -@samp{helm-grep-match}. However, this face can only apply when the user does -not pass @samp{--color=always} as a command-line option for their command. - -Here is the docstring for that face, which is defined in the -@samp{helm-grep.el} library (view a library with @samp{M-x find-library}). - -@quotation -Face used to highlight grep matches. Have no effect when grep backend -use ``--color='' - -@end quotation - -The user must either remove @samp{--color} from the flags passed to the grep -function, or explicitly use @samp{--color=never} (or equivalent). Helm -provides user-facing customization options for controlling the grep -function's parameters, such as @samp{helm-grep-default-command} and -@samp{helm-grep-git-grep-command}. - -When @samp{--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 -@samp{ansi-color-names-vector}. - -@node Note on vc-annotate-background-mode -@section Note on vc-annotate-background-mode - -Due to the unique way @samp{vc-annotate} (@kbd{C-x v g}) applies colors, support for -its background mode (@samp{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 (see @ref{Contributing}). - -@node Contributing -@chapter Contributing - -This section documents the canonical sources of the themes and the ways -in which you can contribute to their ongoing development. - -@menu -* Sources of the themes:: -* Issues you can help with:: -* Merge requests:: Legal considerations for code patches -@end menu - -@node Sources of the themes -@section Sources of the themes - -The @samp{modus-operandi} and @samp{modus-vivendi} themes are built into Emacs. -Currently they are in the project's @samp{master} branch, which is tracking the -next development release target. - -The source code of the themes is @uref{https://gitlab.com/protesilaos/modus-themes/, available on Gitlab}, for the time -being. A @uref{https://github.com/protesilaos/modus-themes/, mirror on Github} is also on offer. - -An HTML version of this manual is available as an extension to the -@uref{https://protesilaos.com/modus-themes/, author's personal website} (does not rely on any non-free code). - -@node Issues you can help with -@section Issues you can help with - -A few tasks you can help with: - -@itemize -@item -Suggest refinements to packages that are covered. -@item -Report packages not covered thus far. -@item -Report bugs, inconsistencies, shortcomings. -@item -Help expand the documentation of covered-but-not-styled packages. -@item -Suggest refinements to the color palette. -@item -Help expand this document or any other piece of documentation. -@item -Merge requests for code refinements. -@end itemize - -@xref{Merge requests, , Patches require copyright assignment to the FSF}. - -It would be great if your feedback also 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. - -@node Merge requests -@section Patches require copyright assignment to the FSF - -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. - -@example -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?] - -Changed a couple of themes that are part of the Emacs source code: - -./etc/themes/modus-operandi-theme.el -./etc/themes/modus-vivendi-theme.el -@end example - -@node Acknowledgements -@chapter Acknowledgements - -The Modus themes are a collective effort. Every contribution counts. - -@table @asis -@item Author/maintainer -Protesilaos Stavrou. - -@item Code contributions -Anders Johansson, Basil L@. Contovounesios, -Markus Beppler, Matthew Stevenson. - -@item Ideas and user feedback -Aaron Jensen, Adam Spiers, Alex Griffin, -Alex Peitsinis, Alexey Shmalko, Anders Johansson, André Alexandre -Gomes, Arif Rezai, Basil L@. Contovounesios, Damien Cassou, Dario -Gjorgjevski, David Edmondson, Davor Rotim, Divan Santana, Gerry -Agbobada, Gianluca Recchia, Iris Garcia, Len Trigg, Manuel Uberti, -Mark Burton, Markus Beppler, Michael Goldenberg, Murilo Pereira, -Nicolas De Jaeghere, Pierre Téchoueyres, Roman Rudakov, Ryan Phillips, -Shreyas Ragavan, Tassilo Horn, Thibaut Verron, Trey Merkley, Uri -Sharf, Utkarsh Singh, Vincent Foley. As well as users: Ben, -Fourchaux, Fredrik, Moesasji, Nick, TheBlob42, dinko, doolio, jixiuf, -okamsn, tycho garen. - -@item Packaging -Dhavan Vaidya (Debian), Stefan Kangas (core Emacs), -Stefan Monnier (GNU Elpa). - -@item Inspiration for certain features -Fabrice Niessen (leuven-theme), -Bozhidar Batsov (zenburn-theme). -@end table - -@node Meta -@chapter Meta - -If you are curious about the principles that govern the development of -this project read the essay @uref{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): - -@itemize -@item -@uref{https://protesilaos.com/codelog/2020-05-10-modus-operandi-palette-review/, Modus Operandi theme subtle palette review} (2020-05-10) -@item -@uref{https://protesilaos.com/codelog/2020-06-13-modus-vivendi-palette-review/, Modus Vivendi theme subtle palette review} (2020-06-13) -@item -@uref{https://protesilaos.com/codelog/2020-07-04-modus-themes-faint-colours/, Modus themes: new ``faint syntax'' option} (2020-07-04) -@item -@uref{https://protesilaos.com/codelog/2020-07-08-modus-themes-nuanced-colours/, Modus themes: major review of ``nuanced'' colours} (2020-07-08) -@item -@uref{https://protesilaos.com/codelog/2020-09-14-modus-themes-review-blues/, Modus themes: review of blue colours} (2020-09-14) -@end itemize - -And here are the canonical sources for this project's documentation: - -@table @asis -@item Manual -@uref{https://protesilaos.com/modus-themes} -@item Change Log -@uref{https://protesilaos.com/modus-themes-changelog} -@item Screenshots -@uref{https://protesilaos.com/modus-themes-pictures} -@end table - -@node External projects (ports) -@chapter External projects (ports) - -The present section documents projects that extend the scope of the -Modus themes. The following list will be updated whenever relevant -information is brought to my attention. If you already have or intend -to produce such a port, feel welcome @uref{https://protesilaos.com/contact, to contact me}. - -@table @asis -@item Modus exporter -This is @uref{https://github.com/polaris64/modus-exporter, an Elisp library written by Simon Pugnet}. -Licensed under the terms of the GNU General Public License. It is -meant to capture the color values of the active Modus theme (Operandi -or Vivendi) and output it as a valid theme for some other application. -@end table - -@node GNU Free Documentation License -@appendix GNU Free Documentation License - -@example - 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 example - -@bye |