From: Stefan Kangas Date: Tue, 15 Nov 2022 07:51:39 +0000 (+0100) Subject: Use two spaces to end sentences X-Git-Tag: emacs-29.0.90~1306^2~15^2~7^2~2 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=a6b1b62763;p=emacs.git Use two spaces to end sentences --- diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi index a5f850c8753..fc504305b48 100644 --- a/doc/misc/use-package.texi +++ b/doc/misc/use-package.texi @@ -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 @@ -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 an Elpa Archive @section Installing from an Elpa Archive -use-package is available from Melpa and Melpa-Stable. If you haven't used +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 -@ref{Packages,,,emacs,}. Then add one of the archives to @code{package-archives}: +@ref{Packages,,,emacs,}. Then add one of the archives to @code{package-archives}: @itemize @item @@ -229,7 +229,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 @@ -249,13 +249,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 @@ -279,7 +279,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 @@ -316,8 +316,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 @@ -332,13 +332,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) @@ -354,7 +354,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. @@ -363,14 +363,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. @@ -409,7 +409,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. @@ -425,7 +425,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: @@ -459,7 +459,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 @@ -493,7 +493,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. @@ -567,14 +567,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. @@ -616,7 +616,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 @@ -635,7 +635,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 @@ -677,7 +677,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 @@ -707,7 +707,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, @@ -752,7 +752,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 @@ -827,8 +827,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 @@ -839,8 +839,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: @@ -859,7 +859,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 @@ -898,8 +898,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 @@ -918,9 +918,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 @@ -936,8 +936,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