Add new use-package manual

* doc/misc/use-package.texi: Rewrite manual.

1 files changed, 1456 insertions, 589 deletions

diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi
index 573baac89aa..d39125c4555 100644
--- a/doc/misc/use-package.texi
+++ b/doc/misc/use-package.texi
@@ -1,29 +1,32 @@
 \input texinfo    @c -*- texinfo -*-
 @c %**start of header
-@setfilename use-package.info
+@setfilename ../../use-package.info
 @settitle use-package User Manual
-@documentencoding UTF-8
-@documentlanguage en
+@include docstyle.texi
+@syncodeindex vr cp
+@syncodeindex fn cp
 @c %**end of header
 
 @copying
-@quotation
-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
-Foundation, either version 3 of the License, or (at your option) any
-later version.
+This manual is for use-package, a configuration macro for simplifying
+your init file.
 
-This document is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@.  See the GNU
-General Public License for more details.
+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
+@dircategory Emacs misc features
 @direntry
 * use-package: (use-package). Declarative package configuration for Emacs.
 @end direntry
@@ -31,8 +34,8 @@ General Public License for more details.
 @finalout
 @titlepage
 @title use-package User Manual
-@subtitle for version 2.4.1-119-g0be480e+1
-@author John Wiegley
+@subtitle for version 2.4.5
+@author John Wiegley & Stefan Kangas
 @page
 @vskip 0pt plus 1filll
 @insertcopying
@@ -44,353 +47,707 @@ General Public License for more details.
 @node Top
 @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
-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
-around 2 seconds, with no loss of functionality!
+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
-@end ifnottex
 
 @menu
-* Introduction::
-* Installation::
-* Getting Started::
-* Basic Concepts::
-* Issues/Requests::
-* Keywords::
-* Debugging Tools::
-
-@detailmenu
---- The Detailed Node Listing ---
-
-Installation
-
-* Installing from GNU ELPA::
-* Installing from the Git Repository::
-* Post-Installation Tasks::
-
-Keywords
-
-* @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::
-
-
-@end detailmenu
+* 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
 
-@node Introduction
-@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
-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
-around 2 seconds, with no loss of functionality!
+@c ----------------------------------------------------------------------------
+@node Basic Concepts
+@chapter Basic Concepts
 
-More text to come@dots{}
+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:
 
-@node Installation
-@chapter Installation
+@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.
 
-use-package can be installed using Emacs' package manager or manually from
-its development repository.
+@item
+To reduce duplication and boilerplate, capturing several common
+practices as mere keywords both easy and intuitive to use.
 
-@menu
-* Installing from GNU ELPA::
-* Installing from the Git Repository::
-* Post-Installation Tasks::
-@end menu
+@item
+To make startup time of Emacs as quick as possible, without
+sacrificing the quantity of add-on packages used.
 
-@node Installing from GNU ELPA
-@section Installing from GNU ELPA
+@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.
 
-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}:
+@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
 
-First, you need to update the local package list using:
+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.
 
-@example
-M-x package-refresh-contents RET
-@end example
+@c ----------------------------------------------------------------------------
+@node Getting Started
+@chapter Getting Started
 
-Once you have done that, you can install use-package and its
-dependencies using:
+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:
 
-@example
-M-x package-install RET use-package RET
-@end example
+@lisp
+(require 'use-package)
+(require 'bind-key)            ; if you use any :bind variant
+@end lisp
 
-Now see @ref{Post-Installation Tasks}.
+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.
 
-@node Installing from the Git Repository
-@section Installing from the Git Repository
+To unconditionally load a package named @samp{foo}, add the following
+declaration to your init file:
 
-First, use Git to clone the use-package repository:
+@lisp
+(use-package foo)
+@end lisp
 
-@example
-$ git clone https://github.com/jwiegley/use-package.git ~/.emacs.d/site-lisp/use-package
-$ cd ~/.emacs.d/site-lisp/use-package
-@end example
+@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}).
 
-Then compile the libraries and generate the info manuals:
+To evaluate Lisp code @emph{before} the @samp{foo} package is loaded,
+use the @code{:init} keyword:
 
-@example
-$ make
-@end example
+@lisp
+(use-package foo
+  :init
+  (setq foo-variable t))
+@end lisp
 
-You may need to create @code{/path/to/use-package/config.mk} with the following
-content before running @code{make}:
+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:
 
-@example
-LOAD_PATH  = -L /path/to/use-package
-@end example
+@lisp
+(use-package foo
+  :init
+  (setq foo-variable t)
+  :config
+  (foo-mode 1))
+@end lisp
 
-Finally add this to your init file:
+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
-(add-to-list 'load-path "~/.emacs.d/site-lisp/use-package")
-(require 'use-package)
-
-(with-eval-after-load 'info
-  (info-initialize)
-  (add-to-list 'Info-directory-list
-               "~/.emacs.d/site-lisp/use-package/"))
+(use-package foo
+  :defer t)
 @end lisp
 
-Note that elements of @code{load-path} should not end with a slash, while those of
-@code{Info-directory-list} should.
+@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.
 
-Instead of running use-package directly from the repository by adding it to
-the @code{load-path}, you might want to instead install it in some other directory
-using @code{sudo make install} and setting @code{load-path} accordingly.
+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.
 
-To update use-package use:
+@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
 
-@example
-$ git pull
-$ make
-@end example
+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.
 
-At times it might be necessary to run @code{make clean all} instead.
+That should be enough to get you started!
 
-To view all available targets use @code{make help}.
+@c ----------------------------------------------------------------------------
+@node Loading Packages
+@chapter Loading Packages
 
-Now see @ref{Post-Installation Tasks}.
+@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.
 
-@node Post-Installation Tasks
-@section Post-Installation Tasks
+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.
 
-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
-doing so, to make sure you are not using an outdated value for @code{load-path}.
+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.
 
-@example
-C-h v use-package-version RET
-@end example
+use-package can interface with @samp{package.el} to install packages
+on Emacs start.  @xref{Installing packages} for details.
 
-should display something like
+@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
 
-@example
-use-package-version’s value is "2.4.3"
-@end example
+@node Loading basics
+@section How and when use-package loads packages
 
-If you are completely new to use-package then see @ref{Getting Started}.
+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.
 
-If you run into problems, then please see the @ref{Debugging Tools}.
+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:
 
-@node Getting Started
-@chapter Getting Started
+@lisp
+(use-package foo)
+@end lisp
 
-TODO@.  For now, see @code{README.md}.
+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}:
 
-@node Basic Concepts
-@chapter Basic Concepts
+@lisp
+(use-package foo
+  :defer t)
+@end lisp
 
-@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
-those decisions clearer:
+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}).
 
-@itemize
-@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.
+@subheading Defer loading until idle for N seconds
 
-@item
-To reduce duplication and boilerplate, capturing several common
-practices as mere keywords both easy and intuitive to use.
+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:
 
-@item
-To make startup time of Emacs as quick as possible, without
-sacrificing the quantity of add-on packages used.
+@lisp
+(use-package foo
+  :defer 30)
+@end lisp
 
-@item
-To make it so errors encountered during startup disable only the
-package raising the error, and as little else as possible, leaving a
-close to a functional Emacs as possible.
+@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 @samp{foo} in graphical Emacs sessions,
+you could use the following:
 
-@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 itemize
+@lisp
+(use-package foo
+  :if (display-graphic-p))
+@end lisp
 
-@node Issues/Requests
-@chapter Issues/Requests
+Another common use case is to make it conditional on the operating
+system:
 
-@node Keywords
-@chapter Keywords
+@lisp
+(use-package foo
+  :if (memq window-system '(mac ns)))
+@end lisp
 
-@menu
-* @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
+@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:
 
-@node @code{after}
-@section @code{:after}
+@lisp
+(when (memq window-system '(mac ns))
+  (use-package foo
+    :ensure t))
+@end lisp
 
-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
-example:
+@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
-  :load-path "site-lisp/hydra")
+(use-package hydra)
 
-(use-package ivy
-  :load-path "site-lisp/swiper")
+(use-package ivy)
 
 (use-package ivy-hydra
   :after (ivy hydra))
 @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,
-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:
-
-@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
 
-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 both @code{baz} and @code{quux} have been loaded.
+This is the same as:
 
-@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
-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.
+@lisp
+(use-package abbrev
+  :if (featurep 'foo))
+@end lisp
 
-@node @code{bind-keymap} @code{bind-keymap*}
-@section @code{:bind-keymap}, @code{:bind-keymap*}
+As a convenience, a list of such packages may be specified:
 
-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 Emacs' @code{autoload} mechanism.
+@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}
 
-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.
+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 projectile
-  :bind-keymap
-  ("C-c p" . projectile-command-map)
+(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 @code{bind} @code{bind*}
-@section @code{:bind}, @code{:bind*}
+@node Manual autoloads
+@section Setting up autoloads manually
 
-Another common thing to do when loading a module is to bind a key to primary
-commands within that module:
+@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 ace-jump-mode
-  :bind ("C-." . ace-jump-mode))
+(use-package org-crypt
+  :autoload org-crypt-use-before-save-magic)
 @end lisp
 
-This does two things: first, it creates an autoload for the @code{ace-jump-mode}
-command and defers loading of @code{ace-jump-mode} until you actually use it.
-Second, it binds the key @code{C-.} to that command.  After loading, you can use
-@code{M-x describe-personal-keybindings} to see all such keybindings you've set
-throughout your @code{.emacs} file.
+@c ----------------------------------------------------------------------------
+@node Configuring Packages
+@chapter Configuring Packages
 
-A more literal way to do the exact same thing is:
+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 ace-jump-mode
-  :commands ace-jump-mode
+(use-package foo
   :init
-  (bind-key "C-." 'ace-jump-mode))
+  (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
+
+To bind keys globally, the @code{:bind} keyword takes either a single
+cons or a list of conses.  Every cons has the form @code{(@var{key}
+. @var{command}}, where @var{key} is a string indicating the key to
+bind, and @var{command} is the name of a command (a symbol).  The
+syntax for the keys is similar to the syntax used by the @code{kbd}
+function (@pxref{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
 
-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
-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.
+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.
 
-The @code{:bind} keyword takes either a cons or a list of conses:
+@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
@@ -399,11 +756,12 @@ The @code{:bind} keyword takes either a cons or a list of conses:
          ("M-o w" . highlight-phrase)))
 @end lisp
 
-The @code{:commands} keyword likewise takes either a symbol or a list of symbols.
+@subheading Using special keys
 
-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
-the "kbd" syntax: see @uref{https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Rebinding.html, the Emacs Manual} for more information.
+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:
 
@@ -415,16 +773,63 @@ Examples:
          ([S-f10] . helm-recentf)))
 @end lisp
 
-@menu
-* Binding to local keymaps::
-@end menu
+@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:
 
-@node Binding to local keymaps
-@subsection Binding to local keymaps
+@lisp
+(use-package ace-jump-mode
+  :bind ("C-." . ace-jump-mode))
+@end lisp
 
-Slightly different from binding a key to a keymap, is binding a key @strong{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:
+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
@@ -432,12 +837,13 @@ supports this with a @code{:map} modifier, taking the local keymap to bind to:
          ("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-mode-map}.
+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:
+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
@@ -451,155 +857,337 @@ first use of @code{:map} are applied to the global keymap:
          ("M-n" . term-send-down)))
 @end lisp
 
-@node @code{commands}
-@section @code{:commands}
+@node Binding to a keymap
+@subsection Binding to keymaps
 
-@node @code{preface} @code{init} @code{config}
-@section @code{:preface}, @code{:init}, @code{:config}
+@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.
 
-Here is the simplest @code{use-package} declaration:
+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
-;; This is only needed once, near the top of the file
-(eval-when-compile
-  ;; Following line is not needed if use-package.el is in ~/.emacs.d
-  (add-to-list 'load-path "<path where use-package is installed>")
-  (require 'use-package))
+(use-package foo
+  :bind-keymap ("C-c p" . foo-command-map))
+@end lisp
 
-(use-package foo)
+@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
 
-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
-succeeds, a message about @code{"Loading foo"} is logged, along with the time it
-took to load, if it took over 0.1 seconds.
+@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
 
-Use the @code{:init} keyword to execute code before a package is loaded.  It
-accepts one or more forms, up until the next keyword:
+@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 foo
-  :init
-  (setq foo-variable t))
+(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
 
-Similarly, @code{:config} can be used to execute code after a package is loaded.
-In cases where loading is done lazily (see more about autoloading below), this
-execution is deferred until after the autoload occurs:
+@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
+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 foo
+(use-package company
+  :commands company-mode
   :init
-  (setq foo-variable t)
-  :config
-  (foo-mode 1))
+  (add-hook 'prog-mode-hook #'company-mode))
 @end lisp
 
-As you might expect, you can use @code{:init} and @code{:config} together:
+Using @code{:hook}, this can be simplified to:
 
 @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))
+(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
-  (setq isearch-lazy-highlight t)
+  (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
+
+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:
+
+@lisp
+(use-package ruby-mode
+  :mode "\\.rb\\'"
+  :interpreter "ruby")
+
+;; The package is "python" but the mode is "python-mode":
+(use-package python
+  :mode ("\\.py\\'" . python-mode)
+  :interpreter ("python" . python-mode))
+@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
-  (use-package moccur-edit))
+  (pdf-tools-install :no-query))
 @end lisp
 
-In this case, I want to autoload the commands @code{isearch-moccur} and
-@code{isearch-all} from @code{color-moccur.el}, and bind keys both at the global level
-and within the @code{isearch-mode-map} (see next section).  When the package is
-actually loaded (by using one of these commands), @code{moccur-edit} is also
-loaded, to allow editing of the @code{moccur} buffer.
+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 @code{custom}
-@section @code{:custom}
+@node User options
+@section User options
 
-The @code{:custom} keyword allows customization of package custom variables.
+@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
 
-The documentation string is not mandatory.
+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.
 
-@node @code{custom-face}
-@section @code{:custom-face}
+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.
 
-The @code{:custom-face} keyword allows customization of package custom faces.
+@node Faces
+@section Faces
+
+The @code{:custom-face} keyword allows customization of package custom
+faces.
 
 @lisp
 (use-package eruby-mode
   :custom-face
   (eruby-standard-face ((t (:slant italic)))))
-@end lisp
 
-@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
-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.
+(use-package example
+  :custom-face
+  (example-1-face ((t (:foreground "LightPink"))))
+  (example-2-face ((t (:foreground "LightGreen"))) face-defspec-spec))
 
-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.
+(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 @code{defines} @code{functions}
-@section @code{:defines}, @code{:functions}
+@node Hiding minor modes
+@section Hiding minor modes with diminish and delight
 
-Another feature of @code{use-package} is that it always loads every file that it
-can when @code{.emacs} is being byte-compiled.  This helps to silence spurious
-warnings about unknown variables and functions.
+@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}.
 
-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 the byte-compiler:
+@menu
+* Diminish::                    Hiding minor modes with Diminish.
+* Delight::                     Hiding minor modes with Delight.
+@end menu
 
-@lisp
-(use-package texinfo
-  :defines texinfo-section-list
-  :commands texinfo-mode
-  :init
-  (add-to-list 'auto-mode-alist '("\\.texi$" . texinfo-mode)))
-@end lisp
+@node Diminish
+@subsection Diminish
 
-If you need to silence a missing function warning, you can use @code{:functions}:
+@findex :diminish
+When diminish@footnote{The diminish package is installable from
+@acronym{GNU ELPA}.} is installed, you can use the @code{:diminish}
+keyword.  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 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))
+(use-package diminish :ensure t)
 @end lisp
 
-@node @code{diminish} @code{delight}
-@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
-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
-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 "-mode" appended at the end:
+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
@@ -609,11 +1197,26 @@ package name with "-mode" appended at the end:
       (quietly-read-abbrev-file)))
 @end lisp
 
-@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,
-the default mode name is hidden completely.
+@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.
+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 guessed 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.
 
 @lisp
 ;; Don't show anything for rainbow-mode.
@@ -636,30 +1239,31 @@ the default mode name is hidden completely.
   (visual-line-mode))
 @end lisp
 
-@node @code{disabled}
-@section @code{:disabled}
+@c ----------------------------------------------------------------------------
+@node Installing packages
+@chapter Installing packages automatically
 
-The @code{:disabled} keyword can turn off a module you're having difficulties with,
-or stop loading something you're not using at the present time:
+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.
 
-@lisp
-(use-package ess-site
-  :disabled
-  :commands R)
-@end lisp
+@menu
+* Install package::
+* Pinning packages::
+* Other package managers::
+@end menu
 
-When byte-compiling your @code{.emacs} file, disabled declarations are omitted
-from the output entirely, to accelerate startup times.
+@node Install package
+@section Installing package
 
-@node @code{ensure} @code{pin}
-@section @code{:ensure}, @code{:pin}
+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.
 
-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
-not already present on your system (set @code{(setq use-package-always-ensure t)}
-if you wish this behavior to be global for all packages):
+For example:
 
 @lisp
 (use-package magit
@@ -667,280 +1271,543 @@ if you wish this behavior to be global for all packages):
 @end lisp
 
 If you need to install a different package from the one named by
-@code{use-package}, you can specify it like this:
+@code{use-package}, you can use a symbol:
 
 @lisp
 (use-package tex
   :ensure auctex)
 @end lisp
 
-Lastly, when running on Emacs 24.4 or later, use-package can pin a package to
-a specific archive, allowing you to mix and match packages from different
-archives.  The primary use-case for this is preferring packages from the
-@code{melpa-stable} and @code{gnu} archives, but using specific packages from @code{melpa}
-when you need to track newer versions than what is available in the @code{stable}
-archives is also a valid use-case.
+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.
 
-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
-set @code{use-package-always-pin} to set a default.
+@lisp
+(require 'use-package-ensure)
+(setq use-package-always-ensure t)
+@end lisp
 
-If you want to manually keep a package updated and ignore upstream updates,
-you can pin it to @code{manual}, which as long as there is no repository by that
-name, will Just Work(tm).
+@noindent
+You can override the above setting for a single package by adding
+@w{@code{:ensure nil}} to its declaration.
 
-@code{use-package} throws an error if you try to pin a package to an archive that
-has not been configured using @code{package-archives} (apart from the magic
-@code{manual} archive mentioned above):
+@node Pinning packages
+@section Pinning packages using @code{:pin}
 
-@example
-Archive 'foo' requested for package 'bar' is not available.
-@end example
+@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.
 
-Example:
+For example:
 
 @lisp
 (use-package company
   :ensure t
-  :pin melpa-stable)
+  :pin gnu)   ; GNU ELPA
+@end lisp
 
-(use-package evil
-  :ensure t)
-  ;; no :pin needed, as package.el will choose the version in melpa
+@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.
 
-(use-package adaptive-wrap
-  :ensure t
-  ;; as this package is available only in the gnu archive, this is
-  ;; technically not needed, but it helps to highlight where it
-  ;; comes from
-  :pin gnu)
+Example:
 
+@lisp
 (use-package org
   :ensure t
   ;; ignore org-mode from upstream and use a manually installed version
   :pin manual)
 @end lisp
 
-@strong{NOTE}: the @code{:pin} argument has no effect on emacs versions < 24.4.
+@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:
 
-@node @code{hook}
-@section @code{:hook}
+@lisp
+(use-package texinfo
+  :defines texinfo-section-list
+  :commands texinfo-mode
+  :init
+  (add-to-list 'auto-mode-alist '("\\.texi$" . texinfo-mode)))
+@end lisp
 
-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:
+If you need to silence a missing function warning, you can use
+@code{:functions}:
 
 @lisp
-(use-package ace-jump-mode
-  :hook prog-mode)
-
-(use-package ace-jump-mode
-  :hook (prog-mode . ace-jump-mode))
+(use-package ruby-mode
+  :mode "\\.rb\\'"
+  :interpreter "ruby"
+  :functions inf-ruby-keys
+  :config
+  (defun my-ruby-mode-hook ()
+    (require 'inf-ruby)
+    (inf-ruby-keys))
 
-(use-package ace-jump-mode
-  :commands ace-jump-mode
-  :init
-  (add-hook 'prog-mode-hook #'ace-jump-mode))
+  (add-hook 'ruby-mode-hook 'my-ruby-mode-hook))
 @end lisp
 
-And likewise, when multiple hooks should be applied, the following are also
-equivalent:
+@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 ace-jump-mode
-  :hook (prog-mode text-mode))
+(use-package foo
+  :no-require t
+  :config
+  (message "Evaluate this immediately after loading `foo'"))
+@end lisp
 
-(use-package ace-jump-mode
-  :hook ((prog-mode text-mode) . ace-jump-mode))
+@c ----------------------------------------------------------------------------
+@node Troubleshooting
+@chapter Troubleshooting
 
-(use-package ace-jump-mode
-  :hook ((prog-mode . ace-jump-mode)
-         (text-mode . ace-jump-mode)))
+@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.
 
-(use-package ace-jump-mode
-  :commands ace-jump-mode
-  :init
-  (add-hook 'prog-mode-hook #'ace-jump-mode)
-  (add-hook 'text-mode-hook #'ace-jump-mode))
-@end lisp
+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):
 
-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} (meaning 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}.
+@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
 
-@node @code{if} @code{when} @code{unless}
-@section @code{:if}, @code{:when}, @code{:unless}
+@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.
 
-You can use the @code{:if} keyword to predicate the loading and initialization of
-modules.
+@menu
+* Troubleshooting Options::
+* Gathering Statistics::
+* Disabling a package::
+@end menu
 
-For example, I only want @code{edit-server} running for my main, graphical Emacs,
-not for other Emacsen I may start at the command line:
+@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 edit-server
-  :if window-system
-  :init
-  (add-hook 'after-init-hook 'server-start t)
-  (add-hook 'after-init-hook 'edit-server-start t))
+(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
 
-In another example, we can load things conditional on the operating system:
+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 @code{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.
+
+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 exec-path-from-shell
-  :if (memq window-system '(mac ns))
-  :ensure t
-  :config
-  (exec-path-from-shell-initialize))
+(use-package foo
+  :disabled)
 @end lisp
 
-Note that @code{:when} is provided as an alias for @code{:if}, and @code{:unless foo} means
-the same thing as @code{:if (not foo)}.
+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::
+* use-package-chords::
+* Creating an extension::
+@end menu
+
+@node use-package-ensure-system-package
+@section :use-package-ensure-system-package
 
-@node @code{load-path}
-@section @code{:load-path}
+@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.}
 
-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
-@code{user-emacs-directory}:
+To use this extension, add this immediately after loading
+@code{use-package}:
 
 @lisp
-(use-package ess-site
-  :load-path "site-lisp/ess/lisp/"
-  :commands R)
+(use-package use-package-ensure-system-package)
 @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 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:
+Now you can use the @code{:ensure-system-package} keyword.
+Here's an example usage:
 
 @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)
+(use-package foo
+  :ensure-system-package foo)
 @end lisp
 
-@node @code{mode} @code{interpreter}
-@section @code{:mode}, @code{:interpreter}
+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.
 
-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:
+One way of making sure it is installed is with @code{use-package}
+together with @code{:ensure}.
 
 @lisp
-(use-package ruby-mode
-  :mode "\\.rb\\'"
-  :interpreter "ruby")
-
-;; The package is "python" but the mode is "python-mode":
-(use-package python
-  :mode ("\\.py\\'" . python-mode)
-  :interpreter ("python" . python-mode))
+(use-package system-packages
+  :ensure t)
 @end lisp
 
-If you aren't using @code{:commands}, @code{:bind}, @code{:bind*}, @code{:bind-keymap},
-@code{:bind-keymap*}, @code{:mode}, or @code{:interpreter} (all of which imply @code{:defer}; see
-the docstring for @code{use-package} for a brief description of each), you can
-still defer loading with the @code{:defer} keyword:
+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 ace-jump-mode
-  :defer t
-  :init
-  (autoload 'ace-jump-mode "ace-jump-mode" nil t)
-  (bind-key "C-." 'ace-jump-mode))
+(use-package foo
+  :ensure-system-package
+  (foocmd . foo))
 @end lisp
 
-This does exactly the same thing as the following:
+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 ace-jump-mode
-  :bind ("C-." . ace-jump-mode))
+(use-package tern
+  :ensure-system-package (tern . "npm i -g tern"))
 @end lisp
 
-@node @code{magic} @code{magic-fallback}
-@section @code{:magic}, @code{:magic-fallback}
+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
 
-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:
+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 pdf-tools
-  :load-path "site-lisp/pdf-tools/lisp"
-  :magic ("%PDF" . pdf-view-mode)
-  :config
-  (pdf-tools-install))
+(use-package dash-at-point
+  :if (eq system-type 'darwin)
+  :ensure-system-package
+  ("/Applications/Dash.app" . "brew cask install dash"))
 @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"}.
+@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 @code{no-require}
-@section @code{:no-require}
+@node use-package-chords
+@section @code{(use-package-chords)}
 
-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:
+The @code{:chords} keyword allows you to define
+@uref{https://www.emacswiki.org/emacs/key-chord.el,@code{key-chord}}
+bindings for @code{use-package} declarations in the same manner as the
+@code{:bind} keyword.
+
+To enable the extension:
 
 @lisp
-(use-package foo
-  :no-require t
-  :config
-  (message "This is evaluated when `foo' is loaded"))
+(use-package use-package-chords
+  :ensure t
+  :config (key-chord-mode 1))
 @end lisp
 
-@node @code{requires}
-@section @code{:requires}
-
-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:
+Then you can define your chord bindings in the same manner as
+@code{:bind} using a cons or a list of conses:
 
 @lisp
-(use-package abbrev
-  :requires foo)
+(use-package ace-jump-mode
+  :chords (("jj" . ace-jump-char-mode)
+           ("jk" . ace-jump-word-mode)
+           ("jl" . ace-jump-line-mode)))
 @end lisp
 
-This is the same as:
+@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
-(use-package abbrev
-  :if (featurep 'foo))
+(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
 
-As a convenience, a list of such packages may be specified:
+@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
-(use-package abbrev
-  :requires (foo bar baz))
+(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
 
-For more complex logic, such as that supported by @code{:after}, simply use @code{:if}
-and the appropriate Lisp expression.
+@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 Debugging Tools
-@chapter Debugging Tools
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
 
-TODO
+@node Index
+@unnumbered Index
+@printindex cp
 
 @bye