changing repositories

1 files changed, 1903 insertions, 0 deletions

diff --git a/assets/info/use-package.texi.files/use-package.texi b/assets/info/use-package.texi.files/use-package.texi
new file mode 100644
index 00000000..b1d7b100
--- /dev/null
+++ b/assets/info/use-package.texi.files/use-package.texi
@@ -0,0 +1,1903 @@
+\input texinfo    @c -*- texinfo -*-
+@c %**start of header
+@setfilename ../../use-package.info
+@settitle use-package User Manual
+@include docstyle.texi
+@syncodeindex vr cp
+@syncodeindex fn cp
+@c %**end of header
+
+@copying
+This manual is for use-package, a configuration macro for simplifying
+your init file.
+
+Copyright @copyright{} 2022 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with 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 quotation
+@end copying
+
+@dircategory Emacs misc features
+@direntry
+* use-package: (use-package). Declarative package configuration for Emacs.
+@end direntry
+
+@finalout
+@titlepage
+@title use-package User Manual
+@subtitle for version 2.4.5
+@author John Wiegley & Stefan Kangas
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top use-package User Manual
+
+The @code{use-package} macro allows you to isolate package
+customization in your init file in a declarative way.  It takes care
+of a lot of things for you that would otherwise require a lot of
+repetitive boilerplate code.  It can help with common customization,
+such as binding keys, setting up hooks, customizing user options and
+faces, autoloading, and more.  It also helps you keep Emacs startup
+fast, even when you use many (even hundreds) of packages.
+
+Note that use-package is not a package manager.  Although use-package
+does have the useful capability to interface with the Emacs package
+manager, its primary purpose is for the configuration and loading of
+packages.
+
+@insertcopying
+
+@menu
+* Basic Concepts::              Basic concepts of use-package.
+* Getting Started::             A gentle introduction to use-package.
+* Loading Packages::            How and when packages are loaded.
+* Configuring Packages::        Package configuration keywords.
+* Installing packages::         Ensuring packages are available.
+* Byte-compiling::              Byte-compiling your init file.
+* Troubleshooting::             What to do when there's trouble.
+
+Appendices
+* Keyword extensions::          Adding new use-package keywords.
+* History::                     History and acknowledgments.
+* GNU Free Documentation License::  The license for this manual.
+* Index::
+@end menu
+@end ifnottex
+
+@c ----------------------------------------------------------------------------
+@node Basic Concepts
+@chapter Basic Concepts
+
+use-package provides the @code{use-package} macro, that simplifies the
+customization and use of packages in Emacs.  It was created for a few
+basic reasons, each of which drove the design.  Understanding these
+reasons may help make some of those decisions clearer:
+
+@enumerate
+@item
+To gather all configuration details of a package into one place,
+making it easier to copy, disable, or move it elsewhere in the init
+file.
+
+@item
+To reduce duplication and boilerplate, capturing several common
+practices as mere keywords both easy and intuitive to use.
+
+@item
+To make startup time of Emacs as quick as possible, without
+sacrificing the quantity of add-on packages used.
+
+@item
+To make it so errors encountered during startup disable only the
+package raising the error, and as little else as possible, leaving as
+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 used for speed (reason 3), it can still be used as a sanity check.
+@end enumerate
+
+It is worth noting that use-package is not intended to replace the
+standard @w{@code{M-x customize}}.  On the contrary, it is designed to
+work together with it, for things that customize cannot do.
+
+@c ----------------------------------------------------------------------------
+@node Getting Started
+@chapter Getting Started
+
+This chapter provides instructions and examples for quickly getting
+started with use-package.  The first thing you need to do is make sure
+that @samp{use-package} itself is loaded.  To do that, put this at the
+top of your init file:
+
+@lisp
+(require 'use-package)
+@end lisp
+
+The above makes the @code{use-macro} for in the rest of your init
+file.  In this manual, we call each call to @code{use-macro} a
+@dfn{declaration}, to highlight the declarative nature of its
+semantic.
+
+To unconditionally load a package named @samp{foo}, add the following
+declaration to your init file:
+
+@lisp
+(use-package foo)
+@end lisp
+
+@noindent
+This declaration is equivalent to using @code{require}, with some
+use-package specific error handling added in.  Just like require, it
+needs the package @samp{foo} to be installed and available in your
+@code{load-path} (@pxref{Installing packages}).
+
+To evaluate Lisp code @emph{before} the @samp{foo} package is loaded,
+use the @code{:init} keyword:
+
+@lisp
+(use-package foo
+  :init
+  (setq foo-variable t))
+@end lisp
+
+Similarly, @code{:config} can be used to execute code @emph{after} a
+package is loaded.  In cases where loading is done lazily
+(@pxref{Loading Packages}), this execution is deferred until after the
+autoload occurs.  As you might expect, you can use @code{:init} and
+@code{:config} together:
+
+@lisp
+(use-package foo
+  :init
+  (setq foo-variable t)
+  :config
+  (foo-mode 1))
+@end lisp
+
+The above declarations will all load the @samp{foo} package
+immediately.  In most cases, this is not necessary or desirable, as
+that will slow down Emacs startup.  Instead, you should try to set
+things up so that packages are only loaded when they are actually
+needed (autoloading).  If you have installed a package from
+@acronym{GNU ELPA} that provides it's own autoloads, it is often
+enough to say:
+
+@lisp
+(use-package foo
+  :defer t)
+@end lisp
+
+@noindent
+This will avoid loading the package.  Now, when you run any autoloaded
+command, the package @samp{foo} is loaded automatically.  Package
+authors will make their own decisions about which commands are marked
+to autoload by default.
+
+In some cases, you might need or want to provide your own autoloads.
+The below more complex example autoloads the commands
+@code{isearch-moccur} and @code{isearch-all} from
+@file{color-moccur.el}, and binds keys both globally and in
+@code{isearch-mode-map}.  When one of these commands are used, the
+package is loaded.  At that point, @code{moccur-edit} is also loaded,
+to allow editing of the @code{moccur} buffer.
+
+@lisp
+(use-package color-moccur
+  :commands (isearch-moccur isearch-all)
+  :bind (("M-s O" . moccur)
+         :map isearch-mode-map
+         ("M-o" . isearch-moccur)
+         ("M-O" . isearch-moccur-all))
+  :init
+  (setq isearch-lazy-highlight t)
+  :config
+  (use-package moccur-edit))
+@end lisp
+
+Some packages will suggest ready-made @code{use-package} declarations
+that you can use.  Where possible, it is a good idea to copy them, and
+use that as a starting point.
+
+That should be enough to get you started!
+
+@c ----------------------------------------------------------------------------
+@node Loading Packages
+@chapter Loading Packages
+
+@cindex loading packages
+Before use-package can load an Emacs Lisp package, it must be
+available in a directory on your @code{load-path}.  When you install
+packages using the built-in @code{install-package} command, it will do
+this automatically for you.  Packages shipped with Emacs (built-in
+packages) are always available.
+
+If you install packages manually, you must make sure they are
+available on your @code{load-path}.  @xref{Lisp Libraries,,, emacs,
+GNU Emacs Manual} for details.
+
+Some packages have more than one library.  In those cases, you might
+need more than one @code{use-package} declaration to make sure it is
+properly loaded.  For complex configurations, you might also need more
+than one declaration for a package with the same name.
+
+use-package can interface with @samp{package.el} to install packages
+on Emacs start.  @xref{Installing packages} for details.
+
+@menu
+* Loading basics::              How and when packages are loaded.
+* Deferring loading::           Loading packages later.
+* Forcing loading::             Loading packages immediately.
+* Conditional loading::         Loading packages conditionally.
+* Loading sequentially::        Loading packages in sequence.
+* Load dependencies::           Don't load without dependencies.
+* Load path::                   Using a custom @code{load-path}.
+* Manual autoloads::            Setting up autoloads manually.
+@end menu
+
+@node Loading basics
+@section How and when use-package loads packages
+
+The @code{use-package} macro either will either load a package
+immediately, or when they are first used (autoloading).  In the
+simplest case, a @code{use-package} declaration loads a package when
+it is evaluated.@footnote{This happens both at run-time and at
+compile-time.  @xref{Byte-compiling}.}  If the declaration is in your
+init file, this happens automatically each time Emacs is started.
+
+For example, the below declaration immediately loads the library
+@code{foo}, just like @code{require} would.  If the library @samp{foo}
+is not available in your @code{load-path}, it logs a warning to the
+@samp{*Messages*} buffer:
+
+@lisp
+(use-package foo)
+@end lisp
+
+Note that a ``package'' is different from an Emacs Lisp ``library''.
+The above declaration tells use-package to load the @emph{library}
+@file{foo.el}, which the overwhelming majority of cases also resides
+in a @emph{package} named @code{foo}.  But the @code{foo} package
+might also contain a library named @file{foo-extra.el}.  If that
+library is not loaded automatically, you will need a separate
+@code{use-package} declaration to make sure that it is.  This manual
+will often use these terms interchangeably, as this distinction does
+not usually matter, but you should keep it in mind for the cases when
+it does.
+
+The details of how and when you should load a package might differ
+from one package to another.  When in doubt, refer to the package
+documentation for details.
+
+@node Deferring loading
+@section Deferring package loading
+
+@cindex autoloading packages
+@cindex loading lazily
+In the examples we have seen so far, use-package loads packages every
+time you start Emacs, even if that package is never used.  That will
+make starting Emacs slower.  use-package therefore tries to set things
+up in such a way that it only loads packages when a command is first
+used (either with @kbd{M-x} or some key binding).  This is based on
+autoloading, a full description of which is outside the scope of this
+manual.  @xref{Autoload,,, elisp, GNU Emacs Lisp Reference Manual} for
+the full story.
+
+@cindex triggers, for loading packages
+Some @code{use-package} keywords provide autoload @dfn{triggers} that
+cause a package to be loaded when certain events occur.  For example,
+the @code{:hook} keyword sets up a trigger that fires when the
+specified hook is run, and then loads the package automatically.  The
+other trigger keywords, all of which are described later in this
+manual, are @code{:commands}, @code{:bind}, @code{:bind*},
+@code{:bind-keymap}, @code{:bind-keymap*}, @code{:mode}, and
+@code{:interpreter}.
+
+@subheading The @code{:defer} keyword
+
+@findex :defer
+If you did not specify any autoloading keyword, use-package will fall
+back to loading the package immediately (typically when Emacs is
+starting up).  This can be overridden using the @code{:defer} keyword.
+It takes one boolean argument: a non-@code{nil} value means to stop
+this package from being immediately loaded.  Here is an example of
+using @code{:defer} to postpone loading the package @samp{foo}:
+
+@lisp
+(use-package foo
+  :defer t)
+@end lisp
+
+Using @code{:defer t} by itself like this is rarely useful.
+Typically, you would only use it together with a keyword like
+@code{:config} (@pxref{Lisp Configuration}), or @code{:ensure}
+(@pxref{Installing packages}).
+
+@subheading Defer loading until idle for N seconds
+
+You can also give a numeric argument @var{N} to @w{@code{:defer}} to
+specify that a package should be loaded (if it hasn't already) after
+Emacs has been idle for @var{N} seconds.  For example, use this to
+make use-package load @samp{foo} after 30 seconds of idle time:
+
+@lisp
+(use-package foo
+  :defer 30)
+@end lisp
+
+@subheading When to use @code{:defer}
+
+When using autoloading keywords, there is no need to also use
+@code{:defer}.  It doesn't hurt anything to add it in this case,
+perhaps for extra clarity, but it is redundant.
+
+You should use @code{:defer} to force deferred loading, in cases when
+use-package isn't creating any autoloads for you.  For example, you
+might know that some other package will already do something to cause
+your package to load at the appropriate time.  This is usually the
+case when you install a package using @code{package-install}, as
+packages installed in this way normally always have their own
+autoloads already set up.
+
+@subheading Making @w{@code{:defer t}} the default
+
+@vindex use-package-always-defer
+If you customize the user option @code{use-package-always-defer} to
+non-@code{nil}, the @code{use-package} macro will behave as if
+@w{@code{:defer t}} is always specified.  This can be overridden for
+individual declarations using either @w{@code{:defer nil}} or
+@w{@code{:demand t}} (@pxref{Forcing loading}).
+
+@node Forcing loading
+@section Forcing package to load immediately
+
+@findex :demand
+The presence of autoloading trigger keywords can be overridden using
+@code{:demand t}, which forces the package to load immediately.  Thus,
+even if you use an autoloading keyword such as @code{:bind}
+(@pxref{Key bindings}), adding @code{:demand} will force loading to
+occur immediately.  It will also avoid creating an autoload for the
+bound key, as it would be redundant.
+
+If you specify both @w{@code{:demand t}} and @w{@code{:defer t}}, the
+@code{:defer} keyword will take precedence.
+
+@node Conditional loading
+@section Loading packages conditionally
+
+@findex :if
+@findex :when
+@findex :unless
+The @code{:if}, @code{:when}, and @code{:unless} keywords predicates
+the loading and initialization of packages.  They all accept one
+argument, an Emacs Lisp form that is evaluated at run-time.
+
+If the argument of the @code{:if} keyword evaluates to non-@code{nil},
+the package will be loaded and initialized.  The @code{:when} keyword
+is provided as an alias for @code{:if}.  Finally, the @code{:unless}
+keyword is the inverse of @code{:if}, such that @w{@code{:unless foo}}
+means the same thing as @w{@code{:if (not foo)}}.
+
+For example, if you only want to load @samp{foo} in graphical Emacs
+sessions, you could use the following:
+
+@lisp
+(use-package foo
+  :if (display-graphic-p))
+@end lisp
+
+@subheading Some common use cases
+
+Here are some common cases for conditional loading, and how to achieve
+them.
+
+@itemize
+
+@item Operating system
+
+This example loads a package only on GNU/Linux.  See the
+@code{system-type} docstring for other valid values.
+
+@lisp
+:if (eq system-type 'gnu/linux)
+@end lisp
+
+@item Window system
+
+This example loads a package only on macOS and X.  See the
+@code{window-system} docstring for valid values.
+
+@lisp
+:if (memq window-system '(ns x))
+@end lisp
+
+@item Installed package
+
+This example loads a package only when the @samp{foo} package is
+installed.
+
+@lisp
+:if (package-installed-p 'foo)
+@end lisp
+
+@item Libraries in @code{load-path}
+
+This example loads a package only when @file{foo.el} is available in
+your @code{load-path} (for example, if you installed that file
+manually):
+
+@lisp
+:if (locate-library "foo.el")
+@end lisp
+@end itemize
+
+@subheading Making conditional loading affect @code{:preface} and @code{:ensure}
+
+@cindex conditional loading before @code{:preface} or @code{:ensure}
+If you need to conditionalize a use-package form so that the condition
+occurs before even @code{:ensure} or @code{:preface}, use @code{when}
+around the use-package form itself.  For example:
+
+@lisp
+(when (memq window-system '(mac ns))
+  (use-package foo
+    :ensure t))
+@end lisp
+
+@node Loading sequentially
+@section Loading packages in sequence
+
+@findex :after
+Sometimes it only makes sense to configure a package after another one
+has been loaded, because certain variables or functions are not in
+scope until that time.  This can achieved with the @code{:after}
+keyword, which allows a fairly rich description of the exact
+conditions when loading should occur.  It takes either a symbol
+indicating the package name, a list of such symbols, or a list of
+selectors (see below).
+
+Here is an example of using the @acronym{GNU ELPA} packages hydra,
+ivy, and ivy-hydra.  Note that ivy-hydra will always be loaded last:
+
+@lisp
+(use-package hydra)
+
+(use-package ivy)
+
+(use-package ivy-hydra
+  :after (ivy hydra))
+@end lisp
+
+In this case, because the declarations are evaluated in the order they
+occur, the use of @code{:after} is not strictly necessary.  However,
+if @samp{hydra} and @samp{ivy} were to be autoloaded, using
+@code{:after} guarantees that @samp{ivy-hydra} is not loaded until it
+is actually needed.  By using @code{:after}, the above code will also
+work even if the order of the declaration changes.  This means that
+moving things around in your init file is less likely to break things.
+
+@subheading Using @code{:after} selectors
+
+@findex :all (with :after)
+@findex :any (with :after)
+The @code{:after} keyword also accepts a list of selectors.  By
+default, @code{:after (foo bar)} is the same as @w{@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:
+
+@verbatim
+:after (foo bar)
+:after (:all foo bar)
+:after (:any foo bar)
+:after (:all (:any foo bar) (:any baz quux))
+:after (:any (:all foo bar) (:all baz quux))
+@end verbatim
+
+When you nest selectors, such as @code{(:any (:all foo bar) (:all baz
+quux))}, it means that the package will be loaded when either both
+@code{foo} and @code{bar} have been loaded, or when both @code{baz}
+and @code{quux} have been loaded.
+
+Pay attention when setting @code{use-package-always-defer} to a
+non-@code{nil} value, and also using the @code{:after} keyword.  In
+this case, you will need to specify how the declared package is to be
+loaded: for example, by some @code{:bind}.  If you are not using one
+of the keywords that registers autoloads, such as @code{:bind} or
+@code{:hook}, and your package manager does not provide autoloads, it
+is possible that your package will never be loaded if you do not add
+@code{:demand t} to those declarations.
+
+@node Load dependencies
+@section Prevent loading if dependencies are missing
+
+@findex :requires
+While the @code{:after} keyword delays loading until the dependencies
+are loaded, the somewhat simpler @code{:requires} keyword @emph{never}
+loads the package if the dependencies are not available when the
+@code{use-package} declaration is evaluated.  In this context,
+``available'' means that @code{foo} is available if @w{@code{(featurep
+'foo)}} evaluates to a non-@code{nil} value.  For example:
+
+@lisp
+(use-package abbrev
+  :requires foo)
+@end lisp
+
+This is the same as:
+
+@lisp
+(use-package abbrev
+  :if (featurep 'foo))
+@end lisp
+
+As a convenience, a list of such packages may be specified:
+
+@lisp
+(use-package abbrev
+  :requires (foo bar baz))
+@end lisp
+
+For more complex logic, such as that supported by @code{:after},
+simply use @code{:if} and the appropriate Lisp expression.
+
+@node Load path
+@section Setting a custom @code{load-path}
+
+@findex :load-path
+If a package resides in some directory that is not in your
+@code{load-path}, use the @code{:load-path} keyword to add it.  It
+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}.
+
+For example:
+
+@lisp
+(use-package ess-site
+  :load-path "site-lisp/ess/lisp/"
+  :commands R)
+@end lisp
+
+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 that 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 fixed at
+whatever was determined during compilation, to avoid looking up the
+same information again on each startup.  For example:
+
+@lisp
+(eval-and-compile
+  (defun ess-site-load-path ()
+    (shell-command "find ~ -path ess/lisp")))
+
+(use-package ess-site
+  :load-path (lambda () (list (ess-site-load-path)))
+  :commands R)
+@end lisp
+
+@node Manual autoloads
+@section Setting up autoloads manually
+
+@findex :commands
+@findex :autoload
+To autoload an interactive command, use the @code{:commands} keyword.
+When you use the @code{:commands} keyword, it creates autoloads for
+those commands (which defers loading of the module until they are
+used).  The @code{:commands} keyword takes either a symbol or a list
+of symbols.
+
+The @code{:autoload} keyword works like @code{:commands}, but is used
+to autoload non-interactive functions.  Here is an example:
+
+@lisp
+(use-package org-crypt
+  :autoload org-crypt-use-before-save-magic)
+@end lisp
+
+@c ----------------------------------------------------------------------------
+@node Configuring Packages
+@chapter Configuring Packages
+
+This chapter describes the various keywords provided by
+@code{use-package} that helps you configure packages.
+
+@menu
+* Lisp Configuration::          Using Lisp to configure packages.
+* Key bindings::                Making your own keybindings.
+* Hooks::                       Adding functions to hooks.
+* Modes and interpreters::      Enabling modes automatically.
+* Magic handlers::              Using regexps to enable modes.
+* User options::                Setting user options.
+* Faces::                       Customizing faces.
+* Hiding minor modes::          Tidying up the mode line.
+@end menu
+
+@node Lisp Configuration
+@section Using Lisp code for configuring packages
+
+The most general way to add customizations are the @code{:preface},
+@code{:init}, and @code{:config} keywords.  They all accept one or
+more Emacs Lisp forms, up to the next keyword, that are evaluated in
+order.  This lets you add arbitrary Lisp code to your
+@code{use-package} declarations.
+
+The only difference between these keywords is when they are evaluated.
+
+@menu
+* Preface keyword::             Evaluate code before anything else.
+* Init keyword::                Evaluate code before loading package.
+* Config keyword::              Evaluate code after loading package.
+* Best practices::              When to use @code{:config}, @code{:init}, and @code{:preface}.
+@end menu
+
+@node Preface keyword
+@subsection @code{:preface} is evaluated first
+
+@findex :preface
+The @code{:preface} section is evaluated before anything else, except
+@code{:disabled} and @code{:ensure}.  It can be used to establish
+function and variable definitions that will:
+
+@enumerate
+@item
+Make the byte-compiler happy.  It will not complain about functions
+whose definitions are unknown because you have them within a guard
+block.
+
+@item
+Define code that can be used in an @code{:if} test.
+@end enumerate
+
+Note that whatever is specified within @code{:preface} is evaluated
+both at load time and at byte-compilation time, in order to ensure
+that definitions are seen by both the Lisp evaluator and the
+byte-compiler.  Therefore, you should avoid having any side-effects in
+your preface, and restrict it to symbol declarations and definitions.
+
+@node Init keyword
+@subsection @code{:init} is evaluated before loading package
+
+@findex :init
+The @code{:init} section is evaluated just before the package is
+loaded.  Note that the @code{:init} form is run unconditionally --
+even if the @code{foo} package happens to not exist on your system.
+You must therefore remember to restrict @code{:init} code to only what
+would succeed either way.  @code{:init} also always happens before
+package load, whether @code{:config} has been deferred or not.
+
+@node Config keyword
+@subsection @code{:config} is evaluated after loading package
+
+@findex :config
+The @code{:config} section is evaluated after the package has been
+loaded.  If the package is loaded immediately, this happens
+immediately after that, but if loading is done lazily (@pxref{Loading
+Packages}), this is deferred until after the package has been loaded.
+
+In general, you should keep @code{:init} forms as simple and quick as
+possible, and put as much as you can get away with into the
+@code{:config} section.  That way, deferred loading can help your
+Emacs start as quickly as possible.
+
+@node Best practices
+@subheading When to use @code{:preface}, @code{:config} and @code{:init}?
+
+Where possible, it is better to avoid @code{:preface}, @code{:config}
+and @code{:init}.  Instead, prefer autoloading keywords such as
+@code{:bind}, @code{:hook}, and @code{:mode}, as they will take care
+of setting up autoloads for you without any need for boilerplate code.
+For example, consider the following declaration:
+
+@lisp
+(use-package foo
+  :init
+  (add-hook 'some-hook 'foo-mode))
+@end lisp
+
+This has two problems.  First, it will unconditionally load the
+package @samp{foo} on startup, which will make things slower.  You can
+fix this by adding @code{:defer t}:
+
+@lisp
+(use-package foo
+  :defer t
+  :init
+  (add-hook 'some-hook 'foo-mode))
+@end lisp
+
+This is better, as @samp{foo} is now only loaded when it is actually
+needed (that is, when the hook @samp{some-hook} is run).
+
+The second problem is that there is a lot of boilerplate that you have
+to write.  In this case, it might not be so bad, but avoiding that was
+what use-package was made to avoid.  The better option in this case is
+therefore to use @code{:hook} (@xref{Hooks}), which also implies
+@w{@code{:defer t}}.  The above is thereby reduced down to:
+
+@lisp
+(use-package foo
+  :hook some-hook)
+@end lisp
+
+use-package will set up autoloading for you, and your Emacs startup
+time will not suffer one bit.
+
+@node Key bindings
+@section Key bindings
+
+@cindex :bind
+@cindex binding keys
+@cindex key bindings
+One common thing to do when loading a package is to bind a key to
+commands within that module.  Without use-package, this would be done
+using a combination of @code{keymap-local-set},
+@code{keymap-global-set} and various autoloads.  With use-package, you
+can simplify this using the @code{:bind} keyword.
+
+@menu
+* Global keybindings::          Bindings you can use anywhere.
+* Binding in keymaps::          Bindings for particular modes.
+* Binding to a keymap::         Binding a key to a keymap.
+* Binding to repeat-maps::      Binding repeating keys.
+* Displaying keybindings::      Displaying personal key bindings.
+@end menu
+
+@node Global keybindings
+@subsection Global keybindings
+
+@findex :bind
+To bind keys globally, the @code{:bind} keyword takes as its argument
+either a single cons or a list of conses.  Each cons has the form
+@w{@code{(@var{key} . @var{definition})}}, where @var{key} is a string
+indicating the key to bind, and @var{definition} is the name of a
+command (a symbol).  Alternatively, @var{definition} may be a cons
+@w{@code{(@var{desc} . @var{command})}}, where @var{desc} is a string
+describing @var{command}, which is the name of a command to bind
+@var{key} to.  The syntax for the keys is similar to the syntax used
+by the @code{kbd} function (see @ref{Init Rebinding,,, emacs, GNU
+Emacs Manual}, for more information).
+
+@subheading Using @code{:bind} with a single cons
+
+Here is an example of using a single cons:
+
+@lisp
+(use-package ace-jump-mode
+  :bind ("C-." . ace-jump-mode))
+@end lisp
+
+This does two things: first, it creates an autoload for the
+@code{ace-jump-mode} command and defers loading of the
+@code{ace-jump-mode} package until you actually use it.  Second, it
+binds the key @code{C-.} to that command globally.
+
+@subheading Using @code{:bind} with a list of conses
+
+Here is an example of using @code{:bind} with a list of conses:
+
+@lisp
+(use-package hi-lock
+  :bind (("M-o l" . highlight-lines-matching-regexp)
+         ("M-o r" . highlight-regexp)
+         ("M-o w" . highlight-phrase)))
+@end lisp
+
+@subheading Using special keys
+
+Inside key strings, special keys like @kbd{TAB} or @kbd{F1}--@kbd{F12}
+have to be written inside angle brackets, e.g.  @code{"C-<up>"}.
+Standalone special keys (and some combinations) can be written in
+square brackets, e.g.@ @code{[tab]} instead of @code{"<tab>"}.
+
+Examples:
+
+@lisp
+(use-package helm
+  :bind (("M-x" . helm-M-x)
+         ("M-<f5>" . helm-find-files)
+         ([f10] . helm-buffers-list)
+         ([S-f10] . helm-recentf)))
+@end lisp
+
+@subheading Providing custom descriptions of commands
+
+When binding keys to commands with @code{:bind}, custom descriptions
+of the commands may optionally be provided.
+
+Examples:
+
+@lisp
+@group
+(use-package avy
+  :bind ("C-:" ("Jump to char" . avy-goto-char)
+         "M-g f" ("Jump to line" . avy-goto-line)))
+@end group
+@end lisp
+
+@noindent
+These descriptions can be used by other code that deals with key
+bindings.  For example, the @acronym{GNU} @acronym{ELPA} package
+@file{which-key} displays them when showing key bindings, instead of
+the plain command names.
+
+@subheading Remapping commands
+
+Remapping commands with @code{:bind} and @code{bind-key} works as
+expected, because when the binding is a vector, it is passed straight
+to @code{define-key}.  @xref{Remapping Commands,,, elisp, GNU Emacs
+Lisp Reference Manual}) for more information about command remapping.
+For example, the following declaration will rebind
+@code{fill-paragraph} (bound to @kbd{M-q} by default) to
+@code{unfill-toggle}:
+
+@lisp
+(use-package unfill
+  :bind ([remap fill-paragraph] . unfill-toggle))
+@end lisp
+
+@subheading What @code{:bind} does behind the scenes
+
+To understand what @code{:bind} does behind the scenes, it might be
+useful to consider an example:
+
+@lisp
+(use-package ace-jump-mode
+  :bind ("C-." . ace-jump-mode))
+@end lisp
+
+This could be expressed in a much more verbose way with the
+@code{:commands} and @code{:init} keywords.
+
+@lisp
+(use-package ace-jump-mode
+  :commands ace-jump-mode
+  :init
+  (bind-key "C-." 'ace-jump-mode))
+@end lisp
+
+Without using even the @code{:commands} keyword, we could also write
+the above like so:
+
+@lisp
+(use-package ace-jump-mode
+  :defer t
+  :init
+  (autoload 'ace-jump-mode "ace-jump-mode" nil t)
+  (bind-key "C-." 'ace-jump-mode))
+@end lisp
+
+Although these three forms are all equivalent, the first form is
+usually the best, as it will save some typing.
+
+@node Binding in keymaps
+@subsection Key bindings in local keymaps
+
+@findex :map, inside :bind
+Slightly different from binding a key to a keymap, is binding a key
+@emph{within} a local keymap that only exists after the package is
+loaded.  @code{use-package} supports this with a @code{:map} modifier,
+taking the local keymap to bind to:
+
+@lisp
+(use-package helm
+  :bind (:map helm-command-map
+         ("C-c h" . helm-execute-persistent-action)))
+@end lisp
+
+The effect of this statement is to wait until @code{helm} has loaded,
+and then to bind the key @code{C-c h} to
+@code{helm-execute-persistent-action} within Helm's local keymap,
+@code{helm-command-map}.
+
+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
+(use-package term
+  :bind (("C-c t" . term)
+         :map term-mode-map
+         ("M-p" . term-send-up)
+         ("M-n" . term-send-down)
+         :map term-raw-map
+         ("M-o" . other-window)
+         ("M-p" . term-send-up)
+         ("M-n" . term-send-down)))
+@end lisp
+
+@node Binding to a keymap
+@subsection Binding to keymaps
+
+@findex :bind-keymap, inside :bind
+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 is actually a keymap, since keymaps are not functions,
+and cannot be autoloaded using the built-in @code{autoload} function.
+
+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'' 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 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.
+
+For example:
+
+@lisp
+(use-package foo
+  :bind-keymap ("C-c p" . foo-command-map))
+@end lisp
+
+@node Binding to repeat-maps
+@subsection Binding to repeat-maps
+
+@findex :repeat-map, inside :bind
+@cindex repeat-mode and use-package, using
+A special case of binding within a local keymap is when that keymap is
+used by @code{repeat-mode} @pxref{Repeating,,, emacs, GNU Emacs
+Manual}.  These keymaps are usually defined specifically for
+this.  Using the @code{:repeat-map} keyword, and passing it a name for
+the map it defines, will bind all following keys inside that map, and
+(by default) set the @code{repeat-map} property of each bound command
+to that map.
+
+The following example creates a keymap called
+@code{git-gutter+-repeat-map}, makes four bindings in it as above,
+then sets the @code{repeat-map} property of each bound command
+(@code{git-gutter+-next-hunk} @code{git-gutter+-previous-hunk},
+@code{git-gutter+-stage-hunks} and @code{git-gutter+-revert-hunk}) to
+that keymap.
+
+@lisp
+(use-package git-gutter+
+  :bind
+  (:repeat-map git-gutter+-repeat-map
+   ("n" . git-gutter+-next-hunk)
+   ("p" . git-gutter+-previous-hunk)
+   ("s" . git-gutter+-stage-hunks)
+   ("r" . git-gutter+-revert-hunk)))
+@end lisp
+
+@findex :exit, inside :repeat-map and :bind
+Specifying @code{:exit} inside the scope of @code{:repeat-map} will
+prevent the @code{repeat-map} property being set, so that the command
+can be used from within the repeat map, but after it using it the repeat
+map will no longer be available.  This is useful for commands often used
+at the end of a series of repeated commands:
+
+@lisp
+(use-package git-gutter+
+  :bind
+  (:repeat-map my/git-gutter+-repeat-map
+   ("n" . git-gutter+-next-hunk)
+   ("p" . git-gutter+-previous-hunk)
+   ("s" . git-gutter+-stage-hunks)
+   ("r" . git-gutter+-revert-hunk)
+   :exit
+   ("c" . magit-commit-create)
+   ("C" . magit-commit)
+   ("b" . magit-blame)))
+@end lisp
+
+@findex :continue, inside :repeat-map and :bind
+Specifying @code{:continue} @emph{forces} setting the
+@code{repeat-map} property (just like @emph{not} specifying
+@code{:exit}), so the above snippet is equivalent to:
+
+@lisp
+(use-package git-gutter+
+  :bind
+  (:repeat-map my/git-gutter+-repeat-map
+   :exit
+   ("c" . magit-commit-create)
+   ("C" . magit-commit)
+   ("b" . magit-blame)
+   :continue
+   ("n" . git-gutter+-next-hunk)
+   ("p" . git-gutter+-previous-hunk)
+   ("s" . git-gutter+-stage-hunks)
+   ("r" . git-gutter+-revert-hunk)))
+@end lisp
+
+@node Displaying keybindings
+@subsection Displaying personal keybinding
+
+@findex describe-personal-keybindings
+The @code{:bind} keyword uses the @code{bind-keys} macro from the
+@samp{bind-key.el} library to set up keybindings.  It keeps track of
+all keybindings you make, so that you can display them separately from
+the default keybindings.
+
+Use @w{@code{M-x describe-personal-keybindings}} to see all
+keybindings you've set using either the @code{:bind} keyword or the
+@code{bind-keys} macro.
+
+@node Hooks
+@section Hooks
+
+@cindex hooks
+@findex :hook
+The @code{:hook} keyword allows adding functions onto hooks.  It takes
+one argument of the form @var{hooks}, specifying one or more functions
+to add to one or more hooks.  For the purposes of @code{:hook}, the
+name of hook variables should always exclude the @samp{-hook} suffix.
+It is appended automatically for you, to save some typing.
+
+For example, consider the following @code{use-package} declaration
+that sets up autoloads for @code{company-mode} from the @samp{company}
+package, and adds @samp{company-mode} to @code{prog-mode-hook}:
+
+@lisp
+(use-package company
+  :commands company-mode
+  :init
+  (add-hook 'prog-mode-hook #'company-mode))
+@end lisp
+
+Using @code{:hook}, this can be simplified to:
+
+@lisp
+(use-package company
+  :hook (prog-mode . company-mode))
+@end lisp
+
+Here, @code{:hook} will automatically set up autoloads for the
+@code{company-mode} command, so there is no need to use
+@code{:commands}.
+
+The @code{:hook} keyword will also assume that the name of the
+function you want to add is the same as the package name with
+@samp{-mode} appended to it.  Taking this into account, you can
+simplify the above to the equivalent:
+
+@lisp
+(use-package company
+  :hook prog-mode)
+@end lisp
+
+@cindex multiple hooks
+You can also provide a list of hooks.  When multiple hooks should be
+applied, the following examples are all equivalent:
+
+@lisp
+(use-package company
+  :hook (prog-mode text-mode))
+
+(use-package company
+  :hook ((prog-mode text-mode) . company-mode))
+
+(use-package company
+  :hook ((prog-mode . company-mode)
+         (text-mode . company-mode)))
+
+(use-package company
+  :commands company-mode
+  :init
+  (add-hook 'prog-mode-hook #'company-mode)
+  (add-hook 'text-mode-hook #'company-mode))
+@end lisp
+
+One common mistake when using @code{:hook} is to forget to omit the
+@samp{-hook} suffix, which, as already explained, is appended
+automatically.  Therefore, the following will not work, as it attempts
+to add a function to non-existent @code{prog-mode-hook-hook}:
+
+@lisp
+;; DOES NOT WORK
+(use-package ace-jump-mode
+  :hook (prog-mode-hook . ace-jump-mode))
+@end lisp
+
+@vindex use-package-hook-name-suffix
+If you do not like this behavior, you can customize the user option
+@code{use-package-hook-name-suffix} to @code{nil}.  The value of this
+variable is @samp{"-hook"} by default.
+
+The use of @code{:hook}, as with @code{:bind}, @code{:mode},
+@code{:interpreter}, etc., causes the functions being hooked to
+implicitly be read as @code{:commands}.  This means that they will
+establish interactive @code{autoload} definitions for that module, if
+not already defined as functions), and so @code{:defer t} is also
+implied by @code{:hook}.
+
+@node Modes and interpreters
+@section Modes and interpreters
+
+@findex :mode
+@findex :interpreter
+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
+cells, or a string or regexp.
+
+The following example reproduces the default @code{ruby-mode}
+configuration, exactly as it is in Emacs out-of-the-box.  That mode is
+enabled automatically when a file whose name matches the regexp
+@code{"\\.rb\\'"} (a file with the @samp{.rb} extension), or when the
+first line of the file (known as the ``shebang'') matches the string
+@code{"ruby"}:
+
+@lisp
+(use-package ruby-mode
+  :mode "\\.rb\\'"
+  :interpreter "ruby")
+@end lisp
+
+The default @code{python-mode} configuration can be reproduced using
+the below declaration.  Note that the package that should be loaded
+differs from the mode name in this case, so we must use a cons:
+
+@lisp
+;; The package is "python" but the mode is "python-mode":
+(use-package python
+  :mode ("\\.py\\'" . python-mode)
+  :interpreter ("python" . python-mode))
+@end lisp
+
+Both the @code{:mode} and @code{:interpreter} keywords also accept a
+list of regexps:
+
+@lisp
+(use-package foo
+  ;; Equivalent to "\\(ba[rz]\\)\\'":
+  :mode ("\\.bar\\'" "\\.baz\\'")
+  ;; Equivalent to "\\(foo[ab]\\)":
+  :interpreter ("fooa" "foob"))
+@end lisp
+
+@node Magic handlers
+@section Magic handlers
+
+@findex :magic
+@findex :magic-fallback
+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 @code{:magic} and @code{:magic-fallback}, is
+that the latter has a lower priority than @code{:mode}.
+
+Here is an example:
+
+@lisp
+(use-package pdf-tools
+  :magic ("%PDF" . pdf-view-mode)
+  :config
+  (pdf-tools-install :no-query))
+@end lisp
+
+This registers an autoloaded command for @code{pdf-view-mode}, defers
+loading of @code{pdf-tools}, and runs @code{pdf-view-mode} if the
+beginning of a buffer matches the string @code{"%PDF"}.
+
+@node User options
+@section User options
+
+@findex :custom
+In Emacs, you normally set customizable variables (user options) using
+the @code{M-x customize} interface (@pxref{Easy Customization,,,
+emacs, GNU Emacs Manual}).  We recommended this method for most users.
+However, it is also possible to set them in your @code{use-package}
+declarations by using the @code{:custom} keyword.
+
+@lisp
+(use-package comint
+  :defer t
+  :custom
+  (comint-buffer-maximum-size 20000 "Increase comint buffer size.")
+  (comint-prompt-read-only t "Make the prompt read only."))
+@end lisp
+
+This is better than using @code{setq} in a @code{:config} block, as
+customizable variables might have some code associated with it that
+Emacs will execute when you assign values to them.  In Emacs 29, there
+is also the new @code{setopt} macro that does this for you.
+
+Note that the values customized using this keyword are @emph{not}
+saved in the standard Emacs @code{custom-file}.  You should therefore
+set each user option using either the @code{:custom} keyword @emph{or}
+@w{@code{M-x customize-option}}, which will save customized values in
+the Emacs @code{custom-file}.  Do not use both for the same variable,
+as this risk having conflicting values in your use-package declaration
+and your @code{custom-file}.  This can lead to problems that are both
+tricky and tedious to debug.
+
+@node Faces
+@section Faces
+
+@findex :custom-face
+The @code{:custom-face} keyword allows customization of package custom
+faces.
+
+@lisp
+(use-package eruby-mode
+  :custom-face
+  (eruby-standard-face ((t (:slant italic)))))
+
+(use-package example
+  :custom-face
+  (example-1-face ((t (:foreground "LightPink"))))
+  (example-2-face ((t (:foreground "LightGreen"))) face-defspec-spec))
+
+(use-package zenburn-theme
+  :preface
+  (setq my/zenburn-colors-alist
+        '((fg . "#DCDCCC") (bg . "#1C1C1C") (cyan . "#93E0E3")))
+  :custom-face
+  (region ((t (:background ,(alist-get my/zenburn-colors-alist 'cyan)))))
+  :config
+  (load-theme 'zenburn t))
+@end lisp
+
+@node Hiding minor modes
+@section Hiding minor modes with diminish and delight
+
+@code{use-package} supports the diminish and delight packages, both of
+which make it possible remove or change minor mode strings in your
+mode-line.  Which one to use is up to you, but you should normally
+only use one or the other -- never both.@footnote{When in doubt, you
+might as well use diminish.}  To use either of them, you must first
+install the corresponding package from @acronym{GNU ELPA}.
+
+@menu
+* Diminish::                    Hiding minor modes with Diminish.
+* Delight::                     Hiding minor modes with Delight.
+@end menu
+
+@node Diminish
+@subsection Diminish
+
+@findex :diminish
+When diminish@footnote{The diminish package is installable from
+@acronym{GNU ELPA}.} is installed, you can use the @code{:diminish}
+keyword.  If diminish is not installed, the @code{:diminish} keyword
+does nothing.
+
+First, add the following declaration to the beginning of your init
+file.  The optional @w{@code{:ensure t}} makes sure the package is
+installed if it isn't already (@pxref{Installing packages}).
+
+@lisp
+(use-package diminish :ensure t)
+@end lisp
+
+The @code{:diminish} keyword takes either a minor mode symbol, a cons
+of the symbol and its replacement string, or just a replacement
+string, in which case the minor mode symbol is guessed to be the
+package name with @samp{-mode} appended at the end:
+
+@lisp
+(use-package abbrev
+  :diminish abbrev-mode
+  :config
+  (if (file-exists-p abbrev-file-name)
+      (quietly-read-abbrev-file)))
+@end lisp
+
+@node Delight
+@subsection Delight
+
+@findex :delight
+When delight@footnote{The @samp{delight} package is installable from
+GNU ELPA.} is installed, you can use the @code{:delight} keyword.  If
+delight is not installed, the @code{:delight} keyword does nothing.
+
+First, add the following declaration to the beginning of your init
+file.  The optional @w{@code{:ensure t}} makes sure the package is
+installed if it isn't already (@pxref{Installing packages}).
+
+@lisp
+(use-package delight :ensure t)
+@end lisp
+
+The @code{:delight} keyword takes a minor mode symbol, a replacement
+string, or quoted mode line data (in which case the minor mode symbol
+is assumed to be the package name with @samp{-mode} appended at the
+end), both of these, or several lists of both.  @xref{Mode Line
+Data,,, elisp, GNU Emacs Lisp Reference Manual}.  If no arguments are
+provided, the default mode name is hidden completely.
+
+For example, the following hides everything for the @samp{foo-mode}
+minor mode in the @samp{foo} package:
+
+@lisp
+(use-package foo
+  :delight)
+@end lisp
+
+If the mode name doesn't match the package name with @samp{-mode}
+appended, provide a symbol instead.  For example, the following hides
+@code{auto-revert-mode} from the mode line:
+
+@lisp
+;; Don't show anything for auto-revert-mode, which doesn't match
+;; its package name.
+(use-package autorevert
+  :delight auto-revert-mode)
+@end lisp
+
+You can also run arbitrary Lisp code.  For example, to replace
+@samp{foo-mode} with the value of the current buffer:
+
+@lisp
+(use-package foo
+  :delight '(:eval buffer-file-name))
+@end lisp
+
+Here is an example of hiding several built-in minor modes:
+
+@lisp
+;; Completely hide visual-line-mode and change auto-fill-mode to " AF".
+(use-package emacs
+  :delight
+  (auto-fill-function " AF")
+  (visual-line-mode))
+@end lisp
+
+@c ----------------------------------------------------------------------------
+@node Installing packages
+@chapter Installing packages automatically
+
+The standard Emacs package manager is documented in the Emacs manual
+(@pxref{Package Installation,,, emacs, GNU Emacs Manual}).  The
+@code{use-package} macro provides the @code{:ensure} and @code{:pin}
+keywords, that interface with that package manager to automatically
+install packages.  This is particularly useful if you use your init
+file on more than one system.
+
+@menu
+* Install package::
+* Pinning packages::
+* Other package managers::
+@end menu
+
+@node Install package
+@section Installing package
+
+@findex :ensure
+The @code{:ensure} keyword makes use-package ask the Emacs package
+manager to install a package if it is not already present on your
+system.
+
+For example:
+
+@lisp
+(use-package magit
+  :ensure t)
+@end lisp
+
+If you need to install a different package from the one named by
+@code{use-package}, you can use a symbol:
+
+@lisp
+(use-package tex
+  :ensure auctex)
+@end lisp
+
+You can customize the user option @code{use-package-always-ensure} to
+non-@code{nil} if you want this behavior to be global for all
+packages.
+
+@lisp
+(require 'use-package-ensure)
+(setq use-package-always-ensure t)
+@end lisp
+
+@noindent
+You can override the above setting for a single package by adding
+@w{@code{:ensure nil}} to its declaration.
+
+@node Pinning packages
+@section Pinning packages using @code{:pin}
+
+@findex :pin
+use-package can pin a package to a specific archive using the
+@code{:pin} keyword.@footnote{The @code{:pin} keyword has no effect on
+Emacs versions older than 24.4.}  This allows you to mix and match
+packages from different archives.  The primary use-case for this is
+preferring to install packages from @acronym{GNU ELPA} or
+@acronym{NonGNU ELPA} (indicated by @code{gnu} and @code{nongnu},
+respectively), while installing specific packages from third-party
+archives.
+
+For example:
+
+@lisp
+(use-package company
+  :ensure t
+  :pin gnu)   ; GNU ELPA
+@end lisp
+
+@vindex use-package-always-pin
+Unfortunately, the third-party archive @acronym{MELPA} uses a
+versioning scheme based on dates, which means that packages from that
+archive are always preferred.  If you are using that archive, we
+strongly encourage you to customize @code{use-package-always-pin} to
+@code{nongnu}.  This guarantees that you are using a version of that
+package that has been specifically marked for release by its
+developer, and not a development snapshot.
+
+@c FIXME: This needs clarifying.  AFAIK, :ensure does not update packages.
+If you want to manually keep a package updated and ignore upstream
+updates, you can pin it to @samp{manual}.  This will work as long as
+you have not customized a repository to use that name in the
+@code{package-archives} variable.
+
+Example:
+
+@lisp
+(use-package org
+  :ensure t
+  ;; ignore org-mode from upstream and use a manually installed version
+  :pin manual)
+@end lisp
+
+@code{use-package} signals an error if you try to pin a package to an
+archive that is not configured using @code{package-archives} (except
+from the special @samp{manual} archive).
+
+@node Other package managers
+@section Non-standard package managers
+
+By default, use-package assumes that you are using the built-in
+@code{package.el} package manager.  We expect that most users will
+find that it is more than capable enough, even for advanced use cases.
+
+@vindex use-package-ensure-function
+However, some users might prefer to use a third-party package manager
+for a specific circumstance or use case.  By setting the user option
+@code{use-package-ensure-function} to the name of a function, you can
+direct @code{:ensure} to use a different package manager for
+installing packages.
+
+For more details, please see the documentation of the package manager
+you are using.  If you run into any bugs, it is often best to report
+them directly to the developers of that package manager.
+
+@c ----------------------------------------------------------------------------
+@node Byte-compiling
+@chapter Byte-compiling your init file
+
+Some users might want to byte-compile their init file to make Emacs
+startup even faster.  This is not recommended in most cases, as the
+speed-up is often too small to be worth it, and can lead to confusion
+if the byte-compiled files are out-of-date.  If you still want to do
+it, read on.
+
+@code{use-package} always loads every library that it can while a file
+is being byte-compiled.  This helps silence spurious warnings about
+unknown variables and functions.
+
+@findex :defines
+@findex :functions
+However, there are times when this is just not enough.  For those
+times, use the @code{:defines} and @code{:functions} keywords to
+introduce dummy variable and function declarations solely for the sake
+of silencing byte-compiler warnings.  For example:
+
+@lisp
+(use-package texinfo
+  :defines texinfo-section-list
+  :commands texinfo-mode
+  :init
+  (add-to-list 'auto-mode-alist '("\\.texi$" . texinfo-mode)))
+@end lisp
+
+If you need to silence a missing function warning, you can use
+@code{:functions}:
+
+@lisp
+(use-package ruby-mode
+  :mode "\\.rb\\'"
+  :interpreter "ruby"
+  :functions inf-ruby-keys
+  :config
+  (defun my-ruby-mode-hook ()
+    (require 'inf-ruby)
+    (inf-ruby-keys))
+
+  (add-hook 'ruby-mode-hook 'my-ruby-mode-hook))
+@end lisp
+
+@findex :no-require
+@cindex prevent a package from loading at compile-time
+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 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 such cases, use
+the @code{:no-require} keyword:
+
+@lisp
+(use-package foo
+  :no-require t
+  :config
+  (message "Evaluate this immediately after loading `foo'"))
+@end lisp
+
+@c ----------------------------------------------------------------------------
+@node Troubleshooting
+@chapter Troubleshooting
+
+@cindex troubleshooting
+@cindex debugging
+If an error occurs while initializing or configuring a package, this
+will not stop your Emacs from loading.  Instead, @code{use-package}
+captures the error and reports it in a special @code{*Warnings*} popup
+buffer, so that you can debug the situation in an otherwise functional
+Emacs.
+
+If you are having trouble when starting Emacs, you can pass Emacs the
+@samp{--debug-init} command line flag.  @xref{Initial Options,,,
+emacs, GNU Emacs Manual}.  To get even more information when using
+that flag, add the following to your init file (these options are
+documented below):
+
+@lisp
+(when init-file-debug
+  (setq use-package-verbose t
+        use-package-expand-minimally nil
+        use-package-compute-statistics t
+        debug-on-error t))
+@end lisp
+
+@cindex reporting bugs
+@cindex expanding macro, for troubleshooting
+Since @code{use-package} is a macro, the first step when you need to
+dig deeper is usually to see what Emacs Lisp code your declaration
+expands to.  You can either use the command @w{@kbd{M-x
+pp-macroexpand-last-sexp}}, or wrap the use-package declaration in
+@code{macroexpand} and evaluate it.  It is a good idea to include
+their output in any bugs you file for use-package.
+
+@menu
+* Troubleshooting Options::
+* Gathering Statistics::
+* Disabling a package::
+@end menu
+
+@node Troubleshooting Options
+@section Options that help when troubleshooting
+
+@vindex use-package-expand-minimally
+By default, use-package will attempts to catch and report errors that
+occur during expansion of use-package declarations in your init file.
+Customize the user option @code{use-package-expand-minimally} to a
+non-@code{nil} value to disable this checking.
+
+@findex :catch
+This behavior may be overridden locally using the @code{:catch}
+keyword.  If @code{t} or @code{nil}, it enables or disables catching
+errors at load time.  It can also be a function taking two arguments:
+the keyword being processed at the time the error was encountered, and
+the error object (as generated by @code{condition-case}).  For
+example:
+
+@lisp
+(use-package example
+  ;; Note that errors are never trapped in the preface, since doing so would
+  ;; hide definitions from the byte-compiler.
+  :preface (message "I'm here at byte-compile and load time")
+  :init (message "I'm always here at startup")
+  :config
+  (message "I'm always here after the package is loaded")
+  (error "oops")
+  ;; Don't try to (require 'example), this is just an example!
+  :no-require t
+  :catch (lambda (keyword err)
+           (message (error-message-string err))))
+@end lisp
+
+Evaluating the above form will print these messages:
+
+@verbatim
+I’m here at byte-compile and load time
+I’m always here at startup
+Configuring package example...
+I’m always here after the package is loaded
+oops
+@end verbatim
+
+@node Gathering Statistics
+@section Gathering Statistics
+
+@vindex use-package-verbose
+When a package is loaded, and if you have @code{use-package-verbose}
+set to @code{t}, or if the package takes longer than 0.1 seconds to
+load, you will see a message to indicate this loading activity in the
+@code{*Messages*} buffer.  The same will happen for configuration, or
+@code{:config} blocks, that take longer than 0.1 seconds to execute.
+
+@vindex use-package-compute-statistics
+If you'd like to see a summary how many packages you've loaded, what
+stage of initialization they've reached, and how much aggregate time
+they've spent (roughly), you can customize the user option
+@code{use-package-compute-statistics} to a non-@code{nil} value.  Then
+reload your packages, normally by restarting Emacs, to make sure that
+use-package can gather statistics for all your packages.
+
+@cindex use-package-report
+Run the command @kbd{M-x use-package-report} to see the results.  The
+buffer displayed is a tabulated list.  To sort rows based on a
+particular column, move point to it and type @kbd{S}, or click the
+column name at the top of the buffer on graphical displays.
+
+@cindex use-package-reset-statistics
+To reset all statistics that use-package has gathered for the current
+Emacs invocation, run the command @kbd{M-x use-package-reset-statistics}.
+
+Note that, if you are setting @code{use-package-compute-statistics}
+directly in your init file, and not with @code{customize}, you must do
+this after loading @code{use-package}, but before any
+@code{use-package} forms.
+
+@node Disabling a package
+@section Disabling a package
+
+@cindex disable package
+@findex :disabled
+The @code{:disabled} keyword inhibits loading a package, and all it's
+customizations.  It is equivalent to commenting out or deleting the
+definition.
+
+You could use this, for example, to temporarily disable a package that
+you're having difficulties with, or to avoid loading a package that
+you're not currently using.
+
+This example disables the @samp{foo} package:
+
+@lisp
+(use-package foo
+  :disabled)
+@end lisp
+
+When byte-compiling your init file, use-package omits disabled
+declarations from the output entirely, in order to make Emacs startup
+faster.
+
+@c ----------------------------------------------------------------------------
+@node Keyword extensions
+@appendix Keyword extensions
+
+use-package is based on an extensible framework that makes it easy for
+package authors to add new keywords, or modify the behavior of
+existing keywords.
+
+Some keyword extensions are included with @code{use-package}, and can
+be optionally enabled.
+
+@menu
+* use-package-ensure-system-package::
+* Creating an extension::
+@end menu
+
+@node use-package-ensure-system-package
+@section :use-package-ensure-system-package
+
+@findex :ensure-system-package
+The @code{:ensure-system-package} keyword allows you to ensure certain
+executables are available on your system alongside your package
+declarations.@footnote{On macOS, you will want to make sure
+@code{exec-path} is cognisant of all binary package names that you
+would like to ensure are installed.  The
+@uref{https://github.com/purcell/exec-path-from-shell,@samp{exec-path-from-shell}}
+package is often a good way to do this.}
+
+To use this extension, add this immediately after loading
+@code{use-package}:
+
+@lisp
+(use-package use-package-ensure-system-package)
+@end lisp
+
+Now you can use the @code{:ensure-system-package} keyword.
+Here's an example usage:
+
+@lisp
+(use-package foo
+  :ensure-system-package foo)
+@end lisp
+
+This will expect a global binary package to exist called @code{foo}.
+If it does not, it will use your system package manager to attempt an
+install of a binary by the same name asynchronously.  This requires
+the GNU ELPA package
+@uref{https://gitlab.com/jabranham/system-packages,@samp{system-packages}},
+so for this to work you must install that first.
+
+One way of making sure it is installed is with @code{use-package}
+together with @code{:ensure}.
+
+@lisp
+(use-package system-packages
+  :ensure t)
+@end lisp
+
+For example, on a @code{Debian GNU/Linux} system, this would call
+@samp{apt-get install foo}.
+
+If the package is named differently than the binary, you can use a
+cons in the form of @code{(binary . package-name)}.  For example:
+
+@lisp
+(use-package foo
+  :ensure-system-package
+  (foocmd . foo))
+@end lisp
+
+On a @code{Debian GNU/Linux} system, this would call @code{apt install
+foo} if Emacs could not locate the executable
+@code{foocmd}.@footnote{For manual testing, you could use the
+@code{executable-find} function, which is what @samp{system-packages}
+uses internally.}
+
+@code{:ensure-system-package} can also take a cons where its
+@code{cdr} is a string that will get called by
+@code{(async-shell-command)} to install if it isn't found.  This does
+not depend upon any external package.
+
+@lisp
+(use-package tern
+  :ensure-system-package (tern . "npm i -g tern"))
+@end lisp
+
+To install several packages, you can pass in a list of conses:
+
+@lisp
+(use-package ruby-mode
+  :ensure-system-package
+  ((rubocop     . "gem install rubocop")
+   (ruby-lint   . "gem install ruby-lint")
+   (ripper-tags . "gem install ripper-tags")
+   (pry         . "gem install pry")))
+@end lisp
+
+Finally, in case the package dependency does not provide a global
+executable, you can ensure packages exist by checking the presence of a
+file path by providing a string like so:
+
+@lisp
+(use-package dash-at-point
+  :if (eq system-type 'darwin)
+  :ensure-system-package
+  ("/Applications/Dash.app" . "brew cask install dash"))
+@end lisp
+
+@code{:ensure-system-package} will use @code{system-packages-install}
+to install system packages, except where a custom command has been
+specified, in which case it will be executed verbatim by
+@code{async-shell-command}.
+
+The user options @code{system-packages-package-manager} and
+@code{system-packages-use-sudo} are honored, but not for custom
+commands.  Custom commands should include the call to sudo in the
+command if needed.
+
+@node Creating an extension
+@section How to create an extension keyword
+
+This section describes how to create a new keyword.
+
+@enumerate
+@item
+Add the keyword.
+
+The first step is to add your keyword at the right place in
+@code{use-package-keywords}.  This list determines the order in which
+things will happen in the expanded code.  You should never change this
+order, but it gives you a framework within which to decide when your
+keyword should fire.
+
+@item
+Create a normalizer.
+
+The job of the normalizer is take a list of arguments (possibly
+@code{nil}), and turn it into the single argument (which could still
+be a list) that should appear in the final property list used by
+@code{use-package}.
+
+Define a normalizer for your keyword by defining a function named
+after the keyword, for example:
+
+@lisp
+(defun use-package-normalize/:pin (name-symbol keyword args)
+  (use-package-only-one (symbol-name keyword) args
+    (lambda (label arg)
+      (cond
+       ((stringp arg) arg)
+       ((symbolp arg) (symbol-name arg))
+       (t
+        (use-package-error
+         ":pin wants an archive name (a string)"))))))
+@end lisp
+
+@item
+Create a handler.
+
+Once you have a normalizer, you must create a handler for the keyword.
+
+Handlers can affect the handling of keywords in two ways.  First, it
+can modify the @code{state} plist before recursively processing the
+remaining keywords, to influence keywords that pay attention to the
+state (one example is the state keyword @code{:deferred}, not to be
+confused with the @code{use-package} keyword @code{:defer}).  Then,
+once the remaining keywords have been handled and their resulting
+forms returned, the handler may manipulate, extend, or just ignore
+those forms.
+
+The task of each handler is to return a @emph{list of forms}
+representing code to be inserted.  It does not need to be a
+@code{progn} list, as this is handled automatically in other places.
+Thus it is common to see the idiom of using @code{use-package-concat}
+to add new functionality before or after a code body, so that only the
+minimum code necessary is emitted as the result of a
+@code{use-package} expansion.
+
+This is an example handler:
+
+@lisp
+(defun use-package-handler/:pin (name-symbol keyword archive-name rest state)
+  (let ((body (use-package-process-keywords name-symbol rest state)))
+    ;; This happens at macro expansion time, not when the expanded code is
+    ;; compiled or evaluated.
+    (if (null archive-name)
+        body
+      (use-package-pin-package name-symbol archive-name)
+      (use-package-concat
+       body
+       `((push '(,name-symbol . ,archive-name)
+               package-pinned-packages))))))
+@end lisp
+
+@item
+Test it.
+
+After the keyword has been inserted into @code{use-package-keywords},
+and a normalizer and a handler defined, you can now test it by seeing
+how usages of the keyword will expand.  For this, use @code{M-x
+pp-macroexpand-last-sexp} with the cursor set immediately after the
+@code{(use-package ...)} expression.
+@end enumerate
+
+@c ----------------------------------------------------------------------------
+@node History
+@appendix History and acknowledgments
+
+use-package was written by John Wiegley.  Its development started in
+2012, and it got merged into Emacs in 2022, in preparation of the
+release of Emacs 29.1.
+
+Dozens of people have contributed to use-package over the years with
+bug reports, documentation and code.  They are too many to list here,
+but we thank them all for their contributions.
+
+This Texinfo manual was written by Stefan Kangas, as a significant
+rewrite of the old use-package manual and @file{README}.
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Index
+@unnumbered Index
+@printindex cp
+
+@bye