[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
emacs-29 ab3210e709: Document 'use-package' in the 2 main manuals
From: |
Eli Zaretskii |
Subject: |
emacs-29 ab3210e709: Document 'use-package' in the 2 main manuals |
Date: |
Sun, 1 Jan 2023 03:38:55 -0500 (EST) |
branch: emacs-29
commit ab3210e7092f6bd8465e7f653be73f0f124153f9
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>
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.
---
doc/emacs/custom.texi | 22 +++++++++++++++++++
doc/lispref/loading.texi | 55 ++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 77 insertions(+)
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index f75512a00e..24a34552fb 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 c7fbdac1d7..edc1eca555 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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- emacs-29 ab3210e709: Document 'use-package' in the 2 main manuals,
Eli Zaretskii <=