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.

1 files changed, 55 insertions, 0 deletions

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