Merge remote-tracking branch 'origin/master' into pr-830

1 files changed, 91 insertions, 114 deletions

diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi
index 2b868564372..a11416a470c 100644
--- a/doc/misc/use-package.texi
+++ b/doc/misc/use-package.texi
@@ -8,7 +8,7 @@
 
 @copying
 @quotation
-Copyright (C) 2012-2022 John Wiegley <johnw@@newartisans.com>
+Copyright (C) 2012-2022 Free Software Foundation, Inc.
 
 You can redistribute this document and/or modify it under the terms
 of the GNU General Public License as published by the Free Software
@@ -31,7 +31,7 @@ General Public License for more details.
 @finalout
 @titlepage
 @title use-package User Manual
-@subtitle for version 2.4.1-81-gb185c6b+1
+@subtitle for version 2.4.1-119-g0be480e+1
 @author John Wiegley
 @page
 @vskip 0pt plus 1filll
@@ -45,9 +45,9 @@ General Public License for more details.
 @top use-package User Manual
 
 The @code{use-package} macro allows you to isolate package configuration in your
-@code{.emacs} file in a way that is both performance-oriented and, well, tidy. I
+@code{.emacs} file in a way that is both performance-oriented and, well, tidy.  I
 created it because I have over 80 packages that I use in Emacs, and things
-were getting difficult to manage. Yet with this utility my total load time is
+were getting difficult to manage.  Yet with this utility my total load time is
 around 2 seconds, with no loss of functionality!
 
 @insertcopying
@@ -67,33 +67,33 @@ around 2 seconds, with no loss of functionality!
 
 Installation
 
-* Installing from an Elpa Archive::
+* Installing from GNU ELPA::
 * Installing from the Git Repository::
 * Post-Installation Tasks::
 
 Keywords
 
-* @code{after}::
-* @code{bind-keymap}, @code{bind-keymap*}: @code{bind-keymap} @code{bind-keymap*}. 
-* @code{bind}, @code{bind*}: @code{bind} @code{bind*}. 
-* @code{commands}::
-* @code{preface}, @code{init}, @code{config}: @code{preface} @code{init} @code{config}. 
-* @code{custom}::
-* @code{custom-face}::
-* @code{defer}, @code{demand}: @code{defer} @code{demand}. 
-* @code{defines}, @code{functions}: @code{defines} @code{functions}. 
-* @code{diminish}, @code{delight}: @code{diminish} @code{delight}. 
-* @code{disabled}::
-* @code{ensure}, @code{pin}: @code{ensure} @code{pin}. 
-* @code{hook}::
-* @code{if}, @code{when}, @code{unless}: @code{if} @code{when} @code{unless}. 
-* @code{load-path}::
-* @code{mode}, @code{interpreter}: @code{mode} @code{interpreter}. 
-* @code{magic}, @code{magic-fallback}: @code{magic} @code{magic-fallback}. 
-* @code{no-require}::
-* @code{requires}::
-
-@code{:bind}, @code{:bind*}
+* @code{after}:: @code{:after}.
+* @code{bind-keymap} @code{bind-keymap*}:: @code{:bind-keymap}, @code{:bind-keymap*}.
+* @code{bind} @code{bind*}:: @code{:bind}, @code{:bind*}.
+* @code{commands}:: @code{:commands}.
+* @code{preface} @code{init} @code{config}:: @code{:preface}, @code{:init}, @code{:config}.
+* @code{custom}:: @code{:custom}.
+* @code{custom-face}:: @code{:custom-face}.
+* @code{defer} @code{demand}:: @code{:defer}, @code{:demand}.
+* @code{defines} @code{functions}:: @code{:defines}, @code{:functions}.
+* @code{diminish} @code{delight}:: @code{:diminish}, @code{:delight}.
+* @code{disabled}:: @code{:disabled}.
+* @code{ensure} @code{pin}:: @code{:ensure}, @code{:pin}.
+* @code{hook}:: @code{:hook}.
+* @code{if} @code{when} @code{unless}:: @code{:if}, @code{:when}, @code{:unless}.
+* @code{load-path}:: @code{:load-path}.
+* @code{mode} @code{interpreter}:: @code{:mode}, @code{:interpreter}.
+* @code{magic} @code{magic-fallback}:: @code{:magic}, @code{:magic-fallback}.
+* @code{no-require}:: @code{:no-require}.
+* @code{requires}:: @code{:requires}.
+
+@code{bind}, @code{bind*}
 
 * Binding to local keymaps::
 
@@ -105,9 +105,9 @@ Keywords
 @chapter Introduction
 
 The @code{use-package} macro allows you to isolate package configuration in your
-@code{.emacs} file in a way that is both performance-oriented and, well, tidy. I
+@code{.emacs} file in a way that is both performance-oriented and, well, tidy.  I
 created it because I have over 80 packages that I use in Emacs, and things
-were getting difficult to manage. Yet with this utility my total load time is
+were getting difficult to manage.  Yet with this utility my total load time is
 around 2 seconds, with no loss of functionality!
 
 More text to come@dots{}
@@ -119,50 +119,27 @@ use-package can be installed using Emacs' package manager or manually from
 its development repository.
 
 @menu
-* Installing from an Elpa Archive::
+* Installing from GNU ELPA::
 * Installing from the Git Repository::
 * Post-Installation Tasks::
 @end menu
 
-@node Installing from an Elpa Archive
-@section Installing from an Elpa Archive
+@node Installing from GNU ELPA
+@section Installing from GNU ELPA
 
-use-package is available from Melpa and Melpa-Stable. If you haven't used
+use-package is available from GNU ELPA.  If you haven't used
 Emacs' package manager before, then it is high time you familiarize yourself
 with it by reading the documentation in the Emacs manual, see
-@ref{Packages,,,emacs,}. Then add one of the archives to @code{package-archives}:
+@ref{Packages,,,emacs,}.  Then add one of the archives to @code{package-archives}:
 
-@itemize
-@item
-To use Melpa:
-@end itemize
-
-@lisp
-(require 'package)
-(add-to-list 'package-archives
-             '("melpa" . "https://melpa.org/packages/") t)
-@end lisp
-
-@itemize
-@item
-To use Melpa-Stable:
-@end itemize
-
-@lisp
-(require 'package)
-(add-to-list 'package-archives
-             '("melpa-stable" . "https://stable.melpa.org/packages/") t)
-@end lisp
-
-Once you have added your preferred archive, you need to update the
-local package list using:
+First, you need to update the local package list using:
 
 @example
 M-x package-refresh-contents RET
 @end example
 
-Once you have done that, you can install use-package and its dependencies
-using:
+Once you have done that, you can install use-package and its
+dependencies using:
 
 @example
 M-x package-install RET use-package RET
@@ -229,7 +206,7 @@ Now see @ref{Post-Installation Tasks}.
 @section Post-Installation Tasks
 
 After installing use-package you should verify that you are indeed using the
-use-package release you think you are using. It's best to restart Emacs before
+use-package release you think you are using.  It's best to restart Emacs before
 doing so, to make sure you are not using an outdated value for @code{load-path}.
 
 @example
@@ -239,7 +216,7 @@ C-h v use-package-version RET
 should display something like
 
 @example
-use-package-version’s value is "2.4.1"
+use-package-version’s value is "2.4.3"
 @end example
 
 If you are completely new to use-package then see @ref{Getting Started}.
@@ -249,13 +226,13 @@ If you run into problems, then please see the @ref{Debugging Tools}.
 @node Getting Started
 @chapter Getting Started
 
-TODO@. For now, see @code{README.md}.
+TODO@.  For now, see @code{README.md}.
 
 @node Basic Concepts
 @chapter Basic Concepts
 
 @code{use-package} was created for few basic reasons, each of which drove the
-design in various ways. Understanding these reasons may help make some of
+design in various ways.  Understanding these reasons may help make some of
 those decisions clearer:
 
 @itemize
@@ -279,7 +256,7 @@ close to a functional Emacs as possible.
 
 @item
 To allow byte-compilation of one's init file so that any warnings or
-errors seen are meaningful. In this way, even if byte-compilation is not
+errors seen are meaningful.  In this way, even if byte-compilation is not
 used for speed (reason 3), it can still be used as a sanity check.
 @end itemize
 
@@ -290,25 +267,25 @@ used for speed (reason 3), it can still be used as a sanity check.
 @chapter Keywords
 
 @menu
-* @code{after}::
-* @code{bind-keymap}, @code{bind-keymap*}: @code{bind-keymap} @code{bind-keymap*}. 
-* @code{bind}, @code{bind*}: @code{bind} @code{bind*}. 
-* @code{commands}::
-* @code{preface}, @code{init}, @code{config}: @code{preface} @code{init} @code{config}. 
-* @code{custom}::
-* @code{custom-face}::
-* @code{defer}, @code{demand}: @code{defer} @code{demand}. 
-* @code{defines}, @code{functions}: @code{defines} @code{functions}. 
-* @code{diminish}, @code{delight}: @code{diminish} @code{delight}. 
-* @code{disabled}::
-* @code{ensure}, @code{pin}: @code{ensure} @code{pin}. 
-* @code{hook}::
-* @code{if}, @code{when}, @code{unless}: @code{if} @code{when} @code{unless}. 
-* @code{load-path}::
-* @code{mode}, @code{interpreter}: @code{mode} @code{interpreter}. 
-* @code{magic}, @code{magic-fallback}: @code{magic} @code{magic-fallback}. 
-* @code{no-require}::
-* @code{requires}::
+* @code{after}:: @code{after}.
+* @code{bind-keymap} @code{bind-keymap*}:: @code{:bind-keymap}, @code{:bind-keymap*}.
+* @code{bind} @code{bind*}:: @code{bind} @code{:bind*}.
+* @code{commands}:: @code{:commands}.
+* @code{preface} @code{init} @code{config}:: @code{:preface}, @code{:init}, @code{:config}.
+* @code{custom}:: @code{:custom}.
+* @code{custom-face}:: @code{:custom-face}.
+* @code{defer} @code{demand}:: @code{:defer}, @code{:demand}.
+* @code{defines} @code{functions}:: @code{:defines}, @code{:functions}.
+* @code{diminish} @code{delight}:: @code{:diminish}, @code{:delight}.
+* @code{disabled}:: @code{:disabled}.
+* @code{ensure} @code{pin}:: @code{:ensure}, @code{:pin}.
+* @code{hook}:: @code{:hook}.
+* @code{if} @code{when} @code{unless}:: @code{:if}, @code{:when}, @code{:unless}.
+* @code{load-path}:: @code{:load-path}.
+* @code{mode} @code{interpreter}:: @code{:mode}, @code{:interpreter}.
+* @code{magic} @code{magic-fallback}:: @code{:magic}, @code{:magic-fallback}.
+* @code{no-require}:: @code{:no-require}.
+* @code{requires}:: @code{:requires}.
 @end menu
 
 @node @code{after}
@@ -316,8 +293,8 @@ used for speed (reason 3), it can still be used as a sanity check.
 
 Sometimes it only makes sense to configure a package after another has been
 loaded, because certain variables or functions are not in scope until that
-time. This can achieved using an @code{:after} keyword that allows a fairly rich
-description of the exact conditions when loading should occur. Here is an
+time.  This can achieved using an @code{:after} keyword that allows a fairly rich
+description of the exact conditions when loading should occur.  Here is an
 example:
 
 @lisp
@@ -332,13 +309,13 @@ example:
 @end lisp
 
 In this case, because all of these packages are demand-loaded in the order
-they occur, the use of @code{:after} is not strictly necessary. By using it,
+they occur, the use of @code{:after} is not strictly necessary.  By using it,
 however, the above code becomes order-independent, without an implicit
 depedence on the nature of your init file.
 
 By default, @code{:after (foo bar)} is the same as @code{:after (:all foo bar)}, meaning
 that loading of the given package will not happen until both @code{foo} and @code{bar}
-have been loaded. Here are some of the other possibilities:
+have been loaded.  Here are some of the other possibilities:
 
 @lisp
 :after (foo bar)
@@ -354,7 +331,7 @@ been loaded, or both @code{baz} and @code{quux} have been loaded.
 
 @strong{NOTE}: Pay attention if you set @code{use-package-always-defer} to t, and also use
 the @code{:after} keyword, as you will need to specify how the declared package is
-to be loaded: e.g., by some @code{:bind}. If you're not using one of the mechanisms
+to be loaded: e.g., by some @code{:bind}.  If you're not using one of the mechanisms
 that registers autoloads, such as @code{:bind} or @code{:hook}, and your package manager
 does not provide autoloads, it's possible that without adding @code{:demand t} to
 those declarations, your package will never be loaded.
@@ -363,14 +340,14 @@ those declarations, your package will never be loaded.
 @section @code{:bind-keymap}, @code{:bind-keymap*}
 
 Normally @code{:bind} expects that commands are functions that will be autoloaded
-from the given package. However, this does not work if one of those commands
+from the given package.  However, this does not work if one of those commands
 is actually a keymap, since keymaps are not functions, and cannot be
 autoloaded using Emacs' @code{autoload} mechanism.
 
 To handle this case, @code{use-package} offers a special, limited variant of
-@code{:bind} called @code{:bind-keymap}. The only difference is that the "commands"
+@code{:bind} called @code{:bind-keymap}.  The only difference is that the "commands"
 bound to by @code{:bind-keymap} must be keymaps defined in the package, rather than
-command functions. This is handled behind the scenes by generating custom code
+command functions.  This is handled behind the scenes by generating custom code
 that loads the package containing the keymap, and then re-executes your
 keypress after the first load, to reinterpret that keypress as a prefix key.
 
@@ -409,7 +386,7 @@ A more literal way to do the exact same thing is:
 @end lisp
 
 When you use the @code{:commands} keyword, it creates autoloads for those commands
-and defers loading of the module until they are used. Since the @code{:init} form
+and defers loading of the module until they are used.  Since the @code{:init} form
 is always run---even if @code{ace-jump-mode} might not be on your system---remember
 to restrict @code{:init} code to only what would succeed either way.
 
@@ -425,7 +402,7 @@ The @code{:bind} keyword takes either a cons or a list of conses:
 The @code{:commands} keyword likewise takes either a symbol or a list of symbols.
 
 NOTE: Special keys like @code{tab} or @code{F1}-@code{Fn} can be written in square brackets,
-i.e. @code{[tab]} instead of @code{"tab"}. The syntax for the keybindings is similar to
+i.e. @code{[tab]} instead of @code{"tab"}.  The syntax for the keybindings is similar to
 the "kbd" syntax: see @uref{https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Rebinding.html, the Emacs Manual} for more information.
 
 Examples:
@@ -459,7 +436,7 @@ The effect of this statement is to wait until @code{helm} has loaded, and then t
 bind the key @code{C-c h} to @code{helm-execute-persistent-action} within Helm's local
 keymap, @code{helm-mode-map}.
 
-Multiple uses of @code{:map} may be specified. Any binding occurring before the
+Multiple uses of @code{:map} may be specified.  Any binding occurring before the
 first use of @code{:map} are applied to the global keymap:
 
 @lisp
@@ -493,7 +470,7 @@ Here is the simplest @code{use-package} declaration:
 @end lisp
 
 This loads in the package @code{foo}, but only if @code{foo} is available on your
-system. If not, a warning is logged to the @code{*Messages*} buffer. If it
+system.  If not, a warning is logged to the @code{*Messages*} buffer.  If it
 succeeds, a message about @code{"Loading foo"} is logged, along with the time it
 took to load, if it took over 0.1 seconds.
 
@@ -567,14 +544,14 @@ The @code{:custom-face} keyword allows customization of package custom faces.
 @node @code{defer} @code{demand}
 @section @code{:defer}, @code{:demand}
 
-In almost all cases you don't need to manually specify @code{:defer t}. This is
-implied whenever @code{:bind} or @code{:mode} or @code{:interpreter} is used. Typically, you
+In almost all cases you don't need to manually specify @code{:defer t}.  This is
+implied whenever @code{:bind} or @code{:mode} or @code{:interpreter} is used.  Typically, you
 only need to specify @code{:defer} if you know for a fact that some other package
 will do something to cause your package to load at the appropriate time, and
 thus you would like to defer loading even though use-package isn't creating
 any autoloads for you.
 
-You can override package deferral with the @code{:demand} keyword. Thus, even if
+You can override package deferral with the @code{:demand} keyword.  Thus, even if
 you use @code{:bind}, using @code{:demand} will force loading to occur immediately and
 not establish an autoload for the bound key.
 
@@ -616,7 +593,7 @@ If you need to silence a missing function warning, you can use @code{:functions}
 @section @code{:diminish}, @code{:delight}
 
 @code{use-package} also provides built-in support for the diminish and delight
-utilities---if you have them installed. Their purpose is to remove or change
+utilities---if you have them installed.  Their purpose is to remove or change
 minor mode strings in your mode-line.
 
 @uref{https://github.com/myrjola/diminish.el, diminish} is invoked with the @code{:diminish} keyword, which is passed either a
@@ -635,7 +612,7 @@ package name with "-mode" appended at the end:
 @uref{https://elpa.gnu.org/packages/delight.html, delight} is invoked with the @code{:delight} keyword, which is passed a minor mode
 symbol, a replacement string or quoted @uref{https://www.gnu.org/software/emacs/manual/html_node/elisp/Mode-Line-Data.html, mode-line data} (in which case the minor
 mode symbol is guessed to be the package name with "-mode" appended at the
-end), both of these, or several lists of both. If no arguments are provided,
+end), both of these, or several lists of both.  If no arguments are provided,
 the default mode name is hidden completely.
 
 @lisp
@@ -677,7 +654,7 @@ from the output entirely, to accelerate startup times.
 @node @code{ensure} @code{pin}
 @section @code{:ensure}, @code{:pin}
 
-You can use @code{use-package} to load packages from ELPA with @code{package.el}. This
+You can use @code{use-package} to load packages from ELPA with @code{package.el}.  This
 is particularly useful if you share your @code{.emacs} among several machines; the
 relevant packages are downloaded automatically once declared in your @code{.emacs}.
 The @code{:ensure} keyword causes the package(s) to be installed automatically if
@@ -707,7 +684,7 @@ archives is also a valid use-case.
 By default @code{package.el} prefers @code{melpa} over @code{melpa-stable} due to the
 versioning @code{(> evil-20141208.623 evil-1.0.9)}, so even if you are tracking
 only a single package from @code{melpa}, you will need to tag all the non-@code{melpa}
-packages with the appropriate archive. If this really annoys you, then you can
+packages with the appropriate archive.  If this really annoys you, then you can
 set @code{use-package-always-pin} to set a default.
 
 If you want to manually keep a package updated and ignore upstream updates,
@@ -752,7 +729,7 @@ Example:
 @section @code{:hook}
 
 The @code{:hook} keyword allows adding functions onto hooks, here only the basename
-of the hook is required. Thus, all of the following are equivalent:
+of the hook is required.  Thus, all of the following are equivalent:
 
 @lisp
 (use-package ace-jump-mode
@@ -827,8 +804,8 @@ the same thing as @code{:if (not foo)}.
 @section @code{:load-path}
 
 If your package needs a directory added to the @code{load-path} in order to load,
-use @code{:load-path}. This takes a symbol, a function, a string or a list of
-strings. If the path is relative, it is expanded within
+use @code{:load-path}.  This takes a symbol, a function, a string or a list of
+strings.  If the path is relative, it is expanded within
 @code{user-emacs-directory}:
 
 @lisp
@@ -839,8 +816,8 @@ strings. If the path is relative, it is expanded within
 
 Note that when using a symbol or a function to provide a dynamically generated
 list of paths, you must inform the byte-compiler of this definition so the
-value is available at byte-compilation time. This is done by using the special
-form @code{eval-and-compile} (as opposed to @code{eval-when-compile}). Further, this
+value is available at byte-compilation time.  This is done by using the special
+form @code{eval-and-compile} (as opposed to @code{eval-when-compile}).  Further, this
 value is fixed at whatever was determined during compilation, to avoid looking
 up the same information again on each startup:
 
@@ -859,7 +836,7 @@ up the same information again on each startup:
 
 Similar to @code{:bind}, you can use @code{:mode} and @code{:interpreter} to establish a
 deferred binding within the @code{auto-mode-alist} and @code{interpreter-mode-alist}
-variables. The specifier to either keyword can be a cons cell, a list of cons
+variables.  The specifier to either keyword can be a cons cell, a list of cons
 cells, or a string or regexp:
 
 @lisp
@@ -898,8 +875,8 @@ This does exactly the same thing as the following:
 
 Similar to @code{:mode} and @code{:interpreter}, you can also use @code{:magic} and
 @code{:magic-fallback} to cause certain function to be run if the beginning of a
-file matches a given regular expression. The difference between the two is
-that @code{:magic-fallback} has a lower priority than @code{:mode}. For example:
+file matches a given regular expression.  The difference between the two is
+that @code{:magic-fallback} has a lower priority than @code{:mode}.  For example:
 
 @lisp
 (use-package pdf-tools
@@ -918,9 +895,9 @@ string @code{"%PDF"}.
 
 Normally, @code{use-package} will load each package at compile time before
 compiling the configuration, to ensure that any necessary symbols are in scope
-to satisfy the byte-compiler. At times this can cause problems, since a
+to satisfy the byte-compiler.  At times this can cause problems, since a
 package may have special loading requirements, and all that you want to use
-@code{use-package} for is to add a configuration to the @code{eval-after-load} hook. In
+@code{use-package} for is to add a configuration to the @code{eval-after-load} hook.  In
 such cases, use the @code{:no-require} keyword:
 
 @lisp
@@ -936,8 +913,8 @@ such cases, use the @code{:no-require} keyword:
 While the @code{:after} keyword delays loading until the dependencies are loaded,
 the somewhat simpler @code{:requires} keyword simply never loads the package if the
 dependencies are not available at the time the @code{use-package} declaration is
-encountered. By "available" in this context it means that @code{foo} is available
-of @code{(featurep 'foo)} evaluates to a non-nil value. For example:
+encountered.  By "available" in this context it means that @code{foo} is available
+of @code{(featurep 'foo)} evaluates to a non-nil value.  For example:
 
 @lisp
 (use-package abbrev