1 files changed, 946 insertions, 0 deletions

diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi
new file mode 100644
index 00000000000..573baac89aa
--- /dev/null
+++ b/doc/misc/use-package.texi
@@ -0,0 +1,946 @@
+\input texinfo    @c -*- texinfo -*-
+@c %**start of header
+@setfilename use-package.info
+@settitle use-package User Manual
+@documentencoding UTF-8
+@documentlanguage en
+@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 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.
+
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* use-package: (use-package). Declarative package configuration for Emacs.
+@end direntry
+
+@finalout
+@titlepage
+@title use-package User Manual
+@subtitle for version 2.4.1-119-g0be480e+1
+@author John Wiegley
+@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 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!
+
+@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
+@end menu
+
+@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!
+
+More text to come@dots{}
+
+@node Installation
+@chapter Installation
+
+use-package can be installed using Emacs' package manager or manually from
+its development repository.
+
+@menu
+* Installing from GNU ELPA::
+* Installing from the Git Repository::
+* Post-Installation Tasks::
+@end menu
+
+@node Installing from GNU ELPA
+@section Installing from GNU ELPA
+
+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}:
+
+First, you need to update the local package list using:
+
+@example
+M-x package-refresh-contents RET
+@end example
+
+Once you have done that, you can install use-package and its
+dependencies using:
+
+@example
+M-x package-install RET use-package RET
+@end example
+
+Now see @ref{Post-Installation Tasks}.
+
+@node Installing from the Git Repository
+@section Installing from the Git Repository
+
+First, use Git to clone the use-package repository:
+
+@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
+
+Then compile the libraries and generate the info manuals:
+
+@example
+$ make
+@end example
+
+You may need to create @code{/path/to/use-package/config.mk} with the following
+content before running @code{make}:
+
+@example
+LOAD_PATH  = -L /path/to/use-package
+@end example
+
+Finally add this to your init file:
+
+@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/"))
+@end lisp
+
+Note that elements of @code{load-path} should not end with a slash, while those of
+@code{Info-directory-list} should.
+
+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.
+
+To update use-package use:
+
+@example
+$ git pull
+$ make
+@end example
+
+At times it might be necessary to run @code{make clean all} instead.
+
+To view all available targets use @code{make help}.
+
+Now see @ref{Post-Installation Tasks}.
+
+@node Post-Installation Tasks
+@section Post-Installation Tasks
+
+After installing use-package you should verify that you are indeed using the
+use-package release you think you are using.  It's best to restart Emacs before
+doing so, to make sure you are not using an outdated value for @code{load-path}.
+
+@example
+C-h v use-package-version RET
+@end example
+
+should display something like
+
+@example
+use-package-version’s value is "2.4.3"
+@end example
+
+If you are completely new to use-package then see @ref{Getting Started}.
+
+If you run into problems, then please see the @ref{Debugging Tools}.
+
+@node Getting Started
+@chapter Getting Started
+
+TODO@.  For now, see @code{README.md}.
+
+@node Basic Concepts
+@chapter Basic Concepts
+
+@code{use-package} was created for few basic reasons, each of which drove the
+design in various ways.  Understanding these reasons may help make some of
+those decisions clearer:
+
+@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.
+
+@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 a
+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 itemize
+
+@node Issues/Requests
+@chapter Issues/Requests
+
+@node Keywords
+@chapter Keywords
+
+@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
+
+@node @code{after}
+@section @code{:after}
+
+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:
+
+@lisp
+(use-package hydra
+  :load-path "site-lisp/hydra")
+
+(use-package ivy
+  :load-path "site-lisp/swiper")
+
+(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
+: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 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.
+
+@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.
+
+@node @code{bind-keymap} @code{bind-keymap*}
+@section @code{:bind-keymap}, @code{:bind-keymap*}
+
+Normally @code{:bind} expects that commands are functions that will be autoloaded
+from the given package.  However, this does not work if one of those commands
+is actually a keymap, since keymaps are not functions, and cannot be
+autoloaded using Emacs' @code{autoload} mechanism.
+
+To handle this case, @code{use-package} offers a special, limited variant of
+@code{:bind} called @code{:bind-keymap}.  The only difference is that the "commands"
+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 projectile
+  :bind-keymap
+  ("C-c p" . projectile-command-map)
+@end lisp
+
+@node @code{bind} @code{bind*}
+@section @code{:bind}, @code{:bind*}
+
+Another common thing to do when loading a module is to bind a key to primary
+commands within that module:
+
+@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 @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.
+
+A more literal way to do the exact same thing is:
+
+@lisp
+(use-package ace-jump-mode
+  :commands ace-jump-mode
+  :init
+  (bind-key "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.
+
+The @code{:bind} keyword takes either a cons or 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
+
+The @code{:commands} keyword likewise takes either a symbol or a list of symbols.
+
+NOTE: Special keys like @code{tab} or @code{F1}-@code{Fn} can be written in square brackets,
+i.e. @code{[tab]} instead of @code{"tab"}.  The syntax for the keybindings is similar to
+the "kbd" syntax: see @uref{https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Rebinding.html, the Emacs Manual} for more information.
+
+Examples:
+
+@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
+
+@menu
+* Binding to local keymaps::
+@end menu
+
+@node Binding to local keymaps
+@subsection Binding to local keymaps
+
+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:
+
+@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-mode-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 @code{commands}
+@section @code{:commands}
+
+@node @code{preface} @code{init} @code{config}
+@section @code{:preface}, @code{:init}, @code{:config}
+
+Here is the simplest @code{use-package} declaration:
+
+@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)
+@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.
+
+Use the @code{:init} keyword to execute code before a package is loaded.  It
+accepts one or more forms, up until the next keyword:
+
+@lisp
+(use-package foo
+  :init
+  (setq foo-variable t))
+@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:
+
+@lisp
+(use-package foo
+  :init
+  (setq foo-variable t)
+  :config
+  (foo-mode 1))
+@end lisp
+
+As you might expect, you can use @code{:init} and @code{:config} together:
+
+@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
+
+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.
+
+@node @code{custom}
+@section @code{:custom}
+
+The @code{:custom} keyword allows customization of package custom variables.
+
+@lisp
+(use-package comint
+  :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.
+
+@node @code{custom-face}
+@section @code{: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)))))
+@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.
+
+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.
+
+@node @code{defines} @code{functions}
+@section @code{:defines}, @code{:functions}
+
+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.
+
+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:
+
+@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
+
+@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:
+
+@lisp
+(use-package abbrev
+  :diminish abbrev-mode
+  :config
+  (if (file-exists-p abbrev-file-name)
+      (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.
+
+@lisp
+;; Don't show anything for rainbow-mode.
+(use-package rainbow-mode
+  :delight)
+
+;; Don't show anything for auto-revert-mode, which doesn't match
+;; its package name.
+(use-package autorevert
+  :delight auto-revert-mode)
+
+;; Remove the mode name for projectile-mode, but show the project name.
+(use-package projectile
+  :delight '(:eval (concat " " (projectile-project-name))))
+
+;; 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
+
+@node @code{disabled}
+@section @code{:disabled}
+
+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:
+
+@lisp
+(use-package ess-site
+  :disabled
+  :commands R)
+@end lisp
+
+When byte-compiling your @code{.emacs} file, disabled declarations are omitted
+from the output entirely, to accelerate startup times.
+
+@node @code{ensure} @code{pin}
+@section @code{:ensure}, @code{:pin}
+
+You can use @code{use-package} to load packages from ELPA with @code{package.el}.  This
+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):
+
+@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 specify it like this:
+
+@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.
+
+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.
+
+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).
+
+@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):
+
+@example
+Archive 'foo' requested for package 'bar' is not available.
+@end example
+
+Example:
+
+@lisp
+(use-package company
+  :ensure t
+  :pin melpa-stable)
+
+(use-package evil
+  :ensure t)
+  ;; no :pin needed, as package.el will choose the version in melpa
+
+(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)
+
+(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.
+
+@node @code{hook}
+@section @code{:hook}
+
+The @code{:hook} keyword allows adding functions onto hooks, here only the basename
+of the hook is required.  Thus, all of the following are equivalent:
+
+@lisp
+(use-package ace-jump-mode
+  :hook prog-mode)
+
+(use-package ace-jump-mode
+  :hook (prog-mode . ace-jump-mode))
+
+(use-package ace-jump-mode
+  :commands ace-jump-mode
+  :init
+  (add-hook 'prog-mode-hook #'ace-jump-mode))
+@end lisp
+
+And likewise, when multiple hooks should be applied, the following are also
+equivalent:
+
+@lisp
+(use-package ace-jump-mode
+  :hook (prog-mode text-mode))
+
+(use-package ace-jump-mode
+  :hook ((prog-mode text-mode) . ace-jump-mode))
+
+(use-package ace-jump-mode
+  :hook ((prog-mode . ace-jump-mode)
+         (text-mode . ace-jump-mode)))
+
+(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
+
+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}.
+
+@node @code{if} @code{when} @code{unless}
+@section @code{:if}, @code{:when}, @code{:unless}
+
+You can use the @code{:if} keyword to predicate the loading and initialization of
+modules.
+
+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:
+
+@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))
+@end lisp
+
+In another example, we can load things conditional on the operating system:
+
+@lisp
+(use-package exec-path-from-shell
+  :if (memq window-system '(mac ns))
+  :ensure t
+  :config
+  (exec-path-from-shell-initialize))
+@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)}.
+
+@node @code{load-path}
+@section @code{:load-path}
+
+If your package needs a directory added to the @code{load-path} in order to load,
+use @code{:load-path}.  This takes a symbol, a function, a string or a list of
+strings.  If the path is relative, it is expanded within
+@code{user-emacs-directory}:
+
+@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 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:
+
+@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{mode} @code{interpreter}
+@section @code{:mode}, @code{: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:
+
+@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
+
+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:
+
+@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
+
+This does exactly the same thing as the following:
+
+@lisp
+(use-package ace-jump-mode
+  :bind ("C-." . ace-jump-mode))
+@end lisp
+
+@node @code{magic} @code{magic-fallback}
+@section @code{:magic}, @code{: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 the two is
+that @code{:magic-fallback} has a lower priority than @code{:mode}.  For example:
+
+@lisp
+(use-package pdf-tools
+  :load-path "site-lisp/pdf-tools/lisp"
+  :magic ("%PDF" . pdf-view-mode)
+  :config
+  (pdf-tools-install))
+@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 @code{no-require}
+@section @code{:no-require}
+
+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 "This is evaluated when `foo' is loaded"))
+@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:
+
+@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 Debugging Tools
+@chapter Debugging Tools
+
+TODO
+
+@bye