Merge pull request from skangas/texinfo-wip
GitHub-reference: https://github.com/jwiegley/use-package/issues/1018
This commit is contained in:
commit
cf8ab8b52e
1 changed files with 84 additions and 84 deletions
|
@ -8,7 +8,7 @@
|
|||
|
||||
@copying
|
||||
@quotation
|
||||
Copyright (C) 2012-2022 John Wiegley <johnw@@newartisans.com>
|
||||
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
|
||||
|
|
Loading…
Add table
Reference in a new issue