[elpa] externals/standard-themes cacc2ee597 13/74: Write the manual

[ELPA Syncer]

branch: externals/standard-themes
commit cacc2ee597aaec2f8bf7e3dbded620e7622d32c2
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Write the manual
---
 README.org      | 1656 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 doclicense.texi |  505 +++++++++++++++++
 2 files changed, 2161 insertions(+)

diff --git a/README.org b/README.org
new file mode 100644
index 0000000000..917a73eaee
--- /dev/null
+++ b/README.org
@@ -0,0 +1,1656 @@
+#+title:                 standard-themes: Like the default theme but more 
consistent
+#+author:                Protesilaos Stavrou
+#+email:                 info@protesilaos.com
+#+language:              en
+#+options:               ':t toc:nil author:t email:t num:t
+#+startup:               content
+#+macro:                 stable-version 1.0.0
+#+macro:                 release-date N/A
+#+macro:                 development-version 1.1.0-dev
+#+export_file_name:      standard-themes.texi
+#+texinfo_filename:      standard-themes.info
+#+texinfo_dir_category:  Emacs misc features
+#+texinfo_dir_title:     Standard-Themes: (standard-themes)
+#+texinfo_dir_desc:      Like the default theme but more consistent
+#+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 Emacs package
+called =standard-themes=, and provides every other piece of information
+pertinent to it.
+
+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}}}.
+
++ Package name (GNU ELPA): =standard-themes=
++ Official manual: <https://protesilaos.com/emacs/standard-themes>
++ Change log: <https://protesilaos.com/emacs/standard-themes-changelog>
++ Sample pictures: <https://protesilaos.com/emacs/standard-themes-pictures>
++ Git repo on SourceHut: <https://git.sr.ht/~protesilaos/standard-themes>
+  - Mirrors:
+    + GitHub: <https://github.com/protesilaos/standard-themes>
+    + GitLab: <https://gitlab.com/protesilaos/standard-themes>
++ Mailing list: <https://lists.sr.ht/~protesilaos/standard-themes>
++ Backronym: Standard Themes Are Not Derivatives but the
+  Affectionately Reimagined Default ... themes.
+
+If you are viewing the README.org version of this file, please note that
+the GNU ELPA machinery automatically generates an Info manual out of it.
+
+#+toc: headlines 8 insert TOC here, with eight headline levels
+
+* COPYING
+:PROPERTIES:
+:COPYING: t
+:CUSTOM_ID: h:1164c8e7-6b52-433c-a2a1-1bf181ca2752
+:END:
+
+Copyright (C) 2022  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 the Front-Cover Texts being “A GNU Manual,” and
+with the Back-Cover Texts as in (a) below.  A copy of the license is
+included in the section entitled “GNU Free Documentation License.”
+
+(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
+modify this GNU manual.”
+#+end_quote
+
+* Installation
+:PROPERTIES:
+:CUSTOM_ID: h:3306414a-e56a-4fda-b70a-73a4140cfa0a
+:END:
+#+cindex: Installation instructions
+
+** GNU ELPA package
+:PROPERTIES:
+:CUSTOM_ID: h:cb6ae4d6-76a1-4bc3-90af-aafcaa05dc35
+:END:
+
+The package is available as =standard-themes=.  Simply do:
+
+: M-x package-refresh-contents
+: M-x package-install
+
+And search for it.
+
+GNU ELPA provides the latest stable release.  Those who prefer to follow
+the development process in order to report bugs or suggest changes, can
+use the version of the package from the GNU-devel ELPA archive.  Read:
+https://protesilaos.com/codelog/2022-05-13-emacs-elpa-devel/.
+
+** Manual installation
+:PROPERTIES:
+:CUSTOM_ID: h:49a5e35d-834e-434f-a8f2-d3a69b688d63
+:END:
+
+Assuming your Emacs files are found in =~/.emacs.d/=, execute the
+following commands in a shell prompt:
+
+#+begin_src sh
+cd ~/.emacs.d
+
+# Create a directory for manually-installed packages
+mkdir manual-packages
+
+# Go to the new directory
+cd manual-packages
+
+# Clone this repo, naming it "standard-themes"
+git clone https://git.sr.ht/~protesilaos/standard-themes standard-themes
+#+end_src
+
+Finally, in your =init.el= (or equivalent) evaluate this:
+
+#+begin_src emacs-lisp
+;; Make Elisp files in that directory available to the user.
+(add-to-list 'load-path "~/.emacs.d/manual-packages/standard-themes")
+#+end_src
+
+Everything is in place to set up the package.
+
+* Sample configuration
+:PROPERTIES:
+:CUSTOM_ID: h:7141f66d-f1b3-4c9a-b07a-f8e78068dcdc
+:END:
+
+#+begin_src emacs-lisp
+;; Make customisations that affect Emacs faces BEFORE loading a theme
+;; (any change needs a theme re-load to take effect).
+(require 'standard-themes)
+
+;; Read the doc string of each of those user options.  These are some
+;; sample values.
+(setq standard-themes-bold-constructs t
+      standard-themes-italic-constructs t
+      standard-themes-mixed-fonts t
+      standard-themes-variable-pitch-ui t
+      standard-themes-mode-line-accented t
+
+      ;; Accepts a symbol value:
+      standard-themes-fringes 'subtle
+
+      ;; The following accept lists of properties
+      standard-themes-links '(neutral-underline)
+      standard-themes-region '(no-extend neutral intense)
+      standard-themes-prompts '(bold italic)
+
+      ;; more complex alist to set weight, height, and optional
+      ;; `variable-pitch' per heading level (t is for any level not
+      ;; specified):
+      standard-themes-headings
+      '((0 . (variable-pitch light 1.9))
+        (1 . (variable-pitch light 1.8))
+        (2 . (variable-pitch light 1.7))
+        (3 . (variable-pitch semilight 1.6))
+        (4 . (variable-pitch semilight 1.5))
+        (5 . (variable-pitch 1.4))
+        (6 . (variable-pitch 1.3))
+        (7 . (variable-pitch 1.2))
+        (t . (variable-pitch 1.1))))
+
+;; Disable all other themes to avoid awkward blending:
+(mapc #'disable-theme custom-enabled-themes)
+
+(load-theme 'standard-light :no-confirm)
+
+(define-key global-map (kbd "<f5>") #'standard-themes-toggle)
+#+end_src
+
+* Customization options
+:PROPERTIES:
+:CUSTOM_ID: h:c3975e07-8bbb-42b2-a160-27e3afeb3258
+:END:
+
+The =standard-themes= provide user options which tweak secondary
+aspects of the theme.  All customizations need to be evaluated before
+loading a theme.  Any change after the theme has been loaded require a
+re-load ([[#h:59c399d6-5dca-4686-b793-255be8bffc31][Loading a theme]]).
+
+** Enable mixed fonts
+:PROPERTIES:
+:CUSTOM_ID: h:a939ee30-f705-4d70-aa00-cca5528ef172
+:END:
+
+#+vindex: standard-themes-mixed-fonts
+The user option ~standard-themes-mixed-fonts~ controls whether strictly
+spacing-sensitive constructs inherit from ~fixed-pitch~ (a monospaced
+font family).
+
+By default (a ~nil~ value for this user option) no face inherits from
+~fixed-pitch~: they all use the default font family, regardless of
+whether it is monospaced or not.
+
+When ~standard-themes-mixed-fonts~ is set to a non-~nil~ value, faces
+such as for Org tables, inline code, code blocks, and the like, are
+rendered in a monospaced font at all times.  The user can thus set
+their default font family to a proportionately spaced font without
+worrying about breaking the alignment of relevant elements, or if they
+simply prefer the aesthetics of mixed mono and proportionately spaced
+font families.
+
+A temporary switch to a proportionately spaced font (known in Emacs as
+~variable-pitch~) can be enabled in the current buffer with the
+activation of the built-in ~variable-pitch-mode~.
+
+To get consistent typography, the user may need to edit the font
+family of the ~fixed-pitch~ and ~variable-pitch~ faces.  The
+=fontaine= package on GNU ELPA (by Protesilaos) can be helpful in this
+regard.
+
+** Accented mode line
+:PROPERTIES:
+:CUSTOM_ID: h:7ccb3fce-4980-4bd6-9281-bdf5fc750902
+:END:
+
+#+vindex: standard-themes-mode-line-accented
+The user option ~standard-themes-mode-line-accented~ handles the
+background color of the active mode line.  When the value is ~nil~,
+the color is gray, while non-~nil~ uses an accent value.
+
+** UI typeface
+:PROPERTIES:
+:CUSTOM_ID: h:fbe4de97-f582-4a53-93cb-6ed4747cdc42
+:END:
+
+#+vindex: standard-themes-variable-pitch-ui
+The user option ~standard-themes-variable-pitch-ui~ controls whether
+the elements of the User Interface (UI) use a proportionately spaced
+font.  By default (a ~nil~ value), all UI elements use the default
+font family.  When this user option is set to a non-~nil~ value, all
+UI elements will inherit the face ~variable-pitch~, thus rendering
+them in a proportionately spaced font.
+
+In this context, the UI elements are:
+
+- ~header-line~
+- ~mode-line~ (active and inactive)
+- ~tab-bar-mode~
+- ~tab-line-mode~
+
+To get consistent typography, the user may need to edit the font
+family of the ~fixed-pitch~ and ~variable-pitch~ faces.  The
+=fontaine= package on GNU ELPA (by Protesilaos) can be helpful in this
+regard.
+
+** Bold constructs
+:PROPERTIES:
+:CUSTOM_ID: h:9bd84648-681b-4369-9868-4f89f2d6abf5
+:END:
+
+#+vindex: standard-themes-bold-constructs
+The user option ~standard-themes-bold-constructs~ determines whether
+select faces will inherit the ~bold~ face.  When the value is
+non-~nil~, a bold weight is applied to code constructs.  This affects
+keywords, builtins, and a few other elements.
+
+[[#h:2c92df8a-02c5-4124-82f8-e3ccdef1a4f8][Configure bold and italic faces]].
+
+** Italic constructs
+:PROPERTIES:
+:CUSTOM_ID: h:a49f7515-04cb-4932-a75c-e45080f12c28
+:END:
+
+#+vindex: standard-themes-italic-constructs
+The user option ~standard-themes-italic-constructs~ determines whether
+select faces will inherit the ~italic~ face.  When the value is
+non-~nil~, an italic style is applied to code constructs.  This
+affects comments, doc strings, and a few other minor elements.
+
+[[#h:2c92df8a-02c5-4124-82f8-e3ccdef1a4f8][Configure bold and italic faces]].
+
+** Fringe visibility
+:PROPERTIES:
+:CUSTOM_ID: h:a04db578-dacc-422e-a3a9-e4b41afd9b0b
+:END:
+
+#+vindex: standard-themes-fringes
+The user option ~standard-themes-fringes~ controls the visibility and
+intensity of the fringes.  With regular Emacs settings "Fringe" is a
+small surface area to either side of the Emacs window: it is where
+certain indicators are displayed, such as continuation lines.
+
+When the value is ~nil~, do not apply a distinct background color.
+
+With a value of ~subtle~, use a gray background color that is visible
+yet close to the main background color.  This is the default style.
+
+With ~intense~, use a more pronounced gray background color.
+
+** Link style
+:PROPERTIES:
+:CUSTOM_ID: h:b92555bf-1542-40f6-945b-f59849e6446c
+:END:
+
+#+vindex: standard-themes-links
+The user option ~standard-themes-links~ controls the style of links.
+The value is a list of properties, each designated by a symbol.  The
+default (a nil value or an empty list) is a prominent text color,
+typically blue, with an underline of the same color.
+
+For the style of the underline, a ~neutral-underline~ property
+turns the color of the line into a subtle gray, while the
+~no-underline~ property removes the line altogether.  If both of
+those are set, the latter takes precedence.
+
+For text coloration, a ~faint~ property desaturates the color of
+the text and the underline, unless the underline is affected by
+the aforementioned properties.
+
+A ~bold~ property applies a heavy typographic weight to the text
+of the link.
+
+An ~italic~ property adds a slant to the link's text (italic or
+oblique forms, depending on the typeface).
+
+Combinations of any of those properties are expressed as a list,
+like in these examples:
+
+#+begin_src emacs-lisp
+(faint)
+(no-underline faint)
+#+end_src
+
+The order in which the properties are set is not significant.
+
+In user configuration files the form may look like this:
+
+#+begin_src emacs-lisp
+(setq standard-themes-links '(neutral-underline faint))
+#+end_src
+
+The placement of the underline, meaning its proximity to the
+text, is controlled by ~x-use-underline-position-properties~,
+~x-underline-at-descent-line~, ~underline-minimum-offset~.
+Please refer to their documentation strings.
+
+** Option for command prompts
+:PROPERTIES:
+:CUSTOM_ID: h:eedd0b6b-9f84-48bc-8871-620934506aa6
+:END:
+
+#+vindex: standard-themes-prompts
+The user option ~standard-themes-prompts~ controls the style of all
+prompts, such as those of the minibuffer and REPLs.
+
+The value is a list of properties, each designated by a symbol.
+The default (a nil value or an empty list) means to only use a
+subtle accented foreground color.
+
+The property ~background~ applies a background color to the
+prompt's text.  By default, this is a subtle accented value.
+
+The property ~bold~ makes the text use a bold typographic weight.
+Similarly, ~italic~ adds a slant to the font's forms (italic or
+oblique forms, depending on the typeface).
+
+Combinations of any of those properties are expressed as a list,
+like in these examples:
+
+#+begin_src emacs-lisp
+(intense)
+(bold intense)
+(intense bold gray)
+(intense background gray bold)
+#+end_src
+
+The order in which the properties are set is not significant.
+
+In user configuration files the form may look like this:
+
+#+begin_src emacs-lisp
+(setq standard-themes-prompts '(background gray))
+#+end_src
+
+** Option for headings
+:PROPERTIES:
+:CUSTOM_ID: h:8540fd7a-7633-4eb9-af4b-4f160568f79a
+:END:
+
+#+vindex: standard-themes-headings
+The user option ~standard-themes-headings~ provides support for individual
+heading styles for levels 0 through 8.
+
+This is an alist that accepts a =(key . list-of-values)= combination.
+The key is either a number, representing the heading's level (0
+through 8) or =t=, which pertains to the fallback style.
+
+Level 0 is a special heading: it is used for what counts as a document
+title or equivalent, such as the =#+title= construct we find in Org
+files.  Levels 1-8 are regular headings.
+
+The list of values covers symbols that refer to properties, as described
+below.  Here is a complete sample, followed by a presentation of all
+available properties:
+
+#+begin_src emacs-lisp
+(setq standard-themes-headings
+      '((1 . (light variable-pitch 1.5))
+        (2 . (regular 1.3))
+        (3 . (1.1))
+        (t . (variable-pitch))))
+#+end_src
+
+By default (a ~nil~ value for this variable), all headings have a bold
+typographic weight, a font family that is the same as the ~default~ face
+(typically monospaced), and a height that is equal to the ~default~
+face's height.
+
+- A ~variable-pitch~ property changes the font family of the heading
+  to that of the ~variable-pitch~ face (normally a proportionately
+  spaced typeface).  Also check the =fontaine= package (by
+  Protesilaos) for tweaking fonts via faces.
+
+- The symbol of a weight attribute adjusts the font of the heading
+  accordingly, such as ~light~, ~semibold~, etc.  Valid symbols are
+  defined in the variable ~standard-themes-weights~.  The absence of a
+  weight means that no distinct weight will be used.
+
+- A number, expressed as a floating point (e.g. 1.5), adjusts the
+  height of the heading to that many times the base font size.  The
+  default height is the same as 1.0, though it need not be explicitly
+  stated.  Instead of a floating point, an acceptable value can be in
+  the form of a cons cell like =(height . FLOAT)= or =(height FLOAT)=,
+  where =FLOAT= is the given number.
+
+Combinations of any of those properties are expressed as a list, like
+in these examples:
+
+#+begin_src emacs-lisp
+(semibold)
+(variable-pitch semibold)
+(variable-pitch semibold 1.3)
+(variable-pitch semibold (height 1.3))   ; same as above
+(variable-pitch semibold (height . 1.3)) ; same as above
+#+end_src
+
+The order in which the properties are set is not significant.
+
+In user configuration files the form may look like this:
+
+#+begin_src emacs-lisp
+(setq standard-themes-headings
+      '((1 . (light variable-pitch 1.5))
+        (2 . (regular 1.3))
+        (3 . (1.1))
+        (t . (variable-pitch))))
+#+end_src
+
+When defining the styles per heading level, it is possible to
+pass a non-~nil~ value (t) instead of a list of properties.  This
+will retain the original aesthetic for that level.  For example:
+
+#+begin_src emacs-lisp
+(setq standard-themes-headings
+      '((1 . t)           ; keep the default style
+        (2 . (variable-pitch 1.2))
+        (t . (variable-pitch)))) ; style for all unspecified headings
+
+(setq standard-themes-headings
+      '((1 . (variable-pitch 1.6))
+        (2 . (1.3))
+        (t . t))) ; default style for all unspecified levels
+#+end_src
+
+** Style of region highlight
+:PROPERTIES:
+:CUSTOM_ID: h:827e4fff-0416-4eba-a364-a6588f80b768
+:END:
+
+#+vindex: standard-themes-region
+The user option ~standard-themes-region~ controls the appearance of
+the ~region~ face (the highlighted selection of an area).
+
+The value it accepts is a list of symbols.
+
+If ~nil~ or an empty list (the default), use a subtle background for
+the region and preserve the color of selected text.
+
+The ~no-extend~ symbol limits the highlighted area to the end of the
+line, so that it does not reach the edge of the window.
+
+The ~neutral~ symbol makes the highlighted area's background gray (or
+more gray, depending on the theme).
+
+The ~intense~ symbol amplifies the intensity of the highlighted area's
+background color.  It also overrides any text color to keep it
+legible.
+
+Combinations of those symbols are expressed in any order.
+
+In user configuration files the form may look like this:
+
+#+begin_src emacs-lisp
+(setq standard-themes-region '(intense no-extend))
+#+end_src
+
+Other examples:
+
+#+begin_src emacs-lisp
+(setq standard-themes-region '(intense))
+(setq standard-themes-region '(intense no-extend neutral))
+#+end_src
+
+* Loading a theme
+:PROPERTIES:
+:CUSTOM_ID: h:59c399d6-5dca-4686-b793-255be8bffc31
+:END:
+
+Emacs can load and maintain enabled multiple themes at once.  This
+typically leads to awkward styling and weird combinations.  The theme
+looks broken and the designer's intent is misunderstood.  Before
+loading either of the =standard-themes=, the user is encouraged to
+disable all others:
+
+#+begin_src emacs-lisp
+(mapc #'disable-theme custom-enabled-themes)
+#+end_src
+
+Then load the theme of choice.  For example:
+
+#+begin_src emacs-lisp
+(load-theme 'standard-light :no-confirm)
+#+end_src
+
+The =:no-confirm= is optional.  It simply skips the step where Emacs
+asks the user whether they are sure about loading the theme.
+
+Consider adding code like the above to the user configuration file, such
+as =init.el=.
+
+#+findex: standard-themes-load-dark
+#+findex: standard-themes-load-light
+#+findex: standard-themes-toggle
+As the Standard themes are extensible, another way to load the theme
+of choice is to use either ~standard-themes-load-dark~ or
+~standard-themes-load-light~.  These functions take care of (i)
+disabling other themes, (ii) loading the specified Standard theme, and
+(iii) running the ~standard-themes-post-load-hook~ which is useful for
+do-it-yourself customizations ([[#h:a6d48445-c215-4f2e-b0ff-c83b0c673fa7][The 
general approach to DIY changes]]).
+These two functions are also called by the command
+~standard-themes-toggle~.
+
+* Preview theme colors
+:PROPERTIES:
+:CUSTOM_ID: h:1eebe221-0d0c-43e8-877a-202d2f15ef34
+:END:
+
+#+findex: standard-themes-preview-colors
+The command ~standard-themes-preview-colors~ uses minibuffer
+completion to select an item from the Standard themes and then
+produces a buffer with previews of its color palette entries.  The
+buffer has a naming scheme which reflects the given choice, like
+=standard-light-preview-colors= for the ~standard-light~ theme.
+
+#+findex: standard-themes-preview-colors-current
+The command ~standard-themes-preview-colors-current~ skips the
+minibuffer selection process and just produces a preview for the
+current Standard theme.
+
+* Use colors from the active Standard theme
+:PROPERTIES:
+:CUSTOM_ID: h:a4d62b3e-0f90-4016-829a-6b6ff8ff7c23
+:END:
+
+#+findex: standard-themes-with-colors
+Advanced users may want to call color variables from the palette of
+the active Standard theme.  The macro ~standard-themes-with-colors~
+supplies those to any form called inside of it.  For example:
+
+#+begin_src emacs-lisp
+(standard-themes-with-colors
+  (list bg-main fg-main bg-mode-line))
+;; => ("#ffffff" "#000000" "#b3b3b3")
+#+end_src
+
+The above return value is for =standard-light= when that is the active
+Standard theme.  Switching to =standard-dark= and evaluating this code
+anew will give us the relevant results for that theme:
+
+#+begin_src emacs-lisp
+(standard-themes-with-colors
+  (list bg-main fg-main bg-mode-line cursor))
+;; => ("#000000" "#ffffff" "#505050")
+#+end_src
+
+[[#h:a4f7a8fb-11a5-4e32-897b-f930b7d5c043][Do-It-Yourself customizations]].
+
+The palette of each Standard theme is considered stable.  No removals
+shall be made.  Though please note that some tweaks to individual hues
+or color mapping are still possible.  At any rate, we will not
+outright break any code that uses ~standard-themes-with-colors~.
+
+* Do-It-Yourself customizations
+:PROPERTIES:
+:CUSTOM_ID: h:a4f7a8fb-11a5-4e32-897b-f930b7d5c043
+:END:
+
+This section shows how the user can tweak the Standard themes to their
+liking, often by employing the ~standard-themes-with-colors~ macro
+([[#h:a4d62b3e-0f90-4016-829a-6b6ff8ff7c23][Use colors from the active 
Standard theme]]).
+
+** The general approach to advanced DIY changes
+:PROPERTIES:
+:CUSTOM_ID: h:a6d48445-c215-4f2e-b0ff-c83b0c673fa7
+:END:
+
+When the user wants to customize Emacs faces there are two
+considerations they need to make if they care about robustness:
+
+1. Do not hardcode color values, but instead use the relevant variables
+   from the Standard themes.
+2. Make the changes persist through theme changes between the Standard
+   themes.
+
+#+vindex: standard-themes-post-load-hook
+For point 1 we provide the ~standard-themes-with-colors~ macro, while for
+point 2 we have the ~standard-themes-post-load-hook~.  The hook runs
+at the end of the command ~standard-themes-toggle~.
+
+[[#h:a4d62b3e-0f90-4016-829a-6b6ff8ff7c23][Use colors from the active Standard 
theme]].
+
+[[#h:4296ba7b-7bad-4dbe-9ce8-da20c957c99a][A theme-agnostic hook for theme 
loading]].
+
+We need to wrap our code in the ~standard-themes-with-colors~ and
+declare it as a function which we then add to the hook.  Here we show
+the general approach of putting those pieces together.
+
+To customize faces in a way that mirrors the Standard themes' source
+code, we use the built-in ~custom-set-faces~.  The value it accepts
+has the same syntax as that found in =standard-themes.el=,
+specifically the ~standard-themes-faces~ constant.  It thus is easy to
+copy lines from there and tweak them.  Let's pick a couple of
+font-lock faces (used in all programming modes, among others):
+
+#+begin_src emacs-lisp
+(defun my-standard-themes-custom-faces ()
+  "My customizations on top of the Standard themes.
+This function is added to the `standard-themes-post-load-hook'."
+  (standard-themes-with-colors
+    (custom-set-faces
+     ;; These are the default specifications
+     `(font-lock-comment-face ((,c :inherit standard-themes-italic :foreground 
,comment)))
+     `(font-lock-variable-name-face ((,c :foreground ,variable))))))
+
+;; Using the hook lets our changes persist when we use the commands
+;; `standard-themes-toggle', `standard-themes-select', and 
`standard-themes-load-random'.
+(add-hook 'standard-themes-post-load-hook #'my-standard-themes-custom-faces)
+#+end_src
+
+Each of the Standard themes has its own color palette and
+corresponding mapping of values to constructs.  So the color of the
+=comment= variable will differ between the themes.  For the purpose of
+our demonstration, we make variables look like comments and comments
+like variables:
+
+#+begin_src emacs-lisp
+(defun my-standard-themes-custom-faces ()
+  "My customizations on top of the Standard themes.
+This function is added to the `standard-themes-post-load-hook'."
+  (standard-themes-with-colors
+    (custom-set-faces
+     `(font-lock-comment-face ((,c :foreground ,variable)))
+     `(font-lock-variable-name-face ((,c :inherit standard-themes-italic 
:foreground ,comment))))))
+
+;; Using the hook lets our changes persist when we use the commands
+;; `standard-themes-toggle', `standard-themes-load-dark',
+;; `standard-themes-load-light'
+(add-hook 'standard-themes-post-load-hook #'my-standard-themes-custom-faces)
+#+end_src
+
+All changes take effect when a theme is loaded again.  As such, it is
+better to use either ~standard-themes-load-dark~ or
+~standard-themes-load-light~ at startup so that the function added to
+the hook gets applied properly upon first load.  Like this:
+
+#+begin_src emacs-lisp
+(defun my-standard-themes-custom-faces ()
+  "My customizations on top of the Standard themes.
+This function is added to the `standard-themes-post-load-hook'."
+  (standard-themes-with-colors
+    (custom-set-faces
+     `(font-lock-comment-face ((,c :foreground ,variable)))
+     `(font-lock-variable-name-face ((,c :inherit standard-themes-italic 
:foreground ,comment))))))
+
+;; Using the hook lets our changes persist when we use the commands
+;; `standard-themes-toggle', `standard-themes-select', and 
`standard-themes-load-random'.
+(add-hook 'standard-themes-post-load-hook #'my-standard-themes-custom-faces)
+
+;; Load the theme and run `standard-themes-post-load-hook'
+(standard-themes-load-light) ; OR (standard-themes-load-dark)
+#+end_src
+
+Please contact us if you have specific questions about this mechanism.
+We are willing to help and shall provide comprehensive documentation
+where necessary.
+
+** A theme-agnostic hook for theme loading
+:PROPERTIES:
+:CUSTOM_ID: h:4296ba7b-7bad-4dbe-9ce8-da20c957c99a
+: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 ~standard-themes-post-load-hook~,
+which is called after the evaluation of any of the commands we provide
+for loading a theme ([[#h:59c399d6-5dca-4686-b793-255be8bffc31][Loading a 
theme]]).  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 Standard themes
+and other items (e.g. the =modus-themes= and =ef-themes=) will find
+that such a hook does not meet their requirements: it only works with
+the Standard themes and only with the functions they provide.
+
+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
+~standard-themes-select~ and the others mentioned in this manual.  The
+function ~enable-theme~ is called internally by ~load-theme~, so the
+hook works everywhere.
+
+The downside of the theme-agnostic hook is that any functions added to
+it will likely not be able to benefit from macro calls that read the
+active theme, such as ~standard-themes-with-colors~ (the Modus and Ef
+themes have an equivalent macro).  Not all Emacs themes have the same
+capabilities.
+
+In this document, we always mention ~standard-themes-post-load-hook~
+though the user can replace it with ~after-enable-theme-hook~ should
+they need to (provided they understand the implications).
+
+** Add support for hl-todo
+:PROPERTIES:
+:CUSTOM_ID: h:f9017f6b-a59d-4512-8d52-9e8ab5a59f87
+:END:
+
+The =hl-todo= package provides the user option ~hl-todo-keyword-faces~:
+it specifies an association list of =(KEYWORD . COLOR-VALUE)= pairs.
+There are no faces, which the theme could style seamlessly.  As such, it
+rests on the user to specify appropriate color values.  This can be done
+either by hardcoding colors, which is inefficient, or by using the macro
+~standard-themes-with-colors~ ([[#h:a6d48445-c215-4f2e-b0ff-c83b0c673fa7][The 
general approach to DIY changes]]).
+Here we show the latter method.
+
+#+begin_src emacs-lisp
+(defun my-standard-themes-hl-todo-faces ()
+  "Configure `hl-todo-keyword-faces' with Standard themes colors.
+The exact color values are taken from the active Standard theme."
+  (standard-themes-with-colors
+    (setq hl-todo-keyword-faces
+          `(("HOLD" . ,yellow)
+            ("TODO" . ,red)
+            ("NEXT" . ,blue)
+            ("THEM" . ,magenta)
+            ("PROG" . ,cyan-warmer)
+            ("OKAY" . ,green-warmer)
+            ("DONT" . ,yellow-warmer)
+            ("FAIL" . ,red-warmer)
+            ("BUG" . ,red-warmer)
+            ("DONE" . ,green)
+            ("NOTE" . ,blue-warmer)
+            ("KLUDGE" . ,cyan)
+            ("HACK" . ,cyan)
+            ("TEMP" . ,red)
+            ("FIXME" . ,red-warmer)
+            ("XXX+" . ,red-warmer)
+            ("REVIEW" . ,red)
+            ("DEPRECATED" . ,yellow)))))
+
+(add-hook 'standard-themes-post-load-hook #'my-standard-themes-hl-todo-faces)
+#+end_src
+
+To find the names of the color variables, the user can rely on the
+commands for previewing the palette 
([[#h:1eebe221-0d0c-43e8-877a-202d2f15ef34][Preview theme colors]]).
+
+** Configure bold and italic faces
+:PROPERTIES:
+:CUSTOM_ID: h:2c92df8a-02c5-4124-82f8-e3ccdef1a4f8
+:END:
+#+cindex: Bold and italic fonts
+
+The Standard themes do not hardcode a ~:weight~ or ~:slant~ attribute in the
+faces they cover.  Instead, they configure the generic faces called
+~bold~ and ~italic~ to use the appropriate styles and then instruct all
+relevant faces that require emphasis to inherit from them.
+
+This practically means that users can change the particularities of what
+it means for a construct to be bold/italic, by tweaking the ~bold~ and
+~italic~ faces.  Cases where that can be useful include:
+
++ The default typeface does not have a variant with slanted glyphs
+  (e.g. Fira Mono/Code as of this writing on 2022-08-23), so the user
+  wants to add another family for the italics, such as Hack.
+
++ The typeface of choice provides a multitude of weights and the user
+  prefers the light one by default.  To prevent the bold weight from
+  being too heavy compared to the light one, they opt to make ~bold~ use a
+  semibold weight.
+
++ The typeface distinguishes between oblique and italic forms by
+  providing different font variants (the former are just slanted
+  versions of the upright forms, while the latter have distinguishing
+  features as well).  In this case, the user wants to specify the font
+  that applies to the ~italic~ face.
+
+To achieve those effects, one must first be sure that the fonts they use
+have support for those features.
+
+In this example, we set the default font family to Fira Code, while we
+choose to render italics in the Hack typeface (obviously one needs to
+pick fonts that work in tandem):
+
+#+begin_src emacs-lisp
+(set-face-attribute 'default nil :family "Fira Code" :height 110)
+(set-face-attribute 'italic nil :family "Hack")
+#+end_src
+
+And here we play with different weights, using Source Code Pro:
+
+#+begin_src emacs-lisp
+(set-face-attribute 'default nil :family "Source Code Pro" :height 110 :weight 
'light)
+(set-face-attribute 'bold nil :weight 'semibold)
+#+end_src
+
+To reset the font family, one can use this:
+
+#+begin_src emacs-lisp
+(set-face-attribute 'italic nil :family 'unspecified)
+#+end_src
+
+Consider the =fontaine= package on GNU ELPA (by Protesilaos) which
+provides the means to configure font families via faces.
+
+** Tweak =org-modern= timestamps
+:PROPERTIES:
+:CUSTOM_ID: h:8c88f697-a14e-468d-935c-7576934e7092
+:END:
+
+The =org-modern= package uses faces and text properties to make Org
+buffers more aesthetically pleasing.  It affects tables, timestamps,
+lists, headings, and more.
+
+In previous versions of the Standard themes, we mistakenly affected one of its
+faces: the ~org-modern-label~.  It changed the intended looks and
+prevented the user option ~org-modern-label-border~ from having its
+desired effect.  As such, we no longer override that face.
+
+Users who were used to the previous design and who generally do not
+configure the user options of =org-modern= may thus notice a change in
+how clocktables (or generally tables with timestamps) are aligned.  The
+simplest solution is to instruct the mode to not prettify timestamps, by
+setting the user option ~org-modern-timestamp~ to ~nil~.  For example, by
+adding this to the init file:
+
+#+begin_src emacs-lisp
+(setq org-modern-timestamp nil)
+#+end_src
+
+Alignment in tables will also depend on the use of proportionately
+spaced fonts.  Enable the relevant option to work with those without any
+further trouble ([[#h:a939ee30-f705-4d70-aa00-cca5528ef172][Enable mixed 
fonts]]).
+
+For any further issues, you are welcome to ask for help.
+
+** Tweak goto-address-mode faces
+:PROPERTIES:
+:CUSTOM_ID: h:7d0b7091-63d1-49b3-992d-cd24d3103782
+:END:
+
+The built-in ~goto-address-mode~ uses heuristics to identify URLs and
+email addresses in the current buffer.  It then applies a face to them
+to change their style.  Some packages, such as =notmuch=, use this
+minor-mode automatically.
+
+The faces are not declared with ~defface~, meaning that it is better
+that the theme does not modify them.  The user is thus encouraged to
+consider including this in their setup:
+
+#+begin_src emacs-lisp
+(setq goto-address-url-face 'link
+      goto-address-url-mouse-face 'highlight
+      goto-address-mail-face 'link
+      goto-address-mail-mouse-face 'highlight)
+#+end_src
+
+My personal preference is to set ~goto-address-mail-face~ to ~nil~,
+because it otherwise adds too much visual noise to the buffer (email
+addresses stand out more, due to the use of the uncommon =@= caharacter
+but also because they are often enclosed in angled brackets).
+
+* Faces defined by the Standard themes
+:PROPERTIES:
+:CUSTOM_ID: h:2553eaca-d9f7-4cb0-9b0b-63e1a22a40e7
+:END:
+
+The themes define some faces to make it possible to achieve
+consistency between various groups of faces.  For example, all "marks
+for selection" use the ~standard-themes-mark-select~ face.  If, say, the
+user wants to edit this face to include an underline, the change will
+apply to lots of packages, like Dired, Trashed, Ibuffer.
+
+[[#h:a4f7a8fb-11a5-4e32-897b-f930b7d5c043][Do-It-Yourself customizations]].
+
+All the faces defined by the themes:
+
++ ~standard-themes-bold~
++ ~standard-themes-fixed-pitch~
++ ~standard-themes-heading-0~
++ ~standard-themes-heading-1~
++ ~standard-themes-heading-2~
++ ~standard-themes-heading-3~
++ ~standard-themes-heading-4~
++ ~standard-themes-heading-5~
++ ~standard-themes-heading-6~
++ ~standard-themes-heading-7~
++ ~standard-themes-heading-8~
++ ~standard-themes-italic~
++ ~standard-themes-key-binding~
++ ~standard-themes-mark-delete~
++ ~standard-themes-mark-other~
++ ~standard-themes-mark-select~
++ ~standard-themes-ui-variable-pitch~
++ ~standard-themes-underline-error~
++ ~standard-themes-underline-info~
++ ~standard-themes-underline-warning~
+
+* Supported packages or face groups
+:PROPERTIES:
+:CUSTOM_ID: h:f954364c-bc23-4230-b8ac-d8804bdbabd9
+:END:
+
+The =standard-themes= will only ever support a curated list of packages based
+on my judgement ([[#h:52524f5a-633e-4e07-917d-06c6e663ec3f][Packages that are 
hard to support]]).  Nevertheless, the
+list of explicitly or implicitly supported packages already covers
+everything most users need.
+
+** Explicitly supported packages or face groups
+:PROPERTIES:
+:CUSTOM_ID: h:9b2458f1-6f70-4f45-849d-f10782c9f18f
+:END:
+
+- all basic faces
+- all-the-icons
+- all-the-icons-dired
+- all-the-icons-ibuffer
+- ansi-color
+- auctex
+- auto-dim-other-buffers
+- bongo
+- bookmark
+- calendar and diary
+- cider
+- change-log and log-view (part of VC)
+- chart
+- clojure-mode
+- company
+- compilation
+- completions
+- consult
+- corfu
+- custom (=M-x customize=)
+- denote
+- dictionary
+- diff-hl
+- diff-mode
+- dired
+- dired-subtree
+- diredfl
+- dirvish
+- display-fill-column-indicator-mode
+- doom-modeline
+- ediff
+- eglot
+- eldoc
+- elfeed
+- embark
+- epa
+- eshell
+- eww
+- flycheck
+- flymake
+- flyspell
+- font-lock
+- git-commit
+- git-rebase
+- gnus
+- hi-lock (=M-x highlight-regexp=)
+- ibuffer
+- image-dired
+- info
+- isearch, occur, query-replace
+- keycast
+- lin
+- line numbers (~display-line-numbers-mode~ and global variant)
+- magit
+- man
+- marginalia
+- markdown-mode
+- messages
+- mode-line
+- mu4e
+- neotree
+- notmuch
+- olivetti
+- orderless
+- org
+- org-habit
+- org-modern
+- outline-mode
+- outline-minor-faces
+- package (=M-x list-packages=)
+- perspective
+- pulsar
+- pulse
+- rainbow-delimiters
+- rcirc
+- recursion-indicator
+- regexp-builder (re-builder)
+- ruler-mode
+- selectrum
+- shell-script-mode (sh-mode)
+- show-paren-mode
+- shr
+- smerge
+- tab-bar-mode
+- tab-line-mode
+- tempel
+- term
+- textsec
+- transient
+- trashed
+- tree-sitter
+- tty-menu
+- vc (=vc-dir.el=, =vc-hooks.el=)
+- vertico
+- wgrep
+- which-function-mode
+- whitespace-mode
+- widget
+- writegood-mode
+- woman
+
+** Implicitly supported packages or face groups
+:PROPERTIES:
+:CUSTOM_ID: h:d98d4a5a-6bf0-43e7-b129-875fa05654e7
+:END:
+
+Those are known to work with the Standard themes either because their colors
+are appropriate or because they inherit from basic faces which the
+themes already cover:
+
+- apropos
+- dim-autoload
+- hl-todo
+- icomplete
+- ido
+- multiple-cursors
+- paren-face
+- which-key
+- xref
+
+Note that "implicitly supported" does not mean that they always fit in
+perfectly.  If there are refinements we need to made, then we need to
+intervene ([[#h:9b2458f1-6f70-4f45-849d-f10782c9f18f][Explicitly supported 
packages or face groups]]).
+
+** Packages that are hard to support
+:PROPERTIES:
+:CUSTOM_ID: h:52524f5a-633e-4e07-917d-06c6e663ec3f
+:END:
+
+These are difficult to support due to their (i) incompatibility with the
+design of the =standard-themes=, (ii) complexity or multiple points of entry,
+(iii) external dependencies, (iv) existence of better alternatives in my
+opinion, or (v) inconsiderate use of color out-of-the-box and implicit
+unwillingness to be good Emacs citizens:
+
+- avy :: its UI is prone to visual breakage and is hard to style
+  correctly.
+
+- calibredb :: has an external dependency that I don't use.
+
+- ctrlf :: use the built-in isearch or the ~consult-line~ command of
+  =consult=.
+
+- dired+ :: it is complex and makes inconsiderate use of color.
+
+- ein (Emacs IPython Notebook) :: external dependency that I don't use.
+
+- elfeed-goodies :: depends on =powerline=...
+
+- ement.el :: has an external dependency that I don't use.
+
+- helm :: it is complex and makes inconsiderate use of color.  Prefer
+  the =vertico=, =consult=, and =embark= packages.
+
+- info+ :: it is complex and makes inconsiderate use of color.
+
+- ivy/counsel/swiper :: use the =vertico=, =consult=, and =embark=
+  packages which are designed to be compatible with standard Emacs
+  mechanisms and are modular.
+
+- lsp-mode :: has external dependencies that I don't use.
+
+- powerline :: requires too many shades of background and generally
+  violates our expectation of how the mode-line is supposed to look by
+  placing the designated default background in unexpected places.
+
+- solaire :: in principle, it is incompatible with practically every
+  theme that is not designed around it.  Emacs does not distinguish
+  between "UI" and "syntax" buffers.
+
+- spaceline :: same as =powerline=.
+
+- sx :: has an external dependency that I don't use.
+
+- telega :: has an external dependency that I don't use (I don't even
+  have a smartphone).
+
+- telephone-line :: same as =powerline=.
+
+- treemacs :: it has too many dependencies and does too many things.
+
+- web-mode :: I don't use all those Web technologies and cannot test
+  this properly without support from an expert.  It also defines lots of
+  faces that hardcode color values for no good reason.
+
+The above list is non-exhaustive though you get the idea.
+
+* Acknowledgements
+:PROPERTIES:
+:CUSTOM_ID: h:9db21121-577d-43e5-8787-62739bfa5d83
+:END:
+
+#+cindex: Contributors
+
+This project is meant to be a collective effort.  Every bit of help
+matters.
+
++ Author/maintainer :: Protesilaos Stavrou.
+
++ Contributions to code or the manual :: Alex Lu, Christopher League,
+  Philip Kaludercic, Walheimat.
+
++ Ideas and/or user feedback :: Alan Schmitt, Anthony Chavez, Benjamin
+  (zealotrush), Daniel Mendler, Federico Stilman, Iris Garcia,
+  Jean-Philippe Gagné Guay, Jonas Collberg, Saša Janiška, Spike-Leung,
+  Steve Molitor, Summer Emacs, Sven Seebeck, Zoltán Király.
+
+* GNU Free Documentation License
+:PROPERTIES:
+:CUSTOM_ID: h:255fa624-6e3c-4118-9618-17cc25a801bd
+:END:
+
+#+texinfo: @include doclicense.texi
+
+#+begin_export html
+<pre>
+
+                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.
+</pre>
+#+end_export
+
+#+html: <!--
+
+* Indices
+:PROPERTIES:
+:CUSTOM_ID: h:3e760365-f83c-4631-b9ee-13b22de8a6d7
+:END:
+
+** Function index
+:PROPERTIES:
+:INDEX: fn
+:CUSTOM_ID: h:c137a71c-b29d-4fd5-a48b-d81c7abc1e86
+:END:
+
+** Variable index
+:PROPERTIES:
+:INDEX: vr
+:CUSTOM_ID: h:b31c615f-6c2e-4778-af97-22ac02db2170
+:END:
+
+** Concept index
+:PROPERTIES:
+:INDEX: cp
+:CUSTOM_ID: h:4bec8826-9a86-47cb-ae99-d6b4743edac3
+:END:
+
+#+html: -->
diff --git a/doclicense.texi b/doclicense.texi
new file mode 100644
index 0000000000..eaf3da0e92
--- /dev/null
+++ b/doclicense.texi
@@ -0,0 +1,505 @@
+@c The GNU Free Documentation License.
+@center Version 1.3, 3 November 2008
+
+@c This file is intended to be included within another document,
+@c hence no sectioning command or @node.
+
+@display
+Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, 
Inc.
+@uref{https://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{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.
+
+@item
+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, La@TeX{} 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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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:
+
+@enumerate A
+@item
+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.
+
+@item
+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.
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+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.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+Delete any section Entitled ``Endorsements''.  Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
+@item
+Preserve any Warranty Disclaimers.
+@end enumerate
+
+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.
+
+@item
+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.''
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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
+@uref{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.
+
+@item
+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.
+
+@end enumerate
+
+@page
+@heading 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:
+
+@smallexample
+@group
+  Copyright (C)  @var{year}  @var{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''.
+@end group
+@end smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with@dots{}Texts.''@: line with this:
+
+@smallexample
+@group
+    with the Invariant Sections being @var{list their titles}, with
+    the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+    being @var{list}.
+@end group
+@end smallexample
+
+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.
+
+@c Local Variables:
+@c ispell-local-pdict: "ispell-dict"
+@c End: