diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi index de6351c592f..573baac89aa 100644 --- a/doc/misc/use-package.texi +++ b/doc/misc/use-package.texi @@ -8,7 +8,7 @@ @copying @quotation -Copyright (C) 2012-2022 John Wiegley +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 @@ -31,7 +31,7 @@ General Public License for more details. @finalout @titlepage @title use-package User Manual -@subtitle for version 2.4.1-81-gb185c6b+1 +@subtitle for version 2.4.1-119-g0be480e+1 @author John Wiegley @page @vskip 0pt plus 1filll @@ -45,9 +45,9 @@ General Public License for more details. @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 +@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 +were getting difficult to manage. Yet with this utility my total load time is around 2 seconds, with no loss of functionality! @insertcopying @@ -73,27 +73,27 @@ Installation Keywords -* @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{preface}, @code{init}, @code{config}: @code{preface} @code{init} @code{config}. -* @code{custom}:: -* @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{ensure}, @code{pin}: @code{ensure} @code{pin}. -* @code{hook}:: -* @code{if}, @code{when}, @code{unless}: @code{if} @code{when} @code{unless}. -* @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{requires}:: +* @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*} +@code{bind}, @code{bind*} * Binding to local keymaps:: @@ -105,9 +105,9 @@ Keywords @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 +@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 +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{} @@ -127,10 +127,10 @@ its development repository. @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 +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,}. +@ref{Packages,,,emacs,}. Then add one of the archives to @code{package-archives}: First, you need to update the local package list using: @@ -206,7 +206,7 @@ Now see @ref{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 +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 @@ -216,7 +216,7 @@ C-h v use-package-version RET should display something like @example -use-package-version’s value is "2.4.1" +use-package-version’s value is "2.4.3" @end example If you are completely new to use-package then see @ref{Getting Started}. @@ -226,13 +226,13 @@ 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}. +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 +design in various ways. Understanding these reasons may help make some of those decisions clearer: @itemize @@ -256,7 +256,7 @@ 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 +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 @@ -267,25 +267,25 @@ used for speed (reason 3), it can still be used as a sanity check. @chapter Keywords @menu -* @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{preface}, @code{init}, @code{config}: @code{preface} @code{init} @code{config}. -* @code{custom}:: -* @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{ensure}, @code{pin}: @code{ensure} @code{pin}. -* @code{hook}:: -* @code{if}, @code{when}, @code{unless}: @code{if} @code{when} @code{unless}. -* @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{requires}:: +* @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} @@ -293,8 +293,8 @@ used for speed (reason 3), it can still be used as a sanity check. 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 +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 @@ -309,13 +309,13 @@ example: @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, +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: +have been loaded. Here are some of the other possibilities: @lisp :after (foo bar) @@ -331,7 +331,7 @@ 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 +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. @@ -340,14 +340,14 @@ those declarations, your package will never be loaded. @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 +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" +@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 +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. @@ -386,7 +386,7 @@ A more literal way to do the exact same thing is: @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 +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. @@ -402,7 +402,7 @@ The @code{:bind} keyword takes either a cons or a list of conses: 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 +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: @@ -436,7 +436,7 @@ The effect of this statement is to wait until @code{helm} has loaded, and then t 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 +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 @@ -470,7 +470,7 @@ Here is the simplest @code{use-package} declaration: @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 +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. @@ -544,14 +544,14 @@ The @code{:custom-face} keyword allows customization of package custom faces. @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 +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 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. @@ -593,7 +593,7 @@ If you need to silence a missing function warning, you can use @code{:functions} @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 +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 @@ -612,7 +612,7 @@ package name with "-mode" appended at the end: @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, +end), both of these, or several lists of both. If no arguments are provided, the default mode name is hidden completely. @lisp @@ -654,7 +654,7 @@ 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 +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 @@ -684,7 +684,7 @@ 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 +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, @@ -729,7 +729,7 @@ Example: @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: +of the hook is required. Thus, all of the following are equivalent: @lisp (use-package ace-jump-mode @@ -804,8 +804,8 @@ the same thing as @code{:if (not foo)}. @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 +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 @@ -816,8 +816,8 @@ strings. If the path is relative, it is expanded within 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 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: @@ -836,7 +836,7 @@ up the same information again on each startup: 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 +variables. The specifier to either keyword can be a cons cell, a list of cons cells, or a string or regexp: @lisp @@ -875,8 +875,8 @@ This does exactly the same thing as the following: 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: +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 @@ -895,9 +895,9 @@ string @code{"%PDF"}. 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 +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 +@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 @@ -913,8 +913,8 @@ such cases, use the @code{:no-require} keyword: 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: +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