diff options
| author | Craig Jennings <c@cjennings.net> | 2025-09-03 23:51:56 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2025-09-03 23:51:56 -0500 |
| commit | 34cadedc4bdbf6f2e4671ad4171f79a8192d81d3 (patch) | |
| tree | 3fa4c33e1cde77312a8b1094ca459cb73a8de445 /assets/use-package.info | |
| parent | dfccb4c4043156384cc4421a38feaee539a6387a (diff) | |
| download | dotemacs-34cadedc4bdbf6f2e4671ad4171f79a8192d81d3.tar.gz dotemacs-34cadedc4bdbf6f2e4671ad4171f79a8192d81d3.zip | |
moving the use-package info file into it's proper place
Diffstat (limited to 'assets/use-package.info')
| -rw-r--r-- | assets/use-package.info | 2386 |
1 files changed, 0 insertions, 2386 deletions
diff --git a/assets/use-package.info b/assets/use-package.info deleted file mode 100644 index 00197f3f..00000000 --- a/assets/use-package.info +++ /dev/null @@ -1,2386 +0,0 @@ -This is use-package.info, produced by texi2any version 7.1 from -use-package.texi. - -This manual is for use-package, a configuration macro for simplifying -your init file. - - Copyright © 2022 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.3 or any later version published by the Free Software - Foundation; with no Invariant Sections, with the Front-Cover Texts - being "A GNU Manual", and with the Back-Cover Texts as in (a) - below. A copy of the license is included in the section entitled - "GNU Free Documentation License". - - (a) The FSF's Back-Cover Text is: "You have the freedom to copy and - modify this GNU manual." -INFO-DIR-SECTION Emacs misc features -START-INFO-DIR-ENTRY -* use-package: (use-package). Declarative package configuration for Emacs. -END-INFO-DIR-ENTRY - - -File: use-package.info, Node: Top, Next: Basic Concepts, Up: (dir) - -use-package User Manual -*********************** - -The ‘use-package’ macro allows you to isolate package customization in -your init file in a declarative way. It takes care of a lot of things -for you that would otherwise require a lot of repetitive boilerplate -code. It can help with common customization, such as binding keys, -setting up hooks, customizing user options and faces, autoloading, and -more. It also helps you keep Emacs startup fast, even when you use many -(even hundreds) of packages. - - Note that use-package is not a package manager. Although use-package -does have the useful capability to interface with the Emacs package -manager, its primary purpose is for the configuration and loading of -packages. - - This manual is for use-package, a configuration macro for simplifying -your init file. - - Copyright © 2022 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.3 or any later version published by the Free Software - Foundation; with no Invariant Sections, with the Front-Cover Texts - being "A GNU Manual", and with the Back-Cover Texts as in (a) - below. A copy of the license is included in the section entitled - "GNU Free Documentation License". - - (a) The FSF's Back-Cover Text is: "You have the freedom to copy and - modify this GNU manual." - -* Menu: - -* Basic Concepts:: Basic concepts of use-package. -* Getting Started:: A gentle introduction to use-package. -* Loading Packages:: How and when packages are loaded. -* Configuring Packages:: Package configuration keywords. -* Installing packages:: Ensuring packages are available. -* Byte-compiling:: Byte-compiling your init file. -* Troubleshooting:: What to do when there's trouble. - -Appendices -* Keyword extensions:: Adding new use-package keywords. -* History:: History and acknowledgments. -* GNU Free Documentation License:: The license for this manual. -* Index:: - - -File: use-package.info, Node: Basic Concepts, Next: Getting Started, Prev: Top, Up: Top - -1 Basic Concepts -**************** - -use-package provides the ‘use-package’ macro, that simplifies the -customization and use of packages in Emacs. It was created for a few -basic reasons, each of which drove the design. Understanding these -reasons may help make some of those decisions clearer: - - 1. To gather all configuration details of a package into one place, - making it easier to copy, disable, or move it elsewhere in the init - file. - - 2. To reduce duplication and boilerplate, capturing several common - practices as mere keywords both easy and intuitive to use. - - 3. To make startup time of Emacs as quick as possible, without - sacrificing the quantity of add-on packages used. - - 4. To make it so errors encountered during startup disable only the - package raising the error, and as little else as possible, leaving - as close to a functional Emacs as possible. - - 5. 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 used for speed (reason 3), it can still be - used as a sanity check. - - It is worth noting that use-package is not intended to replace the -standard ‘M-x customize’. On the contrary, it is designed to work -together with it, for things that customize cannot do. - - -File: use-package.info, Node: Getting Started, Next: Loading Packages, Prev: Basic Concepts, Up: Top - -2 Getting Started -***************** - -This chapter provides instructions and examples for quickly getting -started with use-package. The first thing you need to do is make sure -that ‘use-package’ itself is loaded. To do that, put this at the top of -your init file: - - (require 'use-package) - - The above makes the ‘use-macro’ for in the rest of your init file. -In this manual, we call each call to ‘use-macro’ a “declaration”, to -highlight the declarative nature of its semantic. - - To unconditionally load a package named ‘foo’, add the following -declaration to your init file: - - (use-package foo) - -This declaration is equivalent to using ‘require’, with some use-package -specific error handling added in. Just like require, it needs the -package ‘foo’ to be installed and available in your ‘load-path’ (*note -Installing packages::). - - To evaluate Lisp code _before_ the ‘foo’ package is loaded, use the -‘:init’ keyword: - - (use-package foo - :init - (setq foo-variable t)) - - Similarly, ‘:config’ can be used to execute code _after_ a package is -loaded. In cases where loading is done lazily (*note Loading -Packages::), this execution is deferred until after the autoload occurs. -As you might expect, you can use ‘:init’ and ‘:config’ together: - - (use-package foo - :init - (setq foo-variable t) - :config - (foo-mode 1)) - - The above declarations will all load the ‘foo’ package immediately. -In most cases, this is not necessary or desirable, as that will slow -down Emacs startup. Instead, you should try to set things up so that -packages are only loaded when they are actually needed (autoloading). -If you have installed a package from GNU ELPA that provides it's own -autoloads, it is often enough to say: - - (use-package foo - :defer t) - -This will avoid loading the package. Now, when you run any autoloaded -command, the package ‘foo’ is loaded automatically. Package authors -will make their own decisions about which commands are marked to -autoload by default. - - In some cases, you might need or want to provide your own autoloads. -The below more complex example autoloads the commands ‘isearch-moccur’ -and ‘isearch-all’ from ‘color-moccur.el’, and binds keys both globally -and in ‘isearch-mode-map’. When one of these commands are used, the -package is loaded. At that point, ‘moccur-edit’ is also loaded, to -allow editing of the ‘moccur’ buffer. - - (use-package color-moccur - :commands (isearch-moccur isearch-all) - :bind (("M-s O" . moccur) - :map isearch-mode-map - ("M-o" . isearch-moccur) - ("M-O" . isearch-moccur-all)) - :init - (setq isearch-lazy-highlight t) - :config - (use-package moccur-edit)) - - Some packages will suggest ready-made ‘use-package’ declarations that -you can use. Where possible, it is a good idea to copy them, and use -that as a starting point. - - That should be enough to get you started! - - -File: use-package.info, Node: Loading Packages, Next: Configuring Packages, Prev: Getting Started, Up: Top - -3 Loading Packages -****************** - -Before use-package can load an Emacs Lisp package, it must be available -in a directory on your ‘load-path’. When you install packages using the -built-in ‘install-package’ command, it will do this automatically for -you. Packages shipped with Emacs (built-in packages) are always -available. - - If you install packages manually, you must make sure they are -available on your ‘load-path’. *Note (emacs)Lisp Libraries:: for -details. - - Some packages have more than one library. In those cases, you might -need more than one ‘use-package’ declaration to make sure it is properly -loaded. For complex configurations, you might also need more than one -declaration for a package with the same name. - - use-package can interface with ‘package.el’ to install packages on -Emacs start. *Note Installing packages:: for details. - -* Menu: - -* Loading basics:: How and when packages are loaded. -* Deferring loading:: Loading packages later. -* Forcing loading:: Loading packages immediately. -* Conditional loading:: Loading packages conditionally. -* Loading sequentially:: Loading packages in sequence. -* Load dependencies:: Don't load without dependencies. -* Load path:: Using a custom ‘load-path’. -* Manual autoloads:: Setting up autoloads manually. - - -File: use-package.info, Node: Loading basics, Next: Deferring loading, Up: Loading Packages - -3.1 How and when use-package loads packages -=========================================== - -The ‘use-package’ macro either will either load a package immediately, -or when they are first used (autoloading). In the simplest case, a -‘use-package’ declaration loads a package when it is evaluated.(1) If -the declaration is in your init file, this happens automatically each -time Emacs is started. - - For example, the below declaration immediately loads the library -‘foo’, just like ‘require’ would. If the library ‘foo’ is not available -in your ‘load-path’, it logs a warning to the ‘*Messages*’ buffer: - - (use-package foo) - - Note that a "package" is different from an Emacs Lisp "library". The -above declaration tells use-package to load the _library_ ‘foo.el’, -which the overwhelming majority of cases also resides in a _package_ -named ‘foo’. But the ‘foo’ package might also contain a library named -‘foo-extra.el’. If that library is not loaded automatically, you will -need a separate ‘use-package’ declaration to make sure that it is. This -manual will often use these terms interchangeably, as this distinction -does not usually matter, but you should keep it in mind for the cases -when it does. - - The details of how and when you should load a package might differ -from one package to another. When in doubt, refer to the package -documentation for details. - - ---------- Footnotes ---------- - - (1) This happens both at run-time and at compile-time. *Note -Byte-compiling::. - - -File: use-package.info, Node: Deferring loading, Next: Forcing loading, Prev: Loading basics, Up: Loading Packages - -3.2 Deferring package loading -============================= - -In the examples we have seen so far, use-package loads packages every -time you start Emacs, even if that package is never used. That will -make starting Emacs slower. use-package therefore tries to set things -up in such a way that it only loads packages when a command is first -used (either with ‘M-x’ or some key binding). This is based on -autoloading, a full description of which is outside the scope of this -manual. *Note (elisp)Autoload:: for the full story. - - Some ‘use-package’ keywords provide autoload “triggers” that cause a -package to be loaded when certain events occur. For example, the -‘:hook’ keyword sets up a trigger that fires when the specified hook is -run, and then loads the package automatically. The other trigger -keywords, all of which are described later in this manual, are -‘:commands’, ‘:bind’, ‘:bind*’, ‘:bind-keymap’, ‘:bind-keymap*’, -‘:mode’, and ‘:interpreter’. - -The ‘:defer’ keyword --------------------- - -If you did not specify any autoloading keyword, use-package will fall -back to loading the package immediately (typically when Emacs is -starting up). This can be overridden using the ‘:defer’ keyword. It -takes one boolean argument: a non-‘nil’ value means to stop this package -from being immediately loaded. Here is an example of using ‘:defer’ to -postpone loading the package ‘foo’: - - (use-package foo - :defer t) - - Using ‘:defer t’ by itself like this is rarely useful. Typically, -you would only use it together with a keyword like ‘:config’ (*note Lisp -Configuration::), or ‘:ensure’ (*note Installing packages::). - -Defer loading until idle for N seconds --------------------------------------- - -You can also give a numeric argument N to ‘:defer’ to specify that a -package should be loaded (if it hasn't already) after Emacs has been -idle for N seconds. For example, use this to make use-package load -‘foo’ after 30 seconds of idle time: - - (use-package foo - :defer 30) - -When to use ‘:defer’ --------------------- - -When using autoloading keywords, there is no need to also use ‘:defer’. -It doesn't hurt anything to add it in this case, perhaps for extra -clarity, but it is redundant. - - You should use ‘:defer’ to force deferred loading, in cases when -use-package isn't creating any autoloads for you. For example, you -might know that some other package will already do something to cause -your package to load at the appropriate time. This is usually the case -when you install a package using ‘package-install’, as packages -installed in this way normally always have their own autoloads already -set up. - -Making ‘:defer t’ the default ------------------------------ - -If you customize the user option ‘use-package-always-defer’ to -non-‘nil’, the ‘use-package’ macro will behave as if ‘:defer t’ is -always specified. This can be overridden for individual declarations -using either ‘:defer nil’ or ‘:demand t’ (*note Forcing loading::). - - -File: use-package.info, Node: Forcing loading, Next: Conditional loading, Prev: Deferring loading, Up: Loading Packages - -3.3 Forcing package to load immediately -======================================= - -The presence of autoloading trigger keywords can be overridden using -‘:demand t’, which forces the package to load immediately. Thus, even -if you use an autoloading keyword such as ‘:bind’ (*note Key -bindings::), adding ‘:demand’ will force loading to occur immediately. -It will also avoid creating an autoload for the bound key, as it would -be redundant. - - If you specify both ‘:demand t’ and ‘:defer t’, the ‘:defer’ keyword -will take precedence. - - -File: use-package.info, Node: Conditional loading, Next: Loading sequentially, Prev: Forcing loading, Up: Loading Packages - -3.4 Loading packages conditionally -================================== - -The ‘:if’, ‘:when’, and ‘:unless’ keywords predicates the loading and -initialization of packages. They all accept one argument, an Emacs Lisp -form that is evaluated at run-time. - - If the argument of the ‘:if’ keyword evaluates to non-‘nil’, the -package will be loaded and initialized. The ‘:when’ keyword is provided -as an alias for ‘:if’. Finally, the ‘:unless’ keyword is the inverse of -‘:if’, such that ‘:unless foo’ means the same thing as ‘:if (not foo)’. - - For example, if you only want to load ‘foo’ in graphical Emacs -sessions, you could use the following: - - (use-package foo - :if (display-graphic-p)) - -Some common use cases ---------------------- - -Here are some common cases for conditional loading, and how to achieve -them. - - • Operating system - - This example loads a package only on GNU/Linux. See the - ‘system-type’ docstring for other valid values. - - :if (eq system-type 'gnu/linux) - - • Window system - - This example loads a package only on macOS and X. See the - ‘window-system’ docstring for valid values. - - :if (memq window-system '(ns x)) - - • Installed package - - This example loads a package only when the ‘foo’ package is - installed. - - :if (package-installed-p 'foo) - - • Libraries in ‘load-path’ - - This example loads a package only when ‘foo.el’ is available in - your ‘load-path’ (for example, if you installed that file - manually): - - :if (locate-library "foo.el") - -Making conditional loading affect ‘:preface’ and ‘:ensure’ ----------------------------------------------------------- - -If you need to conditionalize a use-package form so that the condition -occurs before even ‘:ensure’ or ‘:preface’, use ‘when’ around the -use-package form itself. For example: - - (when (memq window-system '(mac ns)) - (use-package foo - :ensure t)) - - -File: use-package.info, Node: Loading sequentially, Next: Load dependencies, Prev: Conditional loading, Up: Loading Packages - -3.5 Loading packages in sequence -================================ - -Sometimes it only makes sense to configure a package after another one -has been loaded, because certain variables or functions are not in scope -until that time. This can achieved with the ‘:after’ keyword, which -allows a fairly rich description of the exact conditions when loading -should occur. It takes either a symbol indicating the package name, a -list of such symbols, or a list of selectors (see below). - - Here is an example of using the GNU ELPA packages hydra, ivy, and -ivy-hydra. Note that ivy-hydra will always be loaded last: - - (use-package hydra) - - (use-package ivy) - - (use-package ivy-hydra - :after (ivy hydra)) - - In this case, because the declarations are evaluated in the order -they occur, the use of ‘:after’ is not strictly necessary. However, if -‘hydra’ and ‘ivy’ were to be autoloaded, using ‘:after’ guarantees that -‘ivy-hydra’ is not loaded until it is actually needed. By using -‘:after’, the above code will also work even if the order of the -declaration changes. This means that moving things around in your init -file is less likely to break things. - -Using ‘:after’ selectors ------------------------- - -The ‘:after’ keyword also accepts a list of selectors. By default, -‘:after (foo bar)’ is the same as ‘:after (:all foo bar)’, meaning that -loading of the given package will not happen until both ‘foo’ and ‘bar’ -have been loaded. Here are some of the other possibilities: - -:after (foo bar) -:after (:all foo bar) -:after (:any foo bar) -:after (:all (:any foo bar) (:any baz quux)) -:after (:any (:all foo bar) (:all baz quux)) - - When you nest selectors, such as ‘(:any (:all foo bar) (:all baz -quux))’, it means that the package will be loaded when either both ‘foo’ -and ‘bar’ have been loaded, or when both ‘baz’ and ‘quux’ have been -loaded. - - Pay attention when setting ‘use-package-always-defer’ to a non-‘nil’ -value, and also using the ‘:after’ keyword. In this case, you will need -to specify how the declared package is to be loaded: for example, by -some ‘:bind’. If you are not using one of the keywords that registers -autoloads, such as ‘:bind’ or ‘:hook’, and your package manager does not -provide autoloads, it is possible that your package will never be loaded -if you do not add ‘:demand t’ to those declarations. - - -File: use-package.info, Node: Load dependencies, Next: Load path, Prev: Loading sequentially, Up: Loading Packages - -3.6 Prevent loading if dependencies are missing -=============================================== - -While the ‘:after’ keyword delays loading until the dependencies are -loaded, the somewhat simpler ‘:requires’ keyword _never_ loads the -package if the dependencies are not available when the ‘use-package’ -declaration is evaluated. In this context, "available" means that ‘foo’ -is available if ‘(featurep 'foo)’ evaluates to a non-‘nil’ value. For -example: - - (use-package abbrev - :requires foo) - - This is the same as: - - (use-package abbrev - :if (featurep 'foo)) - - As a convenience, a list of such packages may be specified: - - (use-package abbrev - :requires (foo bar baz)) - - For more complex logic, such as that supported by ‘:after’, simply -use ‘:if’ and the appropriate Lisp expression. - - -File: use-package.info, Node: Load path, Next: Manual autoloads, Prev: Load dependencies, Up: Loading Packages - -3.7 Setting a custom ‘load-path’ -================================ - -If a package resides in some directory that is not in your ‘load-path’, -use the ‘:load-path’ keyword to add it. It takes a symbol, a function, -a string or a list of strings. If the path is relative, it is expanded -within ‘user-emacs-directory’. - - For example: - - (use-package ess-site - :load-path "site-lisp/ess/lisp/" - :commands R) - - 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 that the value is available at byte-compilation time. -This is done by using the special form ‘eval-and-compile’ (as opposed to -‘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. For example: - - (eval-and-compile - (defun ess-site-load-path () - (shell-command "find ~ -path ess/lisp"))) - - (use-package ess-site - :load-path (lambda () (list (ess-site-load-path))) - :commands R) - - -File: use-package.info, Node: Manual autoloads, Prev: Load path, Up: Loading Packages - -3.8 Setting up autoloads manually -================================= - -To autoload an interactive command, use the ‘:commands’ keyword. When -you use the ‘:commands’ keyword, it creates autoloads for those commands -(which defers loading of the module until they are used). The -‘:commands’ keyword takes either a symbol or a list of symbols. - - The ‘:autoload’ keyword works like ‘:commands’, but is used to -autoload non-interactive functions. Here is an example: - - (use-package org-crypt - :autoload org-crypt-use-before-save-magic) - - -File: use-package.info, Node: Configuring Packages, Next: Installing packages, Prev: Loading Packages, Up: Top - -4 Configuring Packages -********************** - -This chapter describes the various keywords provided by ‘use-package’ -that helps you configure packages. - -* Menu: - -* Lisp Configuration:: Using Lisp to configure packages. -* Key bindings:: Making your own keybindings. -* Hooks:: Adding functions to hooks. -* Modes and interpreters:: Enabling modes automatically. -* Magic handlers:: Using regexps to enable modes. -* User options:: Setting user options. -* Faces:: Customizing faces. -* Hiding minor modes:: Tidying up the mode line. - - -File: use-package.info, Node: Lisp Configuration, Next: Key bindings, Up: Configuring Packages - -4.1 Using Lisp code for configuring packages -============================================ - -The most general way to add customizations are the ‘:preface’, ‘:init’, -and ‘:config’ keywords. They all accept one or more Emacs Lisp forms, -up to the next keyword, that are evaluated in order. This lets you add -arbitrary Lisp code to your ‘use-package’ declarations. - - The only difference between these keywords is when they are -evaluated. - -* Menu: - -* Preface keyword:: Evaluate code before anything else. -* Init keyword:: Evaluate code before loading package. -* Config keyword:: Evaluate code after loading package. -* Best practices:: When to use ‘:config’, ‘:init’, and ‘:preface’. - - -File: use-package.info, Node: Preface keyword, Next: Init keyword, Up: Lisp Configuration - -4.1.1 ‘:preface’ is evaluated first ------------------------------------ - -The ‘:preface’ section is evaluated before anything else, except -‘:disabled’ and ‘:ensure’. It can be used to establish function and -variable definitions that will: - - 1. Make the byte-compiler happy. It will not complain about functions - whose definitions are unknown because you have them within a guard - block. - - 2. Define code that can be used in an ‘:if’ test. - - Note that whatever is specified within ‘:preface’ is evaluated both -at load time and at byte-compilation time, in order to ensure that -definitions are seen by both the Lisp evaluator and the byte-compiler. -Therefore, you should avoid having any side-effects in your preface, and -restrict it to symbol declarations and definitions. - - -File: use-package.info, Node: Init keyword, Next: Config keyword, Prev: Preface keyword, Up: Lisp Configuration - -4.1.2 ‘:init’ is evaluated before loading package -------------------------------------------------- - -The ‘:init’ section is evaluated just before the package is loaded. -Note that the ‘:init’ form is run unconditionally - even if the ‘foo’ -package happens to not exist on your system. You must therefore -remember to restrict ‘:init’ code to only what would succeed either way. -‘:init’ also always happens before package load, whether ‘:config’ has -been deferred or not. - - -File: use-package.info, Node: Config keyword, Next: Best practices, Prev: Init keyword, Up: Lisp Configuration - -4.1.3 ‘:config’ is evaluated after loading package --------------------------------------------------- - -The ‘:config’ section is evaluated after the package has been loaded. -If the package is loaded immediately, this happens immediately after -that, but if loading is done lazily (*note Loading Packages::), this is -deferred until after the package has been loaded. - - In general, you should keep ‘:init’ forms as simple and quick as -possible, and put as much as you can get away with into the ‘:config’ -section. That way, deferred loading can help your Emacs start as -quickly as possible. - - -File: use-package.info, Node: Best practices, Prev: Config keyword, Up: Lisp Configuration - -When to use ‘:preface’, ‘:config’ and ‘:init’? ----------------------------------------------- - -Where possible, it is better to avoid ‘:preface’, ‘:config’ and ‘:init’. -Instead, prefer autoloading keywords such as ‘:bind’, ‘:hook’, and -‘:mode’, as they will take care of setting up autoloads for you without -any need for boilerplate code. For example, consider the following -declaration: - - (use-package foo - :init - (add-hook 'some-hook 'foo-mode)) - - This has two problems. First, it will unconditionally load the -package ‘foo’ on startup, which will make things slower. You can fix -this by adding ‘:defer t’: - - (use-package foo - :defer t - :init - (add-hook 'some-hook 'foo-mode)) - - This is better, as ‘foo’ is now only loaded when it is actually -needed (that is, when the hook ‘some-hook’ is run). - - The second problem is that there is a lot of boilerplate that you -have to write. In this case, it might not be so bad, but avoiding that -was what use-package was made to avoid. The better option in this case -is therefore to use ‘:hook’ (*Note Hooks::), which also implies -‘:defer t’. The above is thereby reduced down to: - - (use-package foo - :hook some-hook) - - use-package will set up autoloading for you, and your Emacs startup -time will not suffer one bit. - - -File: use-package.info, Node: Key bindings, Next: Hooks, Prev: Lisp Configuration, Up: Configuring Packages - -4.2 Key bindings -================ - -One common thing to do when loading a package is to bind a key to -commands within that module. Without use-package, this would be done -using a combination of ‘keymap-local-set’, ‘keymap-global-set’ and -various autoloads. With use-package, you can simplify this using the -‘:bind’ keyword. - -* Menu: - -* Global keybindings:: Bindings you can use anywhere. -* Binding in keymaps:: Bindings for particular modes. -* Binding to a keymap:: Binding a key to a keymap. -* Binding to repeat-maps:: Binding repeating keys. -* Displaying keybindings:: Displaying personal key bindings. - - -File: use-package.info, Node: Global keybindings, Next: Binding in keymaps, Up: Key bindings - -4.2.1 Global keybindings ------------------------- - -To bind keys globally, the ‘:bind’ keyword takes as its argument either -a single cons or a list of conses. Each cons has the form -‘(KEY . DEFINITION)’, where KEY is a string indicating the key to bind, -and DEFINITION is the name of a command (a symbol). Alternatively, -DEFINITION may be a cons ‘(DESC . COMMAND)’, where DESC is a string -describing COMMAND, which is the name of a command to bind KEY to. The -syntax for the keys is similar to the syntax used by the ‘kbd’ function -(see *note (emacs)Init Rebinding::, for more information). - -Using ‘:bind’ with a single cons --------------------------------- - -Here is an example of using a single cons: - - (use-package ace-jump-mode - :bind ("C-." . ace-jump-mode)) - - This does two things: first, it creates an autoload for the -‘ace-jump-mode’ command and defers loading of the ‘ace-jump-mode’ -package until you actually use it. Second, it binds the key ‘C-.’ to -that command globally. - -Using ‘:bind’ with a list of conses ------------------------------------ - -Here is an example of using ‘:bind’ with a list of conses: - - (use-package hi-lock - :bind (("M-o l" . highlight-lines-matching-regexp) - ("M-o r" . highlight-regexp) - ("M-o w" . highlight-phrase))) - -Using special keys ------------------- - -Inside key strings, special keys like ‘TAB’ or ‘F1’-‘F12’ have to be -written inside angle brackets, e.g. ‘"C-<up>"’. Standalone special -keys (and some combinations) can be written in square brackets, -e.g. ‘[tab]’ instead of ‘"<tab>"’. - - Examples: - - (use-package helm - :bind (("M-x" . helm-M-x) - ("M-<f5>" . helm-find-files) - ([f10] . helm-buffers-list) - ([S-f10] . helm-recentf))) - -Providing custom descriptions of commands ------------------------------------------ - -When binding keys to commands with ‘:bind’, custom descriptions of the -commands may optionally be provided. - - Examples: - - (use-package avy - :bind ("C-:" ("Jump to char" . avy-goto-char) - "M-g f" ("Jump to line" . avy-goto-line))) - -These descriptions can be used by other code that deals with key -bindings. For example, the GNU ELPA package ‘which-key’ displays them -when showing key bindings, instead of the plain command names. - -Remapping commands ------------------- - -Remapping commands with ‘:bind’ and ‘bind-key’ works as expected, -because when the binding is a vector, it is passed straight to -‘define-key’. *Note (elisp)Remapping Commands::) for more information -about command remapping. For example, the following declaration will -rebind ‘fill-paragraph’ (bound to ‘M-q’ by default) to ‘unfill-toggle’: - - (use-package unfill - :bind ([remap fill-paragraph] . unfill-toggle)) - -What ‘:bind’ does behind the scenes ------------------------------------ - -To understand what ‘:bind’ does behind the scenes, it might be useful to -consider an example: - - (use-package ace-jump-mode - :bind ("C-." . ace-jump-mode)) - - This could be expressed in a much more verbose way with the -‘:commands’ and ‘:init’ keywords. - - (use-package ace-jump-mode - :commands ace-jump-mode - :init - (bind-key "C-." 'ace-jump-mode)) - - Without using even the ‘:commands’ keyword, we could also write the -above like so: - - (use-package ace-jump-mode - :defer t - :init - (autoload 'ace-jump-mode "ace-jump-mode" nil t) - (bind-key "C-." 'ace-jump-mode)) - - Although these three forms are all equivalent, the first form is -usually the best, as it will save some typing. - - -File: use-package.info, Node: Binding in keymaps, Next: Binding to a keymap, Prev: Global keybindings, Up: Key bindings - -4.2.2 Key bindings in local keymaps ------------------------------------ - -Slightly different from binding a key to a keymap, is binding a key -_within_ a local keymap that only exists after the package is loaded. -‘use-package’ supports this with a ‘:map’ modifier, taking the local -keymap to bind to: - - (use-package helm - :bind (:map helm-command-map - ("C-c h" . helm-execute-persistent-action))) - - The effect of this statement is to wait until ‘helm’ has loaded, and -then to bind the key ‘C-c h’ to ‘helm-execute-persistent-action’ within -Helm's local keymap, ‘helm-command-map’. - - Multiple uses of ‘:map’ may be specified. Any binding occurring -before the first use of ‘:map’ are applied to the global keymap: - - (use-package term - :bind (("C-c t" . term) - :map term-mode-map - ("M-p" . term-send-up) - ("M-n" . term-send-down) - :map term-raw-map - ("M-o" . other-window) - ("M-p" . term-send-up) - ("M-n" . term-send-down))) - - -File: use-package.info, Node: Binding to a keymap, Next: Binding to repeat-maps, Prev: Binding in keymaps, Up: Key bindings - -4.2.3 Binding to keymaps ------------------------- - -Normally ‘:bind’ expects that commands are functions that will be -autoloaded 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 the built-in ‘autoload’ function. - - To handle this case, ‘use-package’ offers a special, limited variant -of ‘:bind’ called ‘:bind-keymap’. The only difference is that the -"commands" bound to by ‘:bind-keymap’ must be keymaps defined in the -package, rather than 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. - - For example: - - (use-package foo - :bind-keymap ("C-c p" . foo-command-map)) - - -File: use-package.info, Node: Binding to repeat-maps, Next: Displaying keybindings, Prev: Binding to a keymap, Up: Key bindings - -4.2.4 Binding to repeat-maps ----------------------------- - -A special case of binding within a local keymap is when that keymap is -used by ‘repeat-mode’ *note (emacs)Repeating::. These keymaps are -usually defined specifically for this. Using the ‘:repeat-map’ keyword, -and passing it a name for the map it defines, will bind all following -keys inside that map, and (by default) set the ‘repeat-map’ property of -each bound command to that map. - - The following example creates a keymap called -‘git-gutter+-repeat-map’, makes four bindings in it as above, then sets -the ‘repeat-map’ property of each bound command (‘git-gutter+-next-hunk’ -‘git-gutter+-previous-hunk’, ‘git-gutter+-stage-hunks’ and -‘git-gutter+-revert-hunk’) to that keymap. - - (use-package git-gutter+ - :bind - (:repeat-map git-gutter+-repeat-map - ("n" . git-gutter+-next-hunk) - ("p" . git-gutter+-previous-hunk) - ("s" . git-gutter+-stage-hunks) - ("r" . git-gutter+-revert-hunk))) - - Specifying ‘:exit’ inside the scope of ‘:repeat-map’ will prevent the -‘repeat-map’ property being set, so that the command can be used from -within the repeat map, but after it using it the repeat map will no -longer be available. This is useful for commands often used at the end -of a series of repeated commands: - - (use-package git-gutter+ - :bind - (:repeat-map my/git-gutter+-repeat-map - ("n" . git-gutter+-next-hunk) - ("p" . git-gutter+-previous-hunk) - ("s" . git-gutter+-stage-hunks) - ("r" . git-gutter+-revert-hunk) - :exit - ("c" . magit-commit-create) - ("C" . magit-commit) - ("b" . magit-blame))) - - Specifying ‘:continue’ _forces_ setting the ‘repeat-map’ property -(just like _not_ specifying ‘:exit’), so the above snippet is equivalent -to: - - (use-package git-gutter+ - :bind - (:repeat-map my/git-gutter+-repeat-map - :exit - ("c" . magit-commit-create) - ("C" . magit-commit) - ("b" . magit-blame) - :continue - ("n" . git-gutter+-next-hunk) - ("p" . git-gutter+-previous-hunk) - ("s" . git-gutter+-stage-hunks) - ("r" . git-gutter+-revert-hunk))) - - -File: use-package.info, Node: Displaying keybindings, Prev: Binding to repeat-maps, Up: Key bindings - -4.2.5 Displaying personal keybinding ------------------------------------- - -The ‘:bind’ keyword uses the ‘bind-keys’ macro from the ‘bind-key.el’ -library to set up keybindings. It keeps track of all keybindings you -make, so that you can display them separately from the default -keybindings. - - Use ‘M-x describe-personal-keybindings’ to see all keybindings you've -set using either the ‘:bind’ keyword or the ‘bind-keys’ macro. - - -File: use-package.info, Node: Hooks, Next: Modes and interpreters, Prev: Key bindings, Up: Configuring Packages - -4.3 Hooks -========= - -The ‘:hook’ keyword allows adding functions onto hooks. It takes one -argument of the form HOOKS, specifying one or more functions to add to -one or more hooks. For the purposes of ‘:hook’, the name of hook -variables should always exclude the ‘-hook’ suffix. It is appended -automatically for you, to save some typing. - - For example, consider the following ‘use-package’ declaration that -sets up autoloads for ‘company-mode’ from the ‘company’ package, and -adds ‘company-mode’ to ‘prog-mode-hook’: - - (use-package company - :commands company-mode - :init - (add-hook 'prog-mode-hook #'company-mode)) - - Using ‘:hook’, this can be simplified to: - - (use-package company - :hook (prog-mode . company-mode)) - - Here, ‘:hook’ will automatically set up autoloads for the -‘company-mode’ command, so there is no need to use ‘:commands’. - - The ‘:hook’ keyword will also assume that the name of the function -you want to add is the same as the package name with ‘-mode’ appended to -it. Taking this into account, you can simplify the above to the -equivalent: - - (use-package company - :hook prog-mode) - - You can also provide a list of hooks. When multiple hooks should be -applied, the following examples are all equivalent: - - (use-package company - :hook (prog-mode text-mode)) - - (use-package company - :hook ((prog-mode text-mode) . company-mode)) - - (use-package company - :hook ((prog-mode . company-mode) - (text-mode . company-mode))) - - (use-package company - :commands company-mode - :init - (add-hook 'prog-mode-hook #'company-mode) - (add-hook 'text-mode-hook #'company-mode)) - - One common mistake when using ‘:hook’ is to forget to omit the -‘-hook’ suffix, which, as already explained, is appended automatically. -Therefore, the following will not work, as it attempts to add a function -to non-existent ‘prog-mode-hook-hook’: - - ;; DOES NOT WORK - (use-package ace-jump-mode - :hook (prog-mode-hook . ace-jump-mode)) - - If you do not like this behavior, you can customize the user option -‘use-package-hook-name-suffix’ to ‘nil’. The value of this variable is -‘"-hook"’ by default. - - The use of ‘:hook’, as with ‘:bind’, ‘:mode’, ‘:interpreter’, etc., -causes the functions being hooked to implicitly be read as ‘:commands’. -This means that they will establish interactive ‘autoload’ definitions -for that module, if not already defined as functions), and so ‘:defer t’ -is also implied by ‘:hook’. - - -File: use-package.info, Node: Modes and interpreters, Next: Magic handlers, Prev: Hooks, Up: Configuring Packages - -4.4 Modes and interpreters -========================== - -Similar to ‘:bind’, you can use ‘:mode’ and ‘:interpreter’ to establish -a deferred binding within the ‘auto-mode-alist’ and -‘interpreter-mode-alist’ variables. The specifier to either keyword can -be a cons cell, a list of cons cells, or a string or regexp. - - The following example reproduces the default ‘ruby-mode’ -configuration, exactly as it is in Emacs out-of-the-box. That mode is -enabled automatically when a file whose name matches the regexp -‘"\\.rb\\'"’ (a file with the ‘.rb’ extension), or when the first line -of the file (known as the "shebang") matches the string ‘"ruby"’: - - (use-package ruby-mode - :mode "\\.rb\\'" - :interpreter "ruby") - - The default ‘python-mode’ configuration can be reproduced using the -below declaration. Note that the package that should be loaded differs -from the mode name in this case, so we must use a cons: - - ;; The package is "python" but the mode is "python-mode": - (use-package python - :mode ("\\.py\\'" . python-mode) - :interpreter ("python" . python-mode)) - - Both the ‘:mode’ and ‘:interpreter’ keywords also accept a list of -regexps: - - (use-package foo - ;; Equivalent to "\\(ba[rz]\\)\\'": - :mode ("\\.bar\\'" "\\.baz\\'") - ;; Equivalent to "\\(foo[ab]\\)": - :interpreter ("fooa" "foob")) - - -File: use-package.info, Node: Magic handlers, Next: User options, Prev: Modes and interpreters, Up: Configuring Packages - -4.5 Magic handlers -================== - -Similar to ‘:mode’ and ‘:interpreter’, you can also use ‘:magic’ and -‘:magic-fallback’ to cause certain function to be run if the beginning -of a file matches a given regular expression. The difference between -‘:magic’ and ‘:magic-fallback’, is that the latter has a lower priority -than ‘:mode’. - - Here is an example: - - (use-package pdf-tools - :magic ("%PDF" . pdf-view-mode) - :config - (pdf-tools-install :no-query)) - - This registers an autoloaded command for ‘pdf-view-mode’, defers -loading of ‘pdf-tools’, and runs ‘pdf-view-mode’ if the beginning of a -buffer matches the string ‘"%PDF"’. - - -File: use-package.info, Node: User options, Next: Faces, Prev: Magic handlers, Up: Configuring Packages - -4.6 User options -================ - -In Emacs, you normally set customizable variables (user options) using -the ‘M-x customize’ interface (*note (emacs)Easy Customization::). We -recommended this method for most users. However, it is also possible to -set them in your ‘use-package’ declarations by using the ‘:custom’ -keyword. - - (use-package comint - :defer t - :custom - (comint-buffer-maximum-size 20000 "Increase comint buffer size.") - (comint-prompt-read-only t "Make the prompt read only.")) - - This is better than using ‘setq’ in a ‘:config’ block, as -customizable variables might have some code associated with it that -Emacs will execute when you assign values to them. In Emacs 29, there -is also the new ‘setopt’ macro that does this for you. - - Note that the values customized using this keyword are _not_ saved in -the standard Emacs ‘custom-file’. You should therefore set each user -option using either the ‘:custom’ keyword _or_ ‘M-x customize-option’, -which will save customized values in the Emacs ‘custom-file’. Do not -use both for the same variable, as this risk having conflicting values -in your use-package declaration and your ‘custom-file’. This can lead -to problems that are both tricky and tedious to debug. - - -File: use-package.info, Node: Faces, Next: Hiding minor modes, Prev: User options, Up: Configuring Packages - -4.7 Faces -========= - -The ‘:custom-face’ keyword allows customization of package custom faces. - - (use-package eruby-mode - :custom-face - (eruby-standard-face ((t (:slant italic))))) - - (use-package example - :custom-face - (example-1-face ((t (:foreground "LightPink")))) - (example-2-face ((t (:foreground "LightGreen"))) face-defspec-spec)) - - (use-package zenburn-theme - :preface - (setq my/zenburn-colors-alist - '((fg . "#DCDCCC") (bg . "#1C1C1C") (cyan . "#93E0E3"))) - :custom-face - (region ((t (:background ,(alist-get my/zenburn-colors-alist 'cyan))))) - :config - (load-theme 'zenburn t)) - - -File: use-package.info, Node: Hiding minor modes, Prev: Faces, Up: Configuring Packages - -4.8 Hiding minor modes with diminish and delight -================================================ - -‘use-package’ supports the diminish and delight packages, both of which -make it possible remove or change minor mode strings in your mode-line. -Which one to use is up to you, but you should normally only use one or -the other - never both.(1) To use either of them, you must first -install the corresponding package from GNU ELPA. - -* Menu: - -* Diminish:: Hiding minor modes with Diminish. -* Delight:: Hiding minor modes with Delight. - - ---------- Footnotes ---------- - - (1) When in doubt, you might as well use diminish. - - -File: use-package.info, Node: Diminish, Next: Delight, Up: Hiding minor modes - -4.8.1 Diminish --------------- - -When diminish(1) is installed, you can use the ‘:diminish’ keyword. If -diminish is not installed, the ‘:diminish’ keyword does nothing. - - First, add the following declaration to the beginning of your init -file. The optional ‘:ensure t’ makes sure the package is installed if -it isn't already (*note Installing packages::). - - (use-package diminish :ensure t) - - The ‘:diminish’ keyword takes either a minor mode symbol, a cons of -the symbol and its replacement string, or just a replacement string, in -which case the minor mode symbol is guessed to be the package name with -‘-mode’ appended at the end: - - (use-package abbrev - :diminish abbrev-mode - :config - (if (file-exists-p abbrev-file-name) - (quietly-read-abbrev-file))) - - ---------- Footnotes ---------- - - (1) The diminish package is installable from GNU ELPA. - - -File: use-package.info, Node: Delight, Prev: Diminish, Up: Hiding minor modes - -4.8.2 Delight -------------- - -When delight(1) is installed, you can use the ‘:delight’ keyword. If -delight is not installed, the ‘:delight’ keyword does nothing. - - First, add the following declaration to the beginning of your init -file. The optional ‘:ensure t’ makes sure the package is installed if -it isn't already (*note Installing packages::). - - (use-package delight :ensure t) - - The ‘:delight’ keyword takes a minor mode symbol, a replacement -string, or quoted mode line data (in which case the minor mode symbol is -assumed to be the package name with ‘-mode’ appended at the end), both -of these, or several lists of both. *Note (elisp)Mode Line Data::. If -no arguments are provided, the default mode name is hidden completely. - - For example, the following hides everything for the ‘foo-mode’ minor -mode in the ‘foo’ package: - - (use-package foo - :delight) - - If the mode name doesn't match the package name with ‘-mode’ -appended, provide a symbol instead. For example, the following hides -‘auto-revert-mode’ from the mode line: - - ;; Don't show anything for auto-revert-mode, which doesn't match - ;; its package name. - (use-package autorevert - :delight auto-revert-mode) - - You can also run arbitrary Lisp code. For example, to replace -‘foo-mode’ with the value of the current buffer: - - (use-package foo - :delight '(:eval buffer-file-name)) - - Here is an example of hiding several built-in minor modes: - - ;; Completely hide visual-line-mode and change auto-fill-mode to " AF". - (use-package emacs - :delight - (auto-fill-function " AF") - (visual-line-mode)) - - ---------- Footnotes ---------- - - (1) The ‘delight’ package is installable from GNU ELPA. - - -File: use-package.info, Node: Installing packages, Next: Byte-compiling, Prev: Configuring Packages, Up: Top - -5 Installing packages automatically -*********************************** - -The standard Emacs package manager is documented in the Emacs manual -(*note (emacs)Package Installation::). The ‘use-package’ macro provides -the ‘:ensure’ and ‘:pin’ keywords, that interface with that package -manager to automatically install packages. This is particularly useful -if you use your init file on more than one system. - -* Menu: - -* Install package:: -* Pinning packages:: -* Other package managers:: - - -File: use-package.info, Node: Install package, Next: Pinning packages, Up: Installing packages - -5.1 Installing package -====================== - -The ‘:ensure’ keyword makes use-package ask the Emacs package manager to -install a package if it is not already present on your system. - - For example: - - (use-package magit - :ensure t) - - If you need to install a different package from the one named by -‘use-package’, you can use a symbol: - - (use-package tex - :ensure auctex) - - You can customize the user option ‘use-package-always-ensure’ to -non-‘nil’ if you want this behavior to be global for all packages. - - (require 'use-package-ensure) - (setq use-package-always-ensure t) - -You can override the above setting for a single package by adding -‘:ensure nil’ to its declaration. - - -File: use-package.info, Node: Pinning packages, Next: Other package managers, Prev: Install package, Up: Installing packages - -5.2 Pinning packages using ‘:pin’ -================================= - -use-package can pin a package to a specific archive using the ‘:pin’ -keyword.(1) This allows you to mix and match packages from different -archives. The primary use-case for this is preferring to install -packages from GNU ELPA or NonGNU ELPA (indicated by ‘gnu’ and ‘nongnu’, -respectively), while installing specific packages from third-party -archives. - - For example: - - (use-package company - :ensure t - :pin gnu) ; GNU ELPA - - Unfortunately, the third-party archive MELPA uses a versioning scheme -based on dates, which means that packages from that archive are always -preferred. If you are using that archive, we strongly encourage you to -customize ‘use-package-always-pin’ to ‘nongnu’. This guarantees that -you are using a version of that package that has been specifically -marked for release by its developer, and not a development snapshot. - - If you want to manually keep a package updated and ignore upstream -updates, you can pin it to ‘manual’. This will work as long as you have -not customized a repository to use that name in the ‘package-archives’ -variable. - - Example: - - (use-package org - :ensure t - ;; ignore org-mode from upstream and use a manually installed version - :pin manual) - - ‘use-package’ signals an error if you try to pin a package to an -archive that is not configured using ‘package-archives’ (except from the -special ‘manual’ archive). - - ---------- Footnotes ---------- - - (1) The ‘:pin’ keyword has no effect on Emacs versions older than -24.4. - - -File: use-package.info, Node: Other package managers, Prev: Pinning packages, Up: Installing packages - -5.3 Non-standard package managers -================================= - -By default, use-package assumes that you are using the built-in -‘package.el’ package manager. We expect that most users will find that -it is more than capable enough, even for advanced use cases. - - However, some users might prefer to use a third-party package manager -for a specific circumstance or use case. By setting the user option -‘use-package-ensure-function’ to the name of a function, you can direct -‘:ensure’ to use a different package manager for installing packages. - - For more details, please see the documentation of the package manager -you are using. If you run into any bugs, it is often best to report -them directly to the developers of that package manager. - - -File: use-package.info, Node: Byte-compiling, Next: Troubleshooting, Prev: Installing packages, Up: Top - -6 Byte-compiling your init file -******************************* - -Some users might want to byte-compile their init file to make Emacs -startup even faster. This is not recommended in most cases, as the -speed-up is often too small to be worth it, and can lead to confusion if -the byte-compiled files are out-of-date. If you still want to do it, -read on. - - ‘use-package’ always loads every library that it can while a file is -being byte-compiled. This helps silence spurious warnings about unknown -variables and functions. - - However, there are times when this is just not enough. For those -times, use the ‘:defines’ and ‘:functions’ keywords to introduce dummy -variable and function declarations solely for the sake of silencing -byte-compiler warnings. For example: - - (use-package texinfo - :defines texinfo-section-list - :commands texinfo-mode - :init - (add-to-list 'auto-mode-alist '("\\.texi$" . texinfo-mode))) - - If you need to silence a missing function warning, you can use -‘:functions’: - - (use-package ruby-mode - :mode "\\.rb\\'" - :interpreter "ruby" - :functions inf-ruby-keys - :config - (defun my-ruby-mode-hook () - (require 'inf-ruby) - (inf-ruby-keys)) - - (add-hook 'ruby-mode-hook 'my-ruby-mode-hook)) - - Normally, ‘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 package may have special loading requirements, and all that you -want to use ‘use-package’ for is to add a configuration to the -‘eval-after-load’ hook. In such cases, use the ‘:no-require’ keyword: - - (use-package foo - :no-require t - :config - (message "Evaluate this immediately after loading `foo'")) - - -File: use-package.info, Node: Troubleshooting, Next: Keyword extensions, Prev: Byte-compiling, Up: Top - -7 Troubleshooting -***************** - -If an error occurs while initializing or configuring a package, this -will not stop your Emacs from loading. Instead, ‘use-package’ captures -the error and reports it in a special ‘*Warnings*’ popup buffer, so that -you can debug the situation in an otherwise functional Emacs. - - If you are having trouble when starting Emacs, you can pass Emacs the -‘--debug-init’ command line flag. *Note (emacs)Initial Options::. To -get even more information when using that flag, add the following to -your init file (these options are documented below): - - (when init-file-debug - (setq use-package-verbose t - use-package-expand-minimally nil - use-package-compute-statistics t - debug-on-error t)) - - Since ‘use-package’ is a macro, the first step when you need to dig -deeper is usually to see what Emacs Lisp code your declaration expands -to. You can either use the command ‘M-x pp-macroexpand-last-sexp’, or -wrap the use-package declaration in ‘macroexpand’ and evaluate it. It -is a good idea to include their output in any bugs you file for -use-package. - -* Menu: - -* Troubleshooting Options:: -* Gathering Statistics:: -* Disabling a package:: - - -File: use-package.info, Node: Troubleshooting Options, Next: Gathering Statistics, Up: Troubleshooting - -7.1 Options that help when troubleshooting -========================================== - -By default, use-package will attempts to catch and report errors that -occur during expansion of use-package declarations in your init file. -Customize the user option ‘use-package-expand-minimally’ to a non-‘nil’ -value to disable this checking. - - This behavior may be overridden locally using the ‘:catch’ keyword. -If ‘t’ or ‘nil’, it enables or disables catching errors at load time. -It can also be a function taking two arguments: the keyword being -processed at the time the error was encountered, and the error object -(as generated by ‘condition-case’). For example: - - (use-package example - ;; Note that errors are never trapped in the preface, since doing so would - ;; hide definitions from the byte-compiler. - :preface (message "I'm here at byte-compile and load time") - :init (message "I'm always here at startup") - :config - (message "I'm always here after the package is loaded") - (error "oops") - ;; Don't try to (require 'example), this is just an example! - :no-require t - :catch (lambda (keyword err) - (message (error-message-string err)))) - - Evaluating the above form will print these messages: - -I’m here at byte-compile and load time -I’m always here at startup -Configuring package example... -I’m always here after the package is loaded -oops - - -File: use-package.info, Node: Gathering Statistics, Next: Disabling a package, Prev: Troubleshooting Options, Up: Troubleshooting - -7.2 Gathering Statistics -======================== - -When a package is loaded, and if you have ‘use-package-verbose’ set to -‘t’, or if the package takes longer than 0.1 seconds to load, you will -see a message to indicate this loading activity in the ‘*Messages*’ -buffer. The same will happen for configuration, or ‘:config’ blocks, -that take longer than 0.1 seconds to execute. - - If you'd like to see a summary how many packages you've loaded, what -stage of initialization they've reached, and how much aggregate time -they've spent (roughly), you can customize the user option -‘use-package-compute-statistics’ to a non-‘nil’ value. Then reload your -packages, normally by restarting Emacs, to make sure that use-package -can gather statistics for all your packages. - - Run the command ‘M-x use-package-report’ to see the results. The -buffer displayed is a tabulated list. To sort rows based on a -particular column, move point to it and type ‘S’, or click the column -name at the top of the buffer on graphical displays. - - To reset all statistics that use-package has gathered for the current -Emacs invocation, run the command ‘M-x use-package-reset-statistics’. - - Note that, if you are setting ‘use-package-compute-statistics’ -directly in your init file, and not with ‘customize’, you must do this -after loading ‘use-package’, but before any ‘use-package’ forms. - - -File: use-package.info, Node: Disabling a package, Prev: Gathering Statistics, Up: Troubleshooting - -7.3 Disabling a package -======================= - -The ‘:disabled’ keyword inhibits loading a package, and all it's -customizations. It is equivalent to commenting out or deleting the -definition. - - You could use this, for example, to temporarily disable a package -that you're having difficulties with, or to avoid loading a package that -you're not currently using. - - This example disables the ‘foo’ package: - - (use-package foo - :disabled) - - When byte-compiling your init file, use-package omits disabled -declarations from the output entirely, in order to make Emacs startup -faster. - - -File: use-package.info, Node: Keyword extensions, Next: History, Prev: Troubleshooting, Up: Top - -Appendix A Keyword extensions -***************************** - -use-package is based on an extensible framework that makes it easy for -package authors to add new keywords, or modify the behavior of existing -keywords. - - Some keyword extensions are included with ‘use-package’, and can be -optionally enabled. - -* Menu: - -* use-package-ensure-system-package:: -* Creating an extension:: - - -File: use-package.info, Node: use-package-ensure-system-package, Next: Creating an extension, Up: Keyword extensions - -A.1 :use-package-ensure-system-package -====================================== - -The ‘:ensure-system-package’ keyword allows you to ensure certain -executables are available on your system alongside your package -declarations.(1) - - To use this extension, add this immediately after loading -‘use-package’: - - (use-package use-package-ensure-system-package) - - Now you can use the ‘:ensure-system-package’ keyword. Here's an -example usage: - - (use-package foo - :ensure-system-package foo) - - This will expect a global binary package to exist called ‘foo’. If -it does not, it will use your system package manager to attempt an -install of a binary by the same name asynchronously. This requires the -GNU ELPA package ‘system-packages’ -(https://gitlab.com/jabranham/system-packages), so for this to work you -must install that first. - - One way of making sure it is installed is with ‘use-package’ together -with ‘:ensure’. - - (use-package system-packages - :ensure t) - - For example, on a ‘Debian GNU/Linux’ system, this would call ‘apt-get -install foo’. - - If the package is named differently than the binary, you can use a -cons in the form of ‘(binary . package-name)’. For example: - - (use-package foo - :ensure-system-package - (foocmd . foo)) - - On a ‘Debian GNU/Linux’ system, this would call ‘apt install foo’ if -Emacs could not locate the executable ‘foocmd’.(2) - - ‘:ensure-system-package’ can also take a cons where its ‘cdr’ is a -string that will get called by ‘(async-shell-command)’ to install if it -isn't found. This does not depend upon any external package. - - (use-package tern - :ensure-system-package (tern . "npm i -g tern")) - - To install several packages, you can pass in a list of conses: - - (use-package ruby-mode - :ensure-system-package - ((rubocop . "gem install rubocop") - (ruby-lint . "gem install ruby-lint") - (ripper-tags . "gem install ripper-tags") - (pry . "gem install pry"))) - - Finally, in case the package dependency does not provide a global -executable, you can ensure packages exist by checking the presence of a -file path by providing a string like so: - - (use-package dash-at-point - :if (eq system-type 'darwin) - :ensure-system-package - ("/Applications/Dash.app" . "brew cask install dash")) - - ‘:ensure-system-package’ will use ‘system-packages-install’ to -install system packages, except where a custom command has been -specified, in which case it will be executed verbatim by -‘async-shell-command’. - - The user options ‘system-packages-package-manager’ and -‘system-packages-use-sudo’ are honored, but not for custom commands. -Custom commands should include the call to sudo in the command if -needed. - - ---------- Footnotes ---------- - - (1) On macOS, you will want to make sure ‘exec-path’ is cognisant of -all binary package names that you would like to ensure are installed. -The ‘exec-path-from-shell’ -(https://github.com/purcell/exec-path-from-shell) package is often a -good way to do this. - - (2) For manual testing, you could use the ‘executable-find’ function, -which is what ‘system-packages’ uses internally. - - -File: use-package.info, Node: Creating an extension, Prev: use-package-ensure-system-package, Up: Keyword extensions - -A.2 How to create an extension keyword -====================================== - -This section describes how to create a new keyword. - - 1. Add the keyword. - - The first step is to add your keyword at the right place in - ‘use-package-keywords’. This list determines the order in which - things will happen in the expanded code. You should never change - this order, but it gives you a framework within which to decide - when your keyword should fire. - - 2. Create a normalizer. - - The job of the normalizer is take a list of arguments (possibly - ‘nil’), and turn it into the single argument (which could still be - a list) that should appear in the final property list used by - ‘use-package’. - - Define a normalizer for your keyword by defining a function named - after the keyword, for example: - - (defun use-package-normalize/:pin (name-symbol keyword args) - (use-package-only-one (symbol-name keyword) args - (lambda (label arg) - (cond - ((stringp arg) arg) - ((symbolp arg) (symbol-name arg)) - (t - (use-package-error - ":pin wants an archive name (a string)")))))) - - 3. Create a handler. - - Once you have a normalizer, you must create a handler for the - keyword. - - Handlers can affect the handling of keywords in two ways. First, - it can modify the ‘state’ plist before recursively processing the - remaining keywords, to influence keywords that pay attention to the - state (one example is the state keyword ‘:deferred’, not to be - confused with the ‘use-package’ keyword ‘:defer’). Then, once the - remaining keywords have been handled and their resulting forms - returned, the handler may manipulate, extend, or just ignore those - forms. - - The task of each handler is to return a _list of forms_ - representing code to be inserted. It does not need to be a ‘progn’ - list, as this is handled automatically in other places. Thus it is - common to see the idiom of using ‘use-package-concat’ to add new - functionality before or after a code body, so that only the minimum - code necessary is emitted as the result of a ‘use-package’ - expansion. - - This is an example handler: - - (defun use-package-handler/:pin (name-symbol keyword archive-name rest state) - (let ((body (use-package-process-keywords name-symbol rest state))) - ;; This happens at macro expansion time, not when the expanded code is - ;; compiled or evaluated. - (if (null archive-name) - body - (use-package-pin-package name-symbol archive-name) - (use-package-concat - body - `((push '(,name-symbol . ,archive-name) - package-pinned-packages)))))) - - 4. Test it. - - After the keyword has been inserted into ‘use-package-keywords’, - and a normalizer and a handler defined, you can now test it by - seeing how usages of the keyword will expand. For this, use ‘M-x - pp-macroexpand-last-sexp’ with the cursor set immediately after the - ‘(use-package ...)’ expression. - - -File: use-package.info, Node: History, Next: GNU Free Documentation License, Prev: Keyword extensions, Up: Top - -Appendix B History and acknowledgments -************************************** - -use-package was written by John Wiegley. Its development started in -2012, and it got merged into Emacs in 2022, in preparation of the -release of Emacs 29.1. - - Dozens of people have contributed to use-package over the years with -bug reports, documentation and code. They are too many to list here, -but we thank them all for their contributions. - - This Texinfo manual was written by Stefan Kangas, as a significant -rewrite of the old use-package manual and ‘README’. - - -File: use-package.info, Node: GNU Free Documentation License, Next: Index, Prev: History, Up: Top - -Appendix C GNU Free Documentation License -***************************************** - - Version 1.3, 3 November 2008 - - Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. - <https://fsf.org/> - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - functional and useful document “free” in the sense of freedom: to - assure everyone the effective freedom to copy and redistribute it, - with or without modifying it, either commercially or - noncommercially. Secondarily, this License preserves for the - author and publisher a way to get credit for their work, while not - being considered responsible for modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - We have designed this License in order to use it for manuals for - free software, because free software needs free documentation: a - free program should come with manuals providing the same freedoms - that the software does. But this License is not limited to - software manuals; it can be used for any textual work, regardless - of subject matter or whether it is published as a printed book. We - recommend this License principally for works whose purpose is - instruction or reference. - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work, in any medium, - that contains a notice placed by the copyright holder saying it can - be distributed under the terms of this License. Such a notice - grants a world-wide, royalty-free license, unlimited in duration, - to use that work under the conditions stated herein. The - "Document", below, refers to any such manual or work. Any member - of the public is a licensee, and is addressed as "you". You accept - the license if you copy, modify or distribute the work in a way - requiring permission under copyright law. - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter section - of the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document's overall - subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (Thus, if the Document - is in part a textbook of mathematics, a Secondary Section may not - explain any mathematics.) The relationship could be a matter of - historical connection with the subject or with related matters, or - of legal, commercial, philosophical, ethical or political position - regarding them. - - The "Invariant Sections" are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in the - notice that says that the Document is released under this License. - If a section does not fit the above definition of Secondary then it - is not allowed to be designated as Invariant. The Document may - contain zero Invariant Sections. If the Document does not identify - any Invariant Sections then there are none. - - The "Cover Texts" are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. A - Front-Cover Text may be at most 5 words, and a Back-Cover Text may - be at most 25 words. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, that is suitable for revising the document - straightforwardly with generic text editors or (for images composed - of pixels) generic paint programs or (for drawings) some widely - available drawing editor, and that is suitable for input to text - formatters or for automatic translation to a variety of formats - suitable for input to text formatters. A copy made in an otherwise - Transparent file format whose markup, or absence of markup, has - been arranged to thwart or discourage subsequent modification by - readers is not Transparent. An image format is not Transparent if - used for any substantial amount of text. A copy that is not - "Transparent" is called "Opaque". - - Examples of suitable formats for Transparent copies include plain - ASCII without markup, Texinfo input format, LaTeX input format, - SGML or XML using a publicly available DTD, and standard-conforming - simple HTML, PostScript or PDF designed for human modification. - Examples of transparent image formats include PNG, XCF and JPG. - Opaque formats include proprietary formats that can be read and - edited only by proprietary word processors, SGML or XML for which - the DTD and/or processing tools are not generally available, and - the machine-generated HTML, PostScript or PDF produced by some word - processors for output purposes only. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, "Title - Page" means the text near the most prominent appearance of the - work's title, preceding the beginning of the body of the text. - - The "publisher" means any person or entity that distributes copies - of the Document to the public. - - A section "Entitled XYZ" means a named subunit of the Document - whose title either is precisely XYZ or contains XYZ in parentheses - following text that translates XYZ in another language. (Here XYZ - stands for a specific section name mentioned below, such as - "Acknowledgements", "Dedications", "Endorsements", or "History".) - To "Preserve the Title" of such a section when you modify the - Document means that it remains a section "Entitled XYZ" according - to this definition. - - The Document may include Warranty Disclaimers next to the notice - which states that this License applies to the Document. These - Warranty Disclaimers are considered to be included by reference in - this License, but only as regards disclaiming warranties: any other - implication that these Warranty Disclaimers may have is void and - has no effect on the meaning of this License. - - 2. VERBATIM COPYING - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License - applies to the Document are reproduced in all copies, and that you - add no other conditions whatsoever to those of this License. You - may not use technical measures to obstruct or control the reading - or further copying of the copies you make or distribute. However, - you may accept compensation in exchange for copies. If you - distribute a large enough number of copies you must also follow the - conditions in section 3. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - If you publish printed copies (or copies in media that commonly - have printed covers) of the Document, numbering more than 100, and - the Document's license notice requires Cover Texts, you must - enclose the copies in covers that carry, clearly and legibly, all - these Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also clearly - and legibly identify you as the publisher of these copies. The - front cover must present the full title with all words of the title - equally prominent and visible. You may add other material on the - covers in addition. Copying with changes limited to the covers, as - long as they preserve the title of the Document and satisfy these - conditions, can be treated as verbatim copying in other respects. - - If the required texts for either cover are too voluminous to fit - legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto - adjacent pages. - - If you publish or distribute Opaque copies of the Document - numbering more than 100, you must either include a machine-readable - Transparent copy along with each Opaque copy, or state in or with - each Opaque copy a computer-network location from which the general - network-using public has access to download using public-standard - network protocols a complete Transparent copy of the Document, free - of added material. If you use the latter option, you must take - reasonably prudent steps, when you begin distribution of Opaque - copies in quantity, to ensure that this Transparent copy will - remain thus accessible at the stated location until at least one - year after the last time you distribute an Opaque copy (directly or - through your agents or retailers) of that edition to the public. - - It is requested, but not required, that you contact the authors of - the Document well before redistributing any large number of copies, - to give them a chance to provide you with an updated version of the - Document. - - 4. MODIFICATIONS - - You may copy and distribute a Modified Version of the Document - under the conditions of sections 2 and 3 above, provided that you - release the Modified Version under precisely this License, with the - Modified Version filling the role of the Document, thus licensing - distribution and modification of the Modified Version to whoever - possesses a copy of it. In addition, you must do these things in - the Modified Version: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of previous - versions (which should, if there were any, be listed in the - History section of the Document). You may use the same title - as a previous version if the original publisher of that - version gives permission. - - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in - the Modified Version, together with at least five of the - principal authors of the Document (all of its principal - authors, if it has fewer than five), unless they release you - from this requirement. - - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - - D. Preserve all the copyright notices of the Document. - - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified - Version under the terms of this License, in the form shown in - the Addendum below. - - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's - license notice. - - H. Include an unaltered copy of this License. - - I. Preserve the section Entitled "History", Preserve its Title, - and add to it an item stating at least the title, year, new - authors, and publisher of the Modified Version as given on the - Title Page. If there is no section Entitled "History" in the - Document, create one stating the title, year, authors, and - publisher of the Document as given on its Title Page, then add - an item describing the Modified Version as stated in the - previous sentence. - - J. Preserve the network location, if any, given in the Document - for public access to a Transparent copy of the Document, and - likewise the network locations given in the Document for - previous versions it was based on. These may be placed in the - "History" section. You may omit a network location for a work - that was published at least four years before the Document - itself, or if the original publisher of the version it refers - to gives permission. - - K. For any section Entitled "Acknowledgements" or "Dedications", - Preserve the Title of the section, and preserve in the section - all the substance and tone of each of the contributor - acknowledgements and/or dedications given therein. - - L. Preserve all the Invariant Sections of the Document, unaltered - in their text and in their titles. Section numbers or the - equivalent are not considered part of the section titles. - - M. Delete any section Entitled "Endorsements". Such a section - may not be included in the Modified Version. - - N. Do not retitle any existing section to be Entitled - "Endorsements" or to conflict in title with any Invariant - Section. - - O. Preserve any Warranty Disclaimers. - - If the Modified Version includes new front-matter sections or - appendices that qualify as Secondary Sections and contain no - material copied from the Document, you may at your option designate - some or all of these sections as invariant. To do this, add their - titles to the list of Invariant Sections in the Modified Version's - license notice. These titles must be distinct from any other - section titles. - - You may add a section Entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties--for example, statements of peer review or that the text - has been approved by an organization as the authoritative - definition of a standard. - - You may add a passage of up to five words as a Front-Cover Text, - and a passage of up to 25 words as a Back-Cover Text, to the end of - the list of Cover Texts in the Modified Version. Only one passage - of Front-Cover Text and one of Back-Cover Text may be added by (or - through arrangements made by) any one entity. If the Document - already includes a cover text for the same cover, previously added - by you or by arrangement made by the same entity you are acting on - behalf of, you may not add another; but you may replace the old - one, on explicit permission from the previous publisher that added - the old one. - - The author(s) and publisher(s) of the Document do not by this - License give permission to use their names for publicity for or to - assert or imply endorsement of any Modified Version. - - 5. COMBINING DOCUMENTS - - You may combine the Document with other documents released under - this License, under the terms defined in section 4 above for - modified versions, provided that you include in the combination all - of the Invariant Sections of all of the original documents, - unmodified, and list them all as Invariant Sections of your - combined work in its license notice, and that you preserve all - their Warranty Disclaimers. - - The combined work need only contain one copy of this License, and - multiple identical Invariant Sections may be replaced with a single - copy. If there are multiple Invariant Sections with the same name - but different contents, make the title of each such section unique - by adding at the end of it, in parentheses, the name of the - original author or publisher of that section if known, or else a - unique number. Make the same adjustment to the section titles in - the list of Invariant Sections in the license notice of the - combined work. - - In the combination, you must combine any sections Entitled - "History" in the various original documents, forming one section - Entitled "History"; likewise combine any sections Entitled - "Acknowledgements", and any sections Entitled "Dedications". You - must delete all sections Entitled "Endorsements." - - 6. COLLECTIONS OF DOCUMENTS - - You may make a collection consisting of the Document and other - documents released under this License, and replace the individual - copies of this License in the various documents with a single copy - that is included in the collection, provided that you follow the - rules of this License for verbatim copying of each of the documents - in all other respects. - - You may extract a single document from such a collection, and - distribute it individually under this License, provided you insert - a copy of this License into the extracted document, and follow this - License in all other respects regarding verbatim copying of that - document. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of a - storage or distribution medium, is called an "aggregate" if the - copyright resulting from the compilation is not used to limit the - legal rights of the compilation's users beyond what the individual - works permit. When the Document is included in an aggregate, this - License does not apply to the other works in the aggregate which - are not themselves derivative works of the Document. - - If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one half - of the entire aggregate, the Document's Cover Texts may be placed - on covers that bracket the Document within the aggregate, or the - electronic equivalent of covers if the Document is in electronic - form. Otherwise they must appear on printed covers that bracket - the whole aggregate. - - 8. TRANSLATION - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License, and all the license notices in the - Document, and any Warranty Disclaimers, provided that you also - include the original English version of this License and the - original versions of those notices and disclaimers. In case of a - disagreement between the translation and the original version of - this License or a notice or disclaimer, the original version will - prevail. - - If a section in the Document is Entitled "Acknowledgements", - "Dedications", or "History", the requirement (section 4) to - Preserve its Title (section 1) will typically require changing the - actual title. - - 9. TERMINATION - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided under this License. Any attempt - otherwise to copy, modify, sublicense, or distribute it is void, - and will automatically terminate your rights under this License. - - However, if you cease all violation of this License, then your - license from a particular copyright holder is reinstated (a) - provisionally, unless and until the copyright holder explicitly and - finally terminates your license, and (b) permanently, if the - copyright holder fails to notify you of the violation by some - reasonable means prior to 60 days after the cessation. - - Moreover, your license from a particular copyright holder is - reinstated permanently if the copyright holder notifies you of the - violation by some reasonable means, this is the first time you have - received notice of violation of this License (for any work) from - that copyright holder, and you cure the violation prior to 30 days - after your receipt of the notice. - - Termination of your rights under this section does not terminate - the licenses of parties who have received copies or rights from you - under this License. If your rights have been terminated and not - permanently reinstated, receipt of a copy of some or all of the - same material does not give you any rights to use it. - - 10. FUTURE REVISIONS OF THIS LICENSE - - The Free Software Foundation may publish new, revised versions of - the GNU Free Documentation License from time to time. Such new - versions will be similar in spirit to the present version, but may - differ in detail to address new problems or concerns. See - <https://www.gnu.org/licenses/>. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If the - Document does not specify a version number of this License, you may - choose any version ever published (not as a draft) by the Free - Software Foundation. If the Document specifies that a proxy can - decide which future versions of this License can be used, that - proxy's public statement of acceptance of a version permanently - authorizes you to choose that version for the Document. - - 11. RELICENSING - - "Massive Multiauthor Collaboration Site" (or "MMC Site") means any - World Wide Web server that publishes copyrightable works and also - provides prominent facilities for anybody to edit those works. A - public wiki that anybody can edit is an example of such a server. - A "Massive Multiauthor Collaboration" (or "MMC") contained in the - site means any set of copyrightable works thus published on the MMC - site. - - "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 - license published by Creative Commons Corporation, a not-for-profit - corporation with a principal place of business in San Francisco, - California, as well as future copyleft versions of that license - published by that same organization. - - "Incorporate" means to publish or republish a Document, in whole or - in part, as part of another Document. - - An MMC is "eligible for relicensing" if it is licensed under this - License, and if all works that were first published under this - License somewhere other than this MMC, and subsequently - incorporated in whole or in part into the MMC, (1) had no cover - texts or invariant sections, and (2) were thus incorporated prior - to November 1, 2008. - - The operator of an MMC Site may republish an MMC contained in the - site under CC-BY-SA on the same site at any time before August 1, - 2009, provided the MMC is eligible for relicensing. - -ADDENDUM: How to use this License for your documents -==================================================== - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and license -notices just after the title page: - - Copyright (C) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. - - If you have Invariant Sections, Front-Cover Texts and Back-Cover -Texts, replace the "with...Texts." line with this: - - with the Invariant Sections being LIST THEIR TITLES, with - the Front-Cover Texts being LIST, and with the Back-Cover Texts - being LIST. - - If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - - If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of free -software license, such as the GNU General Public License, to permit -their use in free software. - - -File: use-package.info, Node: Index, Prev: GNU Free Documentation License, Up: Top - -Index -***** - - -* Menu: - -* :after: Loading sequentially. (line 6) -* :all (with :after): Loading sequentially. (line 34) -* :any (with :after): Loading sequentially. (line 34) -* :autoload: Manual autoloads. (line 6) -* :bind: Key bindings. (line 6) -* :bind <1>: Global keybindings. (line 6) -* :bind-keymap, inside :bind: Binding to a keymap. (line 6) -* :catch: Troubleshooting Options. - (line 11) -* :commands: Manual autoloads. (line 6) -* :config: Config keyword. (line 6) -* :continue, inside :repeat-map and :bind: Binding to repeat-maps. - (line 45) -* :custom: User options. (line 6) -* :custom-face: Faces. (line 6) -* :defer: Deferring loading. (line 25) -* :defines: Byte-compiling. (line 16) -* :delight: Delight. (line 6) -* :demand: Forcing loading. (line 6) -* :diminish: Diminish. (line 6) -* :disabled: Disabling a package. (line 6) -* :ensure: Install package. (line 6) -* :ensure-system-package: use-package-ensure-system-package. - (line 6) -* :exit, inside :repeat-map and :bind: Binding to repeat-maps. - (line 27) -* :functions: Byte-compiling. (line 16) -* :hook: Hooks. (line 6) -* :if: Conditional loading. (line 6) -* :init: Init keyword. (line 6) -* :interpreter: Modes and interpreters. - (line 6) -* :load-path: Load path. (line 6) -* :magic: Magic handlers. (line 6) -* :magic-fallback: Magic handlers. (line 6) -* :map, inside :bind: Binding in keymaps. (line 6) -* :mode: Modes and interpreters. - (line 6) -* :no-require: Byte-compiling. (line 41) -* :pin: Pinning packages. (line 6) -* :preface: Preface keyword. (line 6) -* :repeat-map, inside :bind: Binding to repeat-maps. - (line 6) -* :requires: Load dependencies. (line 6) -* :unless: Conditional loading. (line 6) -* :when: Conditional loading. (line 6) -* autoloading packages: Deferring loading. (line 6) -* binding keys: Key bindings. (line 6) -* conditional loading before :preface or :ensure: Conditional loading. - (line 59) -* debugging: Troubleshooting. (line 6) -* describe-personal-keybindings: Displaying keybindings. - (line 6) -* disable package: Disabling a package. (line 6) -* expanding macro, for troubleshooting: Troubleshooting. (line 22) -* hooks: Hooks. (line 6) -* key bindings: Key bindings. (line 6) -* loading lazily: Deferring loading. (line 6) -* loading packages: Loading Packages. (line 6) -* multiple hooks: Hooks. (line 37) -* prevent a package from loading at compile-time: Byte-compiling. - (line 41) -* repeat-mode and use-package, using: Binding to repeat-maps. - (line 6) -* reporting bugs: Troubleshooting. (line 22) -* triggers, for loading packages: Deferring loading. (line 14) -* troubleshooting: Troubleshooting. (line 6) -* use-package-always-defer: Deferring loading. (line 68) -* use-package-always-pin: Pinning packages. (line 19) -* use-package-compute-statistics: Gathering Statistics. (line 12) -* use-package-ensure-function: Other package managers. - (line 10) -* use-package-expand-minimally: Troubleshooting Options. - (line 6) -* use-package-hook-name-suffix: Hooks. (line 65) -* use-package-report: Gathering Statistics. (line 19) -* use-package-reset-statistics: Gathering Statistics. (line 24) -* use-package-verbose: Gathering Statistics. (line 6) - - - -Tag Table: -Node: Top933 -Node: Basic Concepts3113 -Node: Getting Started4537 -Node: Loading Packages7700 -Node: Loading basics9207 -Ref: Loading basics-Footnote-110760 -Node: Deferring loading10844 -Node: Forcing loading14061 -Node: Conditional loading14746 -Node: Loading sequentially16910 -Node: Load dependencies19491 -Node: Load path20468 -Node: Manual autoloads21705 -Node: Configuring Packages22361 -Node: Lisp Configuration23120 -Node: Preface keyword23984 -Node: Init keyword24890 -Node: Config keyword25508 -Node: Best practices26233 -Node: Key bindings27710 -Node: Global keybindings28480 -Node: Binding in keymaps32292 -Node: Binding to a keymap33501 -Node: Binding to repeat-maps34531 -Node: Displaying keybindings36918 -Node: Hooks37478 -Node: Modes and interpreters40246 -Node: Magic handlers41781 -Node: User options42610 -Node: Faces44025 -Node: Hiding minor modes44822 -Ref: Hiding minor modes-Footnote-145527 -Node: Diminish45582 -Ref: Diminish-Footnote-146519 -Node: Delight46578 -Ref: Delight-Footnote-148382 -Node: Installing packages48446 -Node: Install package49059 -Node: Pinning packages49889 -Ref: Pinning packages-Footnote-151583 -Node: Other package managers51663 -Node: Byte-compiling52535 -Node: Troubleshooting54527 -Node: Troubleshooting Options55878 -Node: Gathering Statistics57440 -Node: Disabling a package58999 -Node: Keyword extensions59709 -Node: use-package-ensure-system-package60197 -Ref: use-package-ensure-system-package-Footnote-163202 -Ref: use-package-ensure-system-package-Footnote-263470 -Node: Creating an extension63601 -Node: History67013 -Node: GNU Free Documentation License67686 -Node: Index92837 - -End Tag Table - - -Local Variables: -coding: utf-8 -End: |