Document 'use-package' in the 2 main manuals

* doc/emacs/custom.texi (Init Examples):
* doc/lispref/loading.texi (Named Features): Document 'use-package'
and its most important features.

2 files changed, 77 insertions, 0 deletions

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index f75512a00e9..24a34552fb6 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -2701,6 +2701,28 @@ function is not defined.
 
 A @code{setq} on a variable which does not exist is generally
 harmless, so those do not need a conditional.
+
+@item
+Using @code{use-package} to automatically load and configure a
+package.
+
+@example
+(use-package hi-lock
+  :defer t
+  :init (add-hook 'some-hook 'hi-lock-mode)
+  :config (use-package my-hi-lock)
+  :bind (("M-o l" . highlight-lines-matching-regexp)
+         ("M-o r" . highlight-regexp)
+         ("M-o w" . highlight-phrase)))
+@end example
+
+@noindent
+This will load @code{hi-lock} when some of its commands or variables
+are first used, bind 3 keys to its commands, and additionally load the
+@code{my-hi-lock} package (presumably further customizing
+@code{hi-lock}) after loading @code{hi-lock}.  The @code{use-package}
+facility is fully documented in its own manual, @pxref{Top,,,
+use-package, use-package User manual}.
 @end itemize
 
 @node Terminal Init
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index c7fbdac1d76..edc1eca555f 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -1026,6 +1026,61 @@ with a call to @code{provide}.  The order of the elements in the
 @code{features} list is not significant.
 @end defvar
 
+@cindex loading and configuring features
+The @code{use-package} macro provides a convenient way of loading a
+feature and configuring it for use.  It provides a means to combine
+requiring a feature, like @code{require} does, with code to be run
+when the feature is actually loaded, similar to load-time hooks
+(@pxref{Hooks for Loading}).  The declarative syntax of
+@code{use-package} makes it exceptionally easy to use in user init
+files.
+
+@defmac use-package feature &rest args
+This macro specifies how to load the named @var{feature} and how to
+configure and customize it for use.  The arguments @var{args} are
+keyword-value pairs.  Some of the important keywords and their values
+are:
+
+@table @code
+@item :init @var{forms}
+Specifies @var{forms} to execute before @var{feature} is loaded.
+
+@item :config @var{forms}
+Specifies @var{forms} to execute after loading @var{feature}.
+
+@item :defer @var{condition}
+If @var{condition} is non-@code{nil}, it specifies to defer loading
+@var{feature} until any of the autoloaded commands or variables of
+@var{feature} are first used.  If @var{condition} is a number @var{n},
+it specifies that @var{feature} should be loaded after @var{n}
+seconds of idle time.
+
+@item :commands @var{commands}@dots{}
+Specifies commands of @var{feature} to be autoloaded.
+
+@item :bind @var{keybindings}@dots{}
+Specifies the @var{keybindings} for @var{feature}s commands.  Each
+binding has the form
+
+@lisp
+(@var{key-sequence} . @var{command})
+@end lisp
+@noindent
+or
+@lisp
+(:map @var{keymap} (@var{key-sequence} . @var{command}))
+@end lisp
+
+@noindent
+where @var{key-sequence} is in the form accepted by the @code{kbd}
+macro (@pxref{Key Sequences}).
+@end table
+
+For more details about @code{use-package}, see @ref{Top,,,
+use-package, use-package User Manual}.
+@end defmac
+
+
 @node Where Defined
 @section Which File Defined a Certain Symbol
 @cindex symbol, where defined