[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/bind-key 21a126cb7e 9/9: Merge pull request #1018 from
|
From: |
ELPA Syncer |
|
Subject: |
[elpa] externals/bind-key 21a126cb7e 9/9: Merge pull request #1018 from skangas/texinfo-wip |
|
Date: |
Tue, 15 Nov 2022 11:57:21 -0500 (EST) |
branch: externals/bind-key
commit 21a126cb7e9bb2a22211da0cdb1e6189303ed5a0
Merge: 8bdfe31fbb b8f0537840
Author: John Wiegley <johnw@newartisans.com>
Commit: GitHub <noreply@github.com>
Merge pull request #1018 from skangas/texinfo-wip
---
.gitignore | 1 -
Makefile | 6 +-
Makefile.doc | 14 +-
README.md | 14 +-
use-package.org | 895 -------------------------------------------------------
use-package.texi | 170 +++++------
6 files changed, 94 insertions(+), 1006 deletions(-)
diff --git a/.gitignore b/.gitignore
index c0749c9a3b..2f51becc32 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,7 +4,6 @@
/*.html
/*.info
/*.pdf
-/*.texi
/config.mk
/dir
/doc/content/*
diff --git a/Makefile b/Makefile
index 77d1c3748d..075a3968c0 100644
--- a/Makefile
+++ b/Makefile
@@ -43,7 +43,7 @@ help:
$(info make clean-lisp - clean elisp)
$(info make clean-docs - clean docs)
$(info make clean-archives - clean release tarball)
- $(info make clean-all - clean everything except tracked texi)
+ $(info make clean-all - clean everything)
$(info make clean-stats - clean stats)
$(info )
$(info Test)
@@ -56,7 +56,6 @@ help:
$(info Release Management)
$(info ==================)
$(info )
- $(info make texi - regenerate texi from org)
$(info make stats - regenerate statistics)
$(info make authors - regenerate AUTHORS.md)
$(info make preview-stats - preview statistics)
@@ -140,9 +139,6 @@ clean-stats:
## Release management ################################################
-texi:
- @$(MAKE) -f Makefile.doc texi
-
stats:
@$(MAKE) -f Makefile.doc stats
diff --git a/Makefile.doc b/Makefile.doc
index 78575501ee..43c874fdaf 100644
--- a/Makefile.doc
+++ b/Makefile.doc
@@ -5,7 +5,7 @@ include default.mk
## ###################################################################
-.PHONY: texi install clean AUTHORS.md stats
+.PHONY: install clean AUTHORS.md stats
all: info
@@ -55,18 +55,6 @@ clean:
## Release management ################################################
-# Because most users don't have the necessary tools we cannot
-# use "%.texi: %.org". Instead we have to hardcode each file
-# using a shared target.
-
-ORG_ARGS = --batch -Q $(DOC_LOAD_PATH)
-ORG_EVAL = --funcall org-texinfo-export-to-texinfo
-
-texi:
- @printf "Generating use-package.texi\n"
- @$(EMACS) $(ORG_ARGS) use-package.org $(ORG_EVAL)
- @echo >> use-package.texi
-
stats:
@printf "Generating statistics\n"
@gitstats -c style=/assets/stats.css -c max_authors=999 $(TOP)
$(statsdir)
diff --git a/README.md b/README.md
index 7ea757c588..7c3308fec0 100644
--- a/README.md
+++ b/README.md
@@ -567,7 +567,13 @@ When byte-compiling your `.emacs` file, disabled
declarations are omitted
from the output entirely, to accelerate startup times.
**NOTE**: `:when` is provided as an alias for `:if`, and `:unless foo` means
-the same thing as `:if (not foo)`. For example, the following will also stop
+the same thing as `:if (not foo)`.
+
+### Conditional loading before :preface
+
+If you need to conditionalize a use-package form so that the condition occurs
+before even the `:preface` is executed, simply use `when` around the
+use-package form itself. For example, the following will also stop
`:ensure` from happening on Mac systems:
``` elisp
@@ -578,12 +584,6 @@ the same thing as `:if (not foo)`. For example, the
following will also stop
(exec-path-from-shell-initialize)))
```
-### Conditional loading before :preface
-
-If you need to conditionalize a use-package form so that the condition occurs
-before even the `:preface` is executed, simply use `when` around the
-use-package form itself:
-
### Loading packages in sequence
Sometimes it only makes sense to configure a package after another has been
diff --git a/use-package.org b/use-package.org
deleted file mode 100644
index 8c7b01c857..0000000000
--- a/use-package.org
+++ /dev/null
@@ -1,895 +0,0 @@
-#+title: use-package User Manual
-:PREAMBLE:
-#+author: John Wiegley
-#+email: johnw@newartisans.com
-#+date: 2012-{{{year}}}
-#+language: en
-
-#+hugo_base_dir: ./doc
-#+hugo_section: /
-#+hugo_menu: :menu main
-
-#+texinfo_dir_category: Emacs
-#+texinfo_dir_title: use-package: (use-package).
-#+texinfo_dir_desc: Declarative package configuration for Emacs.
-#+subtitle: for version {{{version}}}
-
-#+options: H:4 num:3 toc:2
-
-# Below macro is used so that both texinfo and hugo exports work
-# harmoniously. For texinfo exports, the export is done using the
-# scope of the whole file, so it can resolve all internal link
-# references. Whereas for hugo exports, they are done only from the
-# scope of a subtree (or a page of the doc site), so at the moment it
-# doesn't auto-resolve Org internal links outside that scope.
-
-# FIXME: This is just a workaround.. hope to get a better solution in
-# the future.
-
-#+macro: link-jump @@texinfo:@ref{$1}@@@@hugo:[$1]($2)@@
-
-#+macro: year (eval (format-time-string "%Y"))
-#+macro: version (eval (or (getenv "PACKAGE_REVDESC") (getenv
"PACKAGE_VERSION") (ignore-errors (car (process-lines "git" "describe"
"--exact"))) (ignore-errors (concat (car (process-lines "git" "describe" (if
(getenv "AMEND") "HEAD~" "HEAD"))) "+1"))))
-
-The ~use-package~ macro allows you to isolate package configuration in your
-~.emacs~ file in a way that is both performance-oriented and, well, tidy. I
-created it because I have over 80 packages that I use in Emacs, and things
-were getting difficult to manage. Yet with this utility my total load time is
-around 2 seconds, with no loss of functionality!
-
-#+texinfo: @insertcopying
-
-:END:
-* Introduction
-:PROPERTIES:
-:EXPORT_FILE_NAME: _index
-:EXPORT_HUGO_TYPE: homepage
-:END:
-
-The ~use-package~ macro allows you to isolate package configuration in your
-~.emacs~ file in a way that is both performance-oriented and, well, tidy. I
-created it because I have over 80 packages that I use in Emacs, and things
-were getting difficult to manage. Yet with this utility my total load time is
-around 2 seconds, with no loss of functionality!
-
-More text to come...
-
-* Installation
-:PROPERTIES:
-:EXPORT_FILE_NAME: installation
-:END:
-
-use-package can be installed using Emacs' package manager or manually from
-its development repository.
-
-** Installing from an Elpa Archive
-
-use-package is available from Melpa and Melpa-Stable. If you haven't used
-Emacs' package manager before, then it is high time you familiarize yourself
-with it by reading the documentation in the Emacs manual, see
-[[info:emacs#Packages]]. Then add one of the archives to ~package-archives~:
-
-- To use Melpa:
-
-#+begin_src emacs-lisp
- (require 'package)
- (add-to-list 'package-archives
- '("melpa" . "https://melpa.org/packages/";) t)
-#+end_src
-
-- To use Melpa-Stable:
-
-#+begin_src emacs-lisp
- (require 'package)
- (add-to-list 'package-archives
- '("melpa-stable" . "https://stable.melpa.org/packages/";) t)
-#+end_src
-
-Once you have added your preferred archive, you need to update the
-local package list using:
-
-#+begin_example
- M-x package-refresh-contents RET
-#+END_EXAMPLE
-
-Once you have done that, you can install use-package and its dependencies
-using:
-
-#+begin_example
- M-x package-install RET use-package RET
-#+END_EXAMPLE
-
-Now see [[*Post-Installation Tasks]].
-
-** Installing from the Git Repository
-
-First, use Git to clone the use-package repository:
-
-#+begin_src shell-script
- $ git clone https://github.com/jwiegley/use-package.git
~/.emacs.d/site-lisp/use-package
- $ cd ~/.emacs.d/site-lisp/use-package
-#+end_src
-
-Then compile the libraries and generate the info manuals:
-
-#+begin_src shell-script
- $ make
-#+end_src
-
-You may need to create ~/path/to/use-package/config.mk~ with the following
-content before running ~make~:
-
-#+begin_src makefile
- LOAD_PATH = -L /path/to/use-package
-#+end_src
-
-Finally add this to your init file:
-
-#+begin_src emacs-lisp
- (add-to-list 'load-path "~/.emacs.d/site-lisp/use-package")
- (require 'use-package)
-
- (with-eval-after-load 'info
- (info-initialize)
- (add-to-list 'Info-directory-list
- "~/.emacs.d/site-lisp/use-package/"))
-#+end_src
-
-Note that elements of ~load-path~ should not end with a slash, while those of
-~Info-directory-list~ should.
-
-Instead of running use-package directly from the repository by adding it to
-the ~load-path~, you might want to instead install it in some other directory
-using ~sudo make install~ and setting ~load-path~ accordingly.
-
-To update use-package use:
-
-#+begin_src shell-script
- $ git pull
- $ make
-#+end_src
-
-At times it might be necessary to run ~make clean all~ instead.
-
-To view all available targets use ~make help~.
-
-Now see [[*Post-Installation Tasks]].
-
-** Post-Installation Tasks
-
-After installing use-package you should verify that you are indeed using the
-use-package release you think you are using. It's best to restart Emacs before
-doing so, to make sure you are not using an outdated value for ~load-path~.
-
-#+begin_example
- C-h v use-package-version RET
-#+END_EXAMPLE
-
-should display something like
-
-#+begin_example
- use-package-version’s value is "2.4.4"
-#+END_EXAMPLE
-
-If you are completely new to use-package then see {{{link-jump(Getting
-Started,/getting-started)}}}.
-
-If you run into problems, then please see the {{{link-jump(Debugging
-Tools,/debugging-tools)}}}.
-
-* Getting Started
-:PROPERTIES:
-:EXPORT_FILE_NAME: getting-started
-:END:
-
-TODO. For now, see ~README.md~.
-
-* Basic Concepts
-
-~use-package~ was created for few basic reasons, each of which drove the
-design in various ways. Understanding these reasons may help make some of
-those decisions clearer:
-
-- 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.
-
-- To reduce duplication and boilerplate, capturing several common
- practices as mere keywords both easy and intuitive to use.
-
-- To make startup time of Emacs as quick as possible, without
- sacrificing the quantity of add-on packages used.
-
-- To make it so errors encountered during startup disable only the
- package raising the error, and as little else as possible, leaving a
- close to a functional Emacs as possible.
-
-- 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.
-
-* Issues/Requests
-:PROPERTIES:
-:EXPORT_HUGO_SECTION: issues
-:EXPORT_FILE_NAME: _index
-:END:
-
-* Keywords
-:PROPERTIES:
-:EXPORT_FILE_NAME: keywords
-:END:
-** ~:after~
-
-Sometimes it only makes sense to configure a package after another has been
-loaded, because certain variables or functions are not in scope until that
-time. This can achieved using an ~:after~ keyword that allows a fairly rich
-description of the exact conditions when loading should occur. Here is an
-example:
-
-#+begin_src emacs-lisp
- (use-package hydra
- :load-path "site-lisp/hydra")
-
- (use-package ivy
- :load-path "site-lisp/swiper")
-
- (use-package ivy-hydra
- :after (ivy hydra))
-#+end_src
-
-In this case, because all of these packages are demand-loaded in the order
-they occur, the use of ~:after~ is not strictly necessary. By using it,
-however, the above code becomes order-independent, without an implicit
-depedence on the nature of your init file.
-
-By default, ~: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:
-
-#+begin_src emacs-lisp
- :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))
-#+end_src
-
-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 both ~baz~ and ~quux~ have been loaded.
-
-*NOTE*: Pay attention if you set ~use-package-always-defer~ to t, and also use
-the ~:after~ keyword, as you will need to specify how the declared package is
-to be loaded: e.g., by some ~:bind~. If you're not using one of the mechanisms
-that registers autoloads, such as ~:bind~ or ~:hook~, and your package manager
-does not provide autoloads, it's possible that without adding ~:demand t~ to
-those declarations, your package will never be loaded.
-
-** ~:bind-keymap~, ~:bind-keymap*~
-
-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 Emacs' ~autoload~ mechanism.
-
-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:
-
-#+begin_src emacs-lisp
- (use-package projectile
- :bind-keymap
- ("C-c p" . projectile-command-map)
-#+end_src
-
-** ~:bind~, ~:bind*~
-
-Another common thing to do when loading a module is to bind a key to primary
-commands within that module:
-
-#+begin_src emacs-lisp
- (use-package ace-jump-mode
- :bind ("C-." . ace-jump-mode))
-#+end_src
-
-This does two things: first, it creates an autoload for the ~ace-jump-mode~
-command and defers loading of ~ace-jump-mode~ until you actually use it.
-Second, it binds the key ~C-.~ to that command. After loading, you can use
-~M-x describe-personal-keybindings~ to see all such keybindings you've set
-throughout your ~.emacs~ file.
-
-A more literal way to do the exact same thing is:
-
-#+begin_src emacs-lisp
- (use-package ace-jump-mode
- :commands ace-jump-mode
- :init
- (bind-key "C-." 'ace-jump-mode))
-#+end_src
-
-When you use the ~:commands~ keyword, it creates autoloads for those commands
-and defers loading of the module until they are used. Since the ~:init~ form
-is always run---even if ~ace-jump-mode~ might not be on your system---remember
-to restrict ~:init~ code to only what would succeed either way.
-
-The ~:bind~ keyword takes either a cons or a list of conses:
-
-#+begin_src emacs-lisp
- (use-package hi-lock
- :bind (("M-o l" . highlight-lines-matching-regexp)
- ("M-o r" . highlight-regexp)
- ("M-o w" . highlight-phrase)))
-#+end_src
-
-The ~:commands~ keyword likewise takes either a symbol or a list of symbols.
-
-NOTE: Special keys like ~tab~ or ~F1~-~Fn~ can be written in square brackets,
-i.e. ~[tab]~ instead of ~"tab"~. The syntax for the keybindings is similar to
-the "kbd" syntax: see
[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Rebinding.html][the
Emacs Manual]] for more information.
-
-Examples:
-
-#+begin_src emacs-lisp
- (use-package helm
- :bind (("M-x" . helm-M-x)
- ("M-<f5>" . helm-find-files)
- ([f10] . helm-buffers-list)
- ([S-f10] . helm-recentf)))
-#+end_src
-
-*** Binding to 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:
-
-#+begin_src emacs-lisp
- (use-package helm
- :bind (:map helm-command-map
- ("C-c h" . helm-execute-persistent-action)))
-#+end_src
-
-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-mode-map~.
-
-Multiple uses of ~:map~ may be specified. Any binding occurring before the
-first use of ~:map~ are applied to the global keymap:
-
-#+begin_src emacs-lisp
- (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)))
-#+end_src
-
-** ~:commands~
-** ~:preface~, ~:init~, ~:config~
-
-Here is the simplest ~use-package~ declaration:
-
-#+begin_src emacs-lisp
- ;; This is only needed once, near the top of the file
- (eval-when-compile
- ;; Following line is not needed if use-package.el is in ~/.emacs.d
- (add-to-list 'load-path "<path where use-package is installed>")
- (require 'use-package))
-
- (use-package foo)
-#+end_src
-
-This loads in the package ~foo~, but only if ~foo~ is available on your
-system. If not, a warning is logged to the ~*Messages*~ buffer. If it
-succeeds, a message about ~"Loading foo"~ is logged, along with the time it
-took to load, if it took over 0.1 seconds.
-
-Use the ~:init~ keyword to execute code before a package is loaded. It
-accepts one or more forms, up until the next keyword:
-
-#+begin_src emacs-lisp
- (use-package foo
- :init
- (setq foo-variable t))
-#+end_src
-
-Similarly, ~:config~ can be used to execute code after a package is loaded.
-In cases where loading is done lazily (see more about autoloading below), this
-execution is deferred until after the autoload occurs:
-
-#+begin_src emacs-lisp
- (use-package foo
- :init
- (setq foo-variable t)
- :config
- (foo-mode 1))
-#+end_src
-
-As you might expect, you can use ~:init~ and ~:config~ together:
-
-#+begin_src emacs-lisp
- (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))
-#+end_src
-
-In this case, I want to autoload the commands ~isearch-moccur~ and
-~isearch-all~ from ~color-moccur.el~, and bind keys both at the global level
-and within the ~isearch-mode-map~ (see next section). When the package is
-actually loaded (by using one of these commands), ~moccur-edit~ is also
-loaded, to allow editing of the ~moccur~ buffer.
-
-** ~:custom~
-
-The ~:custom~ keyword allows customization of package custom variables.
-
-#+begin_src emacs-lisp
- (use-package comint
- :custom
- (comint-buffer-maximum-size 20000 "Increase comint buffer size.")
- (comint-prompt-read-only t "Make the prompt read only."))
-#+end_src
-
-The documentation string is not mandatory.
-
-** ~:custom-face~
-
-The ~:custom-face~ keyword allows customization of package custom faces.
-
-#+begin_src emacs-lisp
- (use-package eruby-mode
- :custom-face
- (eruby-standard-face ((t (:slant italic)))))
-#+end_src
-
-** ~:defer~, ~:demand~
-
-In almost all cases you don't need to manually specify ~:defer t~. This is
-implied whenever ~:bind~ or ~:mode~ or ~:interpreter~ is used. Typically, you
-only need to specify ~:defer~ if you know for a fact that some other package
-will do something to cause your package to load at the appropriate time, and
-thus you would like to defer loading even though use-package isn't creating
-any autoloads for you.
-
-You can override package deferral with the ~:demand~ keyword. Thus, even if
-you use ~:bind~, using ~:demand~ will force loading to occur immediately and
-not establish an autoload for the bound key.
-
-** ~:defines~, ~:functions~
-
-Another feature of ~use-package~ is that it always loads every file that it
-can when ~.emacs~ is being byte-compiled. This helps to 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 the byte-compiler:
-
-#+begin_src emacs-lisp
- (use-package texinfo
- :defines texinfo-section-list
- :commands texinfo-mode
- :init
- (add-to-list 'auto-mode-alist '("\\.texi$" . texinfo-mode)))
-#+end_src
-
-If you need to silence a missing function warning, you can use ~:functions~:
-
-#+begin_src emacs-lisp
- (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))
-#+end_src
-
-** ~:diminish~, ~:delight~
-
-~use-package~ also provides built-in support for the diminish and delight
-utilities---if you have them installed. Their purpose is to remove or change
-minor mode strings in your mode-line.
-
-[[https://github.com/myrjola/diminish.el][diminish]] is invoked with the
~:diminish~ keyword, which is passed 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:
-
-#+begin_src emacs-lisp
- (use-package abbrev
- :diminish abbrev-mode
- :config
- (if (file-exists-p abbrev-file-name)
- (quietly-read-abbrev-file)))
-#+end_src
-
-[[https://elpa.gnu.org/packages/delight.html][delight]] is invoked with the
~:delight~ keyword, which is passed a minor mode
-symbol, a replacement string or quoted
[[https://www.gnu.org/software/emacs/manual/html_node/elisp/Mode-Line-Data.html][mode-line
data]] (in which case the minor
-mode symbol is guessed to be the package name with "-mode" appended at the
-end), both of these, or several lists of both. If no arguments are provided,
-the default mode name is hidden completely.
-
-#+begin_src emacs-lisp
- ;; Don't show anything for rainbow-mode.
- (use-package rainbow-mode
- :delight)
-
- ;; Don't show anything for auto-revert-mode, which doesn't match
- ;; its package name.
- (use-package autorevert
- :delight auto-revert-mode)
-
- ;; Remove the mode name for projectile-mode, but show the project name.
- (use-package projectile
- :delight '(:eval (concat " " (projectile-project-name))))
-
- ;; Completely hide visual-line-mode and change auto-fill-mode to " AF".
- (use-package emacs
- :delight
- (auto-fill-function " AF")
- (visual-line-mode))
-#+end_src
-
-** ~:disabled~
-
-The ~:disabled~ keyword can turn off a module you're having difficulties with,
-or stop loading something you're not using at the present time:
-
-#+begin_src emacs-lisp
- (use-package ess-site
- :disabled
- :commands R)
-#+end_src
-
-When byte-compiling your ~.emacs~ file, disabled declarations are omitted
-from the output entirely, to accelerate startup times.
-
-** ~:ensure~, ~:pin~
-
-You can use ~use-package~ to load packages from ELPA with ~package.el~. This
-is particularly useful if you share your ~.emacs~ among several machines; the
-relevant packages are downloaded automatically once declared in your ~.emacs~.
-The ~:ensure~ keyword causes the package(s) to be installed automatically if
-not already present on your system (set ~(setq use-package-always-ensure t)~
-if you wish this behavior to be global for all packages):
-
-#+begin_src emacs-lisp
- (use-package magit
- :ensure t)
-#+end_src
-
-If you need to install a different package from the one named by
-~use-package~, you can specify it like this:
-
-#+begin_src emacs-lisp
- (use-package tex
- :ensure auctex)
-#+end_src
-
-Lastly, when running on Emacs 24.4 or later, use-package can pin a package to
-a specific archive, allowing you to mix and match packages from different
-archives. The primary use-case for this is preferring packages from the
-~melpa-stable~ and ~gnu~ archives, but using specific packages from ~melpa~
-when you need to track newer versions than what is available in the ~stable~
-archives is also a valid use-case.
-
-By default ~package.el~ prefers ~melpa~ over ~melpa-stable~ due to the
-versioning ~(> evil-20141208.623 evil-1.0.9)~, so even if you are tracking
-only a single package from ~melpa~, you will need to tag all the non-~melpa~
-packages with the appropriate archive. If this really annoys you, then you can
-set ~use-package-always-pin~ to set a default.
-
-If you want to manually keep a package updated and ignore upstream updates,
-you can pin it to ~manual~, which as long as there is no repository by that
-name, will Just Work(tm).
-
-~use-package~ throws an error if you try to pin a package to an archive that
-has not been configured using ~package-archives~ (apart from the magic
-~manual~ archive mentioned above):
-
-#+begin_src text-mode
-Archive 'foo' requested for package 'bar' is not available.
-#+end_src
-
-Example:
-
-#+begin_src emacs-lisp
- (use-package company
- :ensure t
- :pin melpa-stable)
-
- (use-package evil
- :ensure t)
- ;; no :pin needed, as package.el will choose the version in melpa
-
- (use-package adaptive-wrap
- :ensure t
- ;; as this package is available only in the gnu archive, this is
- ;; technically not needed, but it helps to highlight where it
- ;; comes from
- :pin gnu)
-
- (use-package org
- :ensure t
- ;; ignore org-mode from upstream and use a manually installed version
- :pin manual)
-#+end_src
-
-*NOTE*: the ~:pin~ argument has no effect on emacs versions < 24.4.
-
-** ~:hook~
-
-The ~:hook~ keyword allows adding functions onto hooks, here only the basename
-of the hook is required. Thus, all of the following are equivalent:
-
-#+begin_src emacs-lisp
- (use-package ace-jump-mode
- :hook prog-mode)
-
- (use-package ace-jump-mode
- :hook (prog-mode . ace-jump-mode))
-
- (use-package ace-jump-mode
- :commands ace-jump-mode
- :init
- (add-hook 'prog-mode-hook #'ace-jump-mode))
-#+end_src
-
-And likewise, when multiple hooks should be applied, the following are also
-equivalent:
-
-#+begin_src emacs-lisp
- (use-package ace-jump-mode
- :hook (prog-mode text-mode))
-
- (use-package ace-jump-mode
- :hook ((prog-mode text-mode) . ace-jump-mode))
-
- (use-package ace-jump-mode
- :hook ((prog-mode . ace-jump-mode)
- (text-mode . ace-jump-mode)))
-
- (use-package ace-jump-mode
- :commands ace-jump-mode
- :init
- (add-hook 'prog-mode-hook #'ace-jump-mode)
- (add-hook 'text-mode-hook #'ace-jump-mode))
-#+end_src
-
-The use of ~:hook~, as with ~:bind~, ~:mode~, ~:interpreter~, etc., causes the
-functions being hooked to implicitly be read as ~:commands~ (meaning they will
-establish interactive ~autoload~ definitions for that module, if not already
-defined as functions), and so ~:defer t~ is also implied by ~:hook~.
-
-** ~:if~, ~:when~, ~:unless~
-
-You can use the ~:if~ keyword to predicate the loading and initialization of
-modules.
-
-For example, I only want ~edit-server~ running for my main, graphical Emacs,
-not for other Emacsen I may start at the command line:
-
-#+begin_src emacs-lisp
- (use-package edit-server
- :if window-system
- :init
- (add-hook 'after-init-hook 'server-start t)
- (add-hook 'after-init-hook 'edit-server-start t))
-#+end_src
-
-In another example, we can load things conditional on the operating system:
-
-#+begin_src emacs-lisp
- (use-package exec-path-from-shell
- :if (memq window-system '(mac ns))
- :ensure t
- :config
- (exec-path-from-shell-initialize))
-#+end_src
-
-Note that ~:when~ is provided as an alias for ~:if~, and ~:unless foo~ means
-the same thing as ~:if (not foo)~.
-
-** ~:load-path~
-
-If your package needs a directory added to the ~load-path~ in order to load,
-use ~:load-path~. This takes a symbol, a function, a string or a list of
-strings. If the path is relative, it is expanded within
-~user-emacs-directory~:
-
-#+begin_src emacs-lisp
- (use-package ess-site
- :load-path "site-lisp/ess/lisp/"
- :commands R)
-#+end_src
-
-Note that when using a symbol or a function to provide a dynamically generated
-list of paths, you must inform the byte-compiler of this definition so the
-value is available at byte-compilation time. This is done by using the special
-form ~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:
-
-#+begin_src emacs-lisp
- (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)
-#+end_src
-
-** ~:mode~, ~:interpreter~
-
-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:
-
-#+begin_src emacs-lisp
- (use-package ruby-mode
- :mode "\\.rb\\'"
- :interpreter "ruby")
-
- ;; The package is "python" but the mode is "python-mode":
- (use-package python
- :mode ("\\.py\\'" . python-mode)
- :interpreter ("python" . python-mode))
-#+end_src
-
-If you aren't using ~:commands~, ~:bind~, ~:bind*~, ~:bind-keymap~,
-~:bind-keymap*~, ~:mode~, or ~:interpreter~ (all of which imply ~:defer~; see
-the docstring for ~use-package~ for a brief description of each), you can
-still defer loading with the ~:defer~ keyword:
-
-#+begin_src emacs-lisp
- (use-package ace-jump-mode
- :defer t
- :init
- (autoload 'ace-jump-mode "ace-jump-mode" nil t)
- (bind-key "C-." 'ace-jump-mode))
-#+end_src
-
-This does exactly the same thing as the following:
-
-#+begin_src emacs-lisp
- (use-package ace-jump-mode
- :bind ("C-." . ace-jump-mode))
-#+end_src
-
-** ~:magic~, ~:magic-fallback~
-
-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 the two is
-that ~:magic-fallback~ has a lower priority than ~:mode~. For example:
-
-#+begin_src emacs-lisp
- (use-package pdf-tools
- :load-path "site-lisp/pdf-tools/lisp"
- :magic ("%PDF" . pdf-view-mode)
- :config
- (pdf-tools-install))
-#+end_src
-
-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"~.
-
-** ~:no-require~
-
-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:
-
-#+begin_src emacs-lisp
- (use-package foo
- :no-require t
- :config
- (message "This is evaluated when `foo' is loaded"))
-#+end_src
-
-** ~:requires~
-
-While the ~:after~ keyword delays loading until the dependencies are loaded,
-the somewhat simpler ~:requires~ keyword simply never loads the package if the
-dependencies are not available at the time the ~use-package~ declaration is
-encountered. By "available" in this context it means that ~foo~ is available
-of ~(featurep 'foo)~ evaluates to a non-nil value. For example:
-
-#+begin_src emacs-lisp
- (use-package abbrev
- :requires foo)
-#+end_src
-
-This is the same as:
-
-#+begin_src emacs-lisp
- (use-package abbrev
- :if (featurep 'foo))
-#+end_src
-
-As a convenience, a list of such packages may be specified:
-
-#+begin_src emacs-lisp
- (use-package abbrev
- :requires (foo bar baz))
-#+end_src
-
-For more complex logic, such as that supported by ~:after~, simply use ~:if~
-and the appropriate Lisp expression.
-
-* Debugging Tools
-:PROPERTIES:
-:EXPORT_FILE_NAME: debugging-tools
-:END:
-
-TODO
-
-* _ Copying
-:PROPERTIES:
-:COPYING: t
-:END:
-
-#+begin_quote
-Copyright (C) 2012-{{{year}}} Free Software Foundation, Inc.
-
-You can redistribute this document and/or modify it under the terms
-of the GNU General Public License as published by the Free Software
-Foundation, either version 3 of the License, or (at your option) any
-later version.
-
-This document is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-General Public License for more details.
-#+end_quote
-
-# LocalWords: ARG ARGS CONDITIONs ChangeLog DNS Dired Ediff Ediffing
-# LocalWords: Elpa Emacsclient FUNC Flyspell Git Git's Gitk HOOK's
-# LocalWords: IDENT Ido Junio LocalWords
-# LocalWords: Melpa Propertize REF REF's RET Reflog SPC SYM Spacemacs
-# LocalWords: Submodules TODO TYPEs Theming Unpulled Unpushed Unstaged
-# LocalWords: Untracked WORKTREE Wip ack args async autoloads autosaving
-# LocalWords: autosquash backport basename branchref builtin
-# LocalWords: cdr changelog committer config customizable diff's diffstat
-# LocalWords: dwim ediff ediffing editmsg emacsclient filename fixup
-# LocalWords: flyspell func git's gitk gitman gitmodule gitmodules goto
-# LocalWords: gpg gui ident ido init inserter inserters keymap keymaps
-# LocalWords: logfile use-package maildir manpage manpages minibuffer multi
mv
-# LocalWords: namespace newbase nocommit notesRef popup popups posix prev
-# LocalWords: propertize rebase rebased rebasing reflog repo signoff str
-# LocalWords: struct subcommand submodule submodule's submodules subprocess
-# LocalWords: sym texinfo theming todo topdir un unhighlighted unpulled
-# LocalWords: unpushed unstage unstaged unstages unstaging untracked url
-# LocalWords: versa whitespace wip workflow worktree wtree
-# LocalWords: backported macOS
-
-# Local Variables:
-# indent-tabs-mode: nil
-# org-src-preserve-indentation: nil
-# End:
diff --git a/use-package.texi b/use-package.texi
index de6351c592..573baac89a 100644
--- a/use-package.texi
+++ b/use-package.texi
@@ -8,7 +8,7 @@
@copying
@quotation
-Copyright (C) 2012-2022 John Wiegley <johnw@@newartisans.com>
+Copyright (C) 2012-2022 Free Software Foundation, Inc.
You can redistribute this document and/or modify it under the terms
of the GNU General Public License as published by the Free Software
@@ -31,7 +31,7 @@ General Public License for more details.
@finalout
@titlepage
@title use-package User Manual
-@subtitle for version 2.4.1-81-gb185c6b+1
+@subtitle for version 2.4.1-119-g0be480e+1
@author John Wiegley
@page
@vskip 0pt plus 1filll
@@ -45,9 +45,9 @@ General Public License for more details.
@top use-package User Manual
The @code{use-package} macro allows you to isolate package configuration in
your
-@code{.emacs} file in a way that is both performance-oriented and, well, tidy.
I
+@code{.emacs} file in a way that is both performance-oriented and, well, tidy.
I
created it because I have over 80 packages that I use in Emacs, and things
-were getting difficult to manage. Yet with this utility my total load time is
+were getting difficult to manage. Yet with this utility my total load time is
around 2 seconds, with no loss of functionality!
@insertcopying
@@ -73,27 +73,27 @@ Installation
Keywords
-* @code{after}::
-* @code{bind-keymap}, @code{bind-keymap*}: @code{bind-keymap}
@code{bind-keymap*}.
-* @code{bind}, @code{bind*}: @code{bind} @code{bind*}.
-* @code{commands}::
-* @code{preface}, @code{init}, @code{config}: @code{preface} @code{init}
@code{config}.
-* @code{custom}::
-* @code{custom-face}::
-* @code{defer}, @code{demand}: @code{defer} @code{demand}.
-* @code{defines}, @code{functions}: @code{defines} @code{functions}.
-* @code{diminish}, @code{delight}: @code{diminish} @code{delight}.
-* @code{disabled}::
-* @code{ensure}, @code{pin}: @code{ensure} @code{pin}.
-* @code{hook}::
-* @code{if}, @code{when}, @code{unless}: @code{if} @code{when} @code{unless}.
-* @code{load-path}::
-* @code{mode}, @code{interpreter}: @code{mode} @code{interpreter}.
-* @code{magic}, @code{magic-fallback}: @code{magic} @code{magic-fallback}.
-* @code{no-require}::
-* @code{requires}::
-
-@code{:bind}, @code{:bind*}
+* @code{after}:: @code{:after}.
+* @code{bind-keymap} @code{bind-keymap*}:: @code{:bind-keymap},
@code{:bind-keymap*}.
+* @code{bind} @code{bind*}:: @code{:bind}, @code{:bind*}.
+* @code{commands}:: @code{:commands}.
+* @code{preface} @code{init} @code{config}:: @code{:preface}, @code{:init},
@code{:config}.
+* @code{custom}:: @code{:custom}.
+* @code{custom-face}:: @code{:custom-face}.
+* @code{defer} @code{demand}:: @code{:defer}, @code{:demand}.
+* @code{defines} @code{functions}:: @code{:defines}, @code{:functions}.
+* @code{diminish} @code{delight}:: @code{:diminish}, @code{:delight}.
+* @code{disabled}:: @code{:disabled}.
+* @code{ensure} @code{pin}:: @code{:ensure}, @code{:pin}.
+* @code{hook}:: @code{:hook}.
+* @code{if} @code{when} @code{unless}:: @code{:if}, @code{:when},
@code{:unless}.
+* @code{load-path}:: @code{:load-path}.
+* @code{mode} @code{interpreter}:: @code{:mode}, @code{:interpreter}.
+* @code{magic} @code{magic-fallback}:: @code{:magic}, @code{:magic-fallback}.
+* @code{no-require}:: @code{:no-require}.
+* @code{requires}:: @code{:requires}.
+
+@code{bind}, @code{bind*}
* Binding to local keymaps::
@@ -105,9 +105,9 @@ Keywords
@chapter Introduction
The @code{use-package} macro allows you to isolate package configuration in
your
-@code{.emacs} file in a way that is both performance-oriented and, well, tidy.
I
+@code{.emacs} file in a way that is both performance-oriented and, well, tidy.
I
created it because I have over 80 packages that I use in Emacs, and things
-were getting difficult to manage. Yet with this utility my total load time is
+were getting difficult to manage. Yet with this utility my total load time is
around 2 seconds, with no loss of functionality!
More text to come@dots{}
@@ -127,10 +127,10 @@ its development repository.
@node Installing from GNU ELPA
@section Installing from GNU ELPA
-use-package is available from GNU ELPA. If you haven't used Emacs'
-package manager before, then it is high time you familiarize yourself
+use-package is available from GNU ELPA. If you haven't used
+Emacs' package manager before, then it is high time you familiarize yourself
with it by reading the documentation in the Emacs manual, see
-@ref{Packages,,,emacs,}.
+@ref{Packages,,,emacs,}. Then add one of the archives to
@code{package-archives}:
First, you need to update the local package list using:
@@ -206,7 +206,7 @@ Now see @ref{Post-Installation Tasks}.
@section Post-Installation Tasks
After installing use-package you should verify that you are indeed using the
-use-package release you think you are using. It's best to restart Emacs before
+use-package release you think you are using. It's best to restart Emacs before
doing so, to make sure you are not using an outdated value for
@code{load-path}.
@example
@@ -216,7 +216,7 @@ C-h v use-package-version RET
should display something like
@example
-use-package-version’s value is "2.4.1"
+use-package-version’s value is "2.4.3"
@end example
If you are completely new to use-package then see @ref{Getting Started}.
@@ -226,13 +226,13 @@ If you run into problems, then please see the
@ref{Debugging Tools}.
@node Getting Started
@chapter Getting Started
-TODO@. For now, see @code{README.md}.
+TODO@. For now, see @code{README.md}.
@node Basic Concepts
@chapter Basic Concepts
@code{use-package} was created for few basic reasons, each of which drove the
-design in various ways. Understanding these reasons may help make some of
+design in various ways. Understanding these reasons may help make some of
those decisions clearer:
@itemize
@@ -256,7 +256,7 @@ close to a functional Emacs as possible.
@item
To allow byte-compilation of one's init file so that any warnings or
-errors seen are meaningful. In this way, even if byte-compilation is not
+errors seen are meaningful. In this way, even if byte-compilation is not
used for speed (reason 3), it can still be used as a sanity check.
@end itemize
@@ -267,25 +267,25 @@ used for speed (reason 3), it can still be used as a
sanity check.
@chapter Keywords
@menu
-* @code{after}::
-* @code{bind-keymap}, @code{bind-keymap*}: @code{bind-keymap}
@code{bind-keymap*}.
-* @code{bind}, @code{bind*}: @code{bind} @code{bind*}.
-* @code{commands}::
-* @code{preface}, @code{init}, @code{config}: @code{preface} @code{init}
@code{config}.
-* @code{custom}::
-* @code{custom-face}::
-* @code{defer}, @code{demand}: @code{defer} @code{demand}.
-* @code{defines}, @code{functions}: @code{defines} @code{functions}.
-* @code{diminish}, @code{delight}: @code{diminish} @code{delight}.
-* @code{disabled}::
-* @code{ensure}, @code{pin}: @code{ensure} @code{pin}.
-* @code{hook}::
-* @code{if}, @code{when}, @code{unless}: @code{if} @code{when} @code{unless}.
-* @code{load-path}::
-* @code{mode}, @code{interpreter}: @code{mode} @code{interpreter}.
-* @code{magic}, @code{magic-fallback}: @code{magic} @code{magic-fallback}.
-* @code{no-require}::
-* @code{requires}::
+* @code{after}:: @code{after}.
+* @code{bind-keymap} @code{bind-keymap*}:: @code{:bind-keymap},
@code{:bind-keymap*}.
+* @code{bind} @code{bind*}:: @code{bind} @code{:bind*}.
+* @code{commands}:: @code{:commands}.
+* @code{preface} @code{init} @code{config}:: @code{:preface}, @code{:init},
@code{:config}.
+* @code{custom}:: @code{:custom}.
+* @code{custom-face}:: @code{:custom-face}.
+* @code{defer} @code{demand}:: @code{:defer}, @code{:demand}.
+* @code{defines} @code{functions}:: @code{:defines}, @code{:functions}.
+* @code{diminish} @code{delight}:: @code{:diminish}, @code{:delight}.
+* @code{disabled}:: @code{:disabled}.
+* @code{ensure} @code{pin}:: @code{:ensure}, @code{:pin}.
+* @code{hook}:: @code{:hook}.
+* @code{if} @code{when} @code{unless}:: @code{:if}, @code{:when},
@code{:unless}.
+* @code{load-path}:: @code{:load-path}.
+* @code{mode} @code{interpreter}:: @code{:mode}, @code{:interpreter}.
+* @code{magic} @code{magic-fallback}:: @code{:magic}, @code{:magic-fallback}.
+* @code{no-require}:: @code{:no-require}.
+* @code{requires}:: @code{:requires}.
@end menu
@node @code{after}
@@ -293,8 +293,8 @@ used for speed (reason 3), it can still be used as a sanity
check.
Sometimes it only makes sense to configure a package after another has been
loaded, because certain variables or functions are not in scope until that
-time. This can achieved using an @code{:after} keyword that allows a fairly
rich
-description of the exact conditions when loading should occur. Here is an
+time. This can achieved using an @code{:after} keyword that allows a fairly
rich
+description of the exact conditions when loading should occur. Here is an
example:
@lisp
@@ -309,13 +309,13 @@ example:
@end lisp
In this case, because all of these packages are demand-loaded in the order
-they occur, the use of @code{:after} is not strictly necessary. By using it,
+they occur, the use of @code{:after} is not strictly necessary. By using it,
however, the above code becomes order-independent, without an implicit
depedence on the nature of your init file.
By default, @code{:after (foo bar)} is the same as @code{:after (:all foo
bar)}, meaning
that loading of the given package will not happen until both @code{foo} and
@code{bar}
-have been loaded. Here are some of the other possibilities:
+have been loaded. Here are some of the other possibilities:
@lisp
:after (foo bar)
@@ -331,7 +331,7 @@ been loaded, or both @code{baz} and @code{quux} have been
loaded.
@strong{NOTE}: Pay attention if you set @code{use-package-always-defer} to t,
and also use
the @code{:after} keyword, as you will need to specify how the declared
package is
-to be loaded: e.g., by some @code{:bind}. If you're not using one of the
mechanisms
+to be loaded: e.g., by some @code{:bind}. If you're not using one of the
mechanisms
that registers autoloads, such as @code{:bind} or @code{:hook}, and your
package manager
does not provide autoloads, it's possible that without adding @code{:demand t}
to
those declarations, your package will never be loaded.
@@ -340,14 +340,14 @@ those declarations, your package will never be loaded.
@section @code{:bind-keymap}, @code{:bind-keymap*}
Normally @code{:bind} expects that commands are functions that will be
autoloaded
-from the given package. However, this does not work if one of those commands
+from the given package. However, this does not work if one of those commands
is actually a keymap, since keymaps are not functions, and cannot be
autoloaded using Emacs' @code{autoload} mechanism.
To handle this case, @code{use-package} offers a special, limited variant of
-@code{:bind} called @code{:bind-keymap}. The only difference is that the
"commands"
+@code{:bind} called @code{:bind-keymap}. The only difference is that the
"commands"
bound to by @code{:bind-keymap} must be keymaps defined in the package, rather
than
-command functions. This is handled behind the scenes by generating custom code
+command functions. This is handled behind the scenes by generating custom code
that loads the package containing the keymap, and then re-executes your
keypress after the first load, to reinterpret that keypress as a prefix key.
@@ -386,7 +386,7 @@ A more literal way to do the exact same thing is:
@end lisp
When you use the @code{:commands} keyword, it creates autoloads for those
commands
-and defers loading of the module until they are used. Since the @code{:init}
form
+and defers loading of the module until they are used. Since the @code{:init}
form
is always run---even if @code{ace-jump-mode} might not be on your
system---remember
to restrict @code{:init} code to only what would succeed either way.
@@ -402,7 +402,7 @@ The @code{:bind} keyword takes either a cons or a list of
conses:
The @code{:commands} keyword likewise takes either a symbol or a list of
symbols.
NOTE: Special keys like @code{tab} or @code{F1}-@code{Fn} can be written in
square brackets,
-i.e. @code{[tab]} instead of @code{"tab"}. The syntax for the keybindings is
similar to
+i.e. @code{[tab]} instead of @code{"tab"}. The syntax for the keybindings is
similar to
the "kbd" syntax: see
@uref{https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Rebinding.html,
the Emacs Manual} for more information.
Examples:
@@ -436,7 +436,7 @@ The effect of this statement is to wait until @code{helm}
has loaded, and then t
bind the key @code{C-c h} to @code{helm-execute-persistent-action} within
Helm's local
keymap, @code{helm-mode-map}.
-Multiple uses of @code{:map} may be specified. Any binding occurring before the
+Multiple uses of @code{:map} may be specified. Any binding occurring before
the
first use of @code{:map} are applied to the global keymap:
@lisp
@@ -470,7 +470,7 @@ Here is the simplest @code{use-package} declaration:
@end lisp
This loads in the package @code{foo}, but only if @code{foo} is available on
your
-system. If not, a warning is logged to the @code{*Messages*} buffer. If it
+system. If not, a warning is logged to the @code{*Messages*} buffer. If it
succeeds, a message about @code{"Loading foo"} is logged, along with the time
it
took to load, if it took over 0.1 seconds.
@@ -544,14 +544,14 @@ The @code{:custom-face} keyword allows customization of
package custom faces.
@node @code{defer} @code{demand}
@section @code{:defer}, @code{:demand}
-In almost all cases you don't need to manually specify @code{:defer t}. This is
-implied whenever @code{:bind} or @code{:mode} or @code{:interpreter} is used.
Typically, you
+In almost all cases you don't need to manually specify @code{:defer t}. This
is
+implied whenever @code{:bind} or @code{:mode} or @code{:interpreter} is used.
Typically, you
only need to specify @code{:defer} if you know for a fact that some other
package
will do something to cause your package to load at the appropriate time, and
thus you would like to defer loading even though use-package isn't creating
any autoloads for you.
-You can override package deferral with the @code{:demand} keyword. Thus, even
if
+You can override package deferral with the @code{:demand} keyword. Thus, even
if
you use @code{:bind}, using @code{:demand} will force loading to occur
immediately and
not establish an autoload for the bound key.
@@ -593,7 +593,7 @@ If you need to silence a missing function warning, you can
use @code{:functions}
@section @code{:diminish}, @code{:delight}
@code{use-package} also provides built-in support for the diminish and delight
-utilities---if you have them installed. Their purpose is to remove or change
+utilities---if you have them installed. Their purpose is to remove or change
minor mode strings in your mode-line.
@uref{https://github.com/myrjola/diminish.el, diminish} is invoked with the
@code{:diminish} keyword, which is passed either a
@@ -612,7 +612,7 @@ package name with "-mode" appended at the end:
@uref{https://elpa.gnu.org/packages/delight.html, delight} is invoked with the
@code{:delight} keyword, which is passed a minor mode
symbol, a replacement string or quoted
@uref{https://www.gnu.org/software/emacs/manual/html_node/elisp/Mode-Line-Data.html,
mode-line data} (in which case the minor
mode symbol is guessed to be the package name with "-mode" appended at the
-end), both of these, or several lists of both. If no arguments are provided,
+end), both of these, or several lists of both. If no arguments are provided,
the default mode name is hidden completely.
@lisp
@@ -654,7 +654,7 @@ from the output entirely, to accelerate startup times.
@node @code{ensure} @code{pin}
@section @code{:ensure}, @code{:pin}
-You can use @code{use-package} to load packages from ELPA with
@code{package.el}. This
+You can use @code{use-package} to load packages from ELPA with
@code{package.el}. This
is particularly useful if you share your @code{.emacs} among several machines;
the
relevant packages are downloaded automatically once declared in your
@code{.emacs}.
The @code{:ensure} keyword causes the package(s) to be installed automatically
if
@@ -684,7 +684,7 @@ archives is also a valid use-case.
By default @code{package.el} prefers @code{melpa} over @code{melpa-stable} due
to the
versioning @code{(> evil-20141208.623 evil-1.0.9)}, so even if you are tracking
only a single package from @code{melpa}, you will need to tag all the
non-@code{melpa}
-packages with the appropriate archive. If this really annoys you, then you can
+packages with the appropriate archive. If this really annoys you, then you can
set @code{use-package-always-pin} to set a default.
If you want to manually keep a package updated and ignore upstream updates,
@@ -729,7 +729,7 @@ Example:
@section @code{:hook}
The @code{:hook} keyword allows adding functions onto hooks, here only the
basename
-of the hook is required. Thus, all of the following are equivalent:
+of the hook is required. Thus, all of the following are equivalent:
@lisp
(use-package ace-jump-mode
@@ -804,8 +804,8 @@ the same thing as @code{:if (not foo)}.
@section @code{:load-path}
If your package needs a directory added to the @code{load-path} in order to
load,
-use @code{:load-path}. This takes a symbol, a function, a string or a list of
-strings. If the path is relative, it is expanded within
+use @code{:load-path}. This takes a symbol, a function, a string or a list of
+strings. If the path is relative, it is expanded within
@code{user-emacs-directory}:
@lisp
@@ -816,8 +816,8 @@ strings. If the path is relative, it is expanded within
Note that when using a symbol or a function to provide a dynamically generated
list of paths, you must inform the byte-compiler of this definition so the
-value is available at byte-compilation time. This is done by using the special
-form @code{eval-and-compile} (as opposed to @code{eval-when-compile}).
Further, this
+value is available at byte-compilation time. This is done by using the special
+form @code{eval-and-compile} (as opposed to @code{eval-when-compile}).
Further, this
value is fixed at whatever was determined during compilation, to avoid looking
up the same information again on each startup:
@@ -836,7 +836,7 @@ up the same information again on each startup:
Similar to @code{:bind}, you can use @code{:mode} and @code{:interpreter} to
establish a
deferred binding within the @code{auto-mode-alist} and
@code{interpreter-mode-alist}
-variables. The specifier to either keyword can be a cons cell, a list of cons
+variables. The specifier to either keyword can be a cons cell, a list of cons
cells, or a string or regexp:
@lisp
@@ -875,8 +875,8 @@ This does exactly the same thing as the following:
Similar to @code{:mode} and @code{:interpreter}, you can also use
@code{:magic} and
@code{:magic-fallback} to cause certain function to be run if the beginning of
a
-file matches a given regular expression. The difference between the two is
-that @code{:magic-fallback} has a lower priority than @code{:mode}. For
example:
+file matches a given regular expression. The difference between the two is
+that @code{:magic-fallback} has a lower priority than @code{:mode}. For
example:
@lisp
(use-package pdf-tools
@@ -895,9 +895,9 @@ string @code{"%PDF"}.
Normally, @code{use-package} will load each package at compile time before
compiling the configuration, to ensure that any necessary symbols are in scope
-to satisfy the byte-compiler. At times this can cause problems, since a
+to satisfy the byte-compiler. At times this can cause problems, since a
package may have special loading requirements, and all that you want to use
-@code{use-package} for is to add a configuration to the @code{eval-after-load}
hook. In
+@code{use-package} for is to add a configuration to the @code{eval-after-load}
hook. In
such cases, use the @code{:no-require} keyword:
@lisp
@@ -913,8 +913,8 @@ such cases, use the @code{:no-require} keyword:
While the @code{:after} keyword delays loading until the dependencies are
loaded,
the somewhat simpler @code{:requires} keyword simply never loads the package
if the
dependencies are not available at the time the @code{use-package} declaration
is
-encountered. By "available" in this context it means that @code{foo} is
available
-of @code{(featurep 'foo)} evaluates to a non-nil value. For example:
+encountered. By "available" in this context it means that @code{foo} is
available
+of @code{(featurep 'foo)} evaluates to a non-nil value. For example:
@lisp
(use-package abbrev
- [elpa] externals/bind-key updated (87c03dffc7 -> 21a126cb7e), ELPA Syncer, 2022/11/15
- [elpa] externals/bind-key 8354533d36 2/9: Delete use-package.org, ELPA Syncer, 2022/11/15
- [elpa] externals/bind-key 8bdfe31fbb 7/9: Merge pull request #1017 from skangas/gnu-elpa, ELPA Syncer, 2022/11/15
- [elpa] externals/bind-key 2a7da686bc 1/9: manual: Regenerate texi file, ELPA Syncer, 2022/11/15
- [elpa] externals/bind-key 7126fb73f9 4/9: Move incorrectly placed example in README, ELPA Syncer, 2022/11/15
- [elpa] externals/bind-key 2f7544a081 6/9: Fix makeinfo warnings, ELPA Syncer, 2022/11/15
- [elpa] externals/bind-key 77e04dc55b 3/9: Recommend GNU ELPA over MELPA, ELPA Syncer, 2022/11/15
- [elpa] externals/bind-key b8f0537840 8/9: Merge branch 'master' into texinfo-wip, ELPA Syncer, 2022/11/15
- [elpa] externals/bind-key 21a126cb7e 9/9: Merge pull request #1018 from skangas/texinfo-wip,
ELPA Syncer <=
- [elpa] externals/bind-key 1938f50e74 5/9: Use two spaces to end sentences, ELPA Syncer, 2022/11/15