Update use-package.texi

doc/misc/use-package.texi

@@ -17,8 +17,9 @@ 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
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@.  See the GNU
 General Public License for more details.
+
 @end quotation
 @end copying
 
@@ -54,7 +55,8 @@ 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.
+FOR A PARTICULAR PURPOSE@. See the GNU General Public License for more details.
+
 @end quotation
 @end ifnottex
 
@@ -62,6 +64,8 @@ FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
 * Introduction::
 * Installation::
 * Getting Started::
+* Basic Concepts::
+* Issues/Requests::
 * Keywords::
 * FAQ::
 * Debugging Tools::
@@ -72,44 +76,39 @@ FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
 @detailmenu
 --- The Detailed Node Listing ---
 
-
 Installation
 
 * Installing from an Elpa Archive::
 * Installing from the Git Repository::
 * Post-Installation Tasks::
 
-
-
-
 Keywords
 
-* @code{:after}: @code{after}. 
+* @code{after}::
-* @code{:bind-keymap}, @code{:bind-keymap*}: @code{bind-keymap} @code{bind-keymap*}. 
+* @code{bind-keymap}, @code{bind-keymap*}: @code{bind-keymap} @code{bind-keymap*}. 
-* @code{:bind}, @code{:bind*}: @code{bind} @code{bind*}. 
+* @code{bind}, @code{bind*}: @code{bind} @code{bind*}. 
-* @code{:commands}: @code{commands}. 
+* @code{commands}::
-* @code{:preface}, @code{:init}, @code{:config}: @code{preface} @code{init} @code{config}. 
+* @code{preface}, @code{init}, @code{config}: @code{preface} @code{init} @code{config}. 
-* @code{:custom}: @code{custom}. 
+* @code{custom}::
-* @code{:custom-face}: @code{custom-face}. 
+* @code{custom-face}::
-* @code{:defer}, @code{:demand}: @code{defer} @code{demand}. 
+* @code{defer}, @code{demand}: @code{defer} @code{demand}. 
-* @code{:defines}, @code{:functions}: @code{defines} @code{functions}. 
+* @code{defines}, @code{functions}: @code{defines} @code{functions}. 
-* @code{:diminish}, @code{:delight}: @code{diminish} @code{delight}. 
+* @code{diminish}, @code{delight}: @code{diminish} @code{delight}. 
-* @code{:disabled}: @code{disabled}. 
+* @code{disabled}::
-* @code{:ensure}, @code{:pin}: @code{ensure} @code{pin}. 
+* @code{ensure}, @code{pin}: @code{ensure} @code{pin}. 
-* @code{:hook}: @code{hook}. 
+* @code{hook}::
-* @code{:if}, @code{:when}, @code{:unless}: @code{if} @code{when} @code{unless}. 
+* @code{if}, @code{when}, @code{unless}: @code{if} @code{when} @code{unless}. 
-* @code{:load-path}: @code{load-path}. 
+* @code{load-path}::
-* @code{:mode}, @code{:interpreter}: @code{mode} @code{interpreter}. 
+* @code{mode}, @code{interpreter}: @code{mode} @code{interpreter}. 
-* @code{:magic}, @code{:magic-fallback}: @code{magic} @code{magic-fallback}. 
+* @code{magic}, @code{magic-fallback}: @code{magic} @code{magic-fallback}. 
-* @code{:no-require}: @code{no-require}. 
+* @code{no-require}::
-* @code{:requires}: @code{requires}. 
+* @code{requires}::
-
-
 
 @code{:bind}, @code{:bind*}
 
 * Binding to local keymaps::
 
+
 FAQ
 
 * FAQ - How to @dots{}?::
@@ -123,21 +122,31 @@ FAQ - How to @dots{}?
 FAQ - Issues and Errors
 
 * This is an issues::
+
+
 @end detailmenu
 @end menu
 
 @node Introduction
 @chapter Introduction
 
-The @code{use-package} macro allows you to isolate package configuration
+The @code{use-package} macro allows you to isolate package configuration in your
-in your @file{.emacs} file in a way that is both performance-oriented and,
+@code{.emacs} file in a way that is both performance-oriented and, well, tidy. I
-well, tidy.  I created it because I have over 400 packages that I use in
+created it because I have over 80 packages that I use in Emacs, and things
-Emacs, and things were getting difficult to manage.  Yet with this utility
+were getting difficult to manage. Yet with this utility my total load time is
-my total load time is around 2 seconds, with no loss of functionality!
+around 2 seconds, with no loss of functionality!
+
+More text to come@dots{}
 
 @node Installation
 @chapter Installation
 
+@menu
+* Installing from an Elpa Archive::
+* Installing from the Git Repository::
+* Post-Installation Tasks::
+@end menu
+
 use-package can be installed using Emacs' package manager or manually from
 its development repository.
 
@@ -267,37 +276,75 @@ use-package-version’s value is "2.4.1"
 
 If you are completely new to use-package then see @ref{Getting Started}.
 
-If you run into problems, then please see the @ref{FAQ}.  Also see the
+If you run into problems, then please see the
-@ref{Debugging Tools}.
+@ref{FAQ}.  Also 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
+those decisions clearer:
+
+@itemize
+@item
+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.
+
+
+@item
+To reduce duplication and boilerplate, capturing several common practices
+as mere keywords both easy and intuitive to use.
+
+
+@item
+To make startup time of Emacs as quick as possible, without sacrificing
+the quantity of add-on packages used.
+
+
+@item
+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.
+
+
+@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
+used for speed (reason 3), it can still be used as a sanity check.
+@end itemize
+
+@node Issues/Requests
+@chapter Issues/Requests
 
 @node Keywords
 @chapter Keywords
 
 @menu
-* @code{:after}: @code{after}. 
+* @code{after}::
-* @code{:bind-keymap}, @code{:bind-keymap*}: @code{bind-keymap} @code{bind-keymap*}. 
+* @code{bind-keymap}, @code{bind-keymap*}: @code{bind-keymap} @code{bind-keymap*}. 
-* @code{:bind}, @code{:bind*}: @code{bind} @code{bind*}. 
+* @code{bind}, @code{bind*}: @code{bind} @code{bind*}. 
-* @code{:commands}: @code{commands}. 
+* @code{commands}::
-* @code{:preface}, @code{:init}, @code{:config}: @code{preface} @code{init} @code{config}. 
+* @code{preface}, @code{init}, @code{config}: @code{preface} @code{init} @code{config}. 
-* @code{:custom}: @code{custom}. 
+* @code{custom}::
-* @code{:custom-face}: @code{custom-face}. 
+* @code{custom-face}::
-* @code{:defer}, @code{:demand}: @code{defer} @code{demand}. 
+* @code{defer}, @code{demand}: @code{defer} @code{demand}. 
-* @code{:defines}, @code{:functions}: @code{defines} @code{functions}. 
+* @code{defines}, @code{functions}: @code{defines} @code{functions}. 
-* @code{:diminish}, @code{:delight}: @code{diminish} @code{delight}. 
+* @code{diminish}, @code{delight}: @code{diminish} @code{delight}. 
-* @code{:disabled}: @code{disabled}. 
+* @code{disabled}::
-* @code{:ensure}, @code{:pin}: @code{ensure} @code{pin}. 
+* @code{ensure}, @code{pin}: @code{ensure} @code{pin}. 
-* @code{:hook}: @code{hook}. 
+* @code{hook}::
-* @code{:if}, @code{:when}, @code{:unless}: @code{if} @code{when} @code{unless}. 
+* @code{if}, @code{when}, @code{unless}: @code{if} @code{when} @code{unless}. 
-* @code{:load-path}: @code{load-path}. 
+* @code{load-path}::
-* @code{:mode}, @code{:interpreter}: @code{mode} @code{interpreter}. 
+* @code{mode}, @code{interpreter}: @code{mode} @code{interpreter}. 
-* @code{:magic}, @code{:magic-fallback}: @code{magic} @code{magic-fallback}. 
+* @code{magic}, @code{magic-fallback}: @code{magic} @code{magic-fallback}. 
-* @code{:no-require}: @code{no-require}. 
+* @code{no-require}::
-* @code{:requires}: @code{requires}. 
+* @code{requires}::
 @end menu
 
 @node @code{after}
@@ -341,6 +388,13 @@ When you nest selectors, such as @code{(:any (:all foo bar) (:all baz quux))}, i
 means that the package will be loaded when either both @code{foo} and @code{bar} have
 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
+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.
+
 @node @code{bind-keymap} @code{bind-keymap*}
 @section @code{:bind-keymap}, @code{:bind-keymap*}
 
@@ -878,22 +932,22 @@ This does exactly the same thing as the following:
 @node @code{magic} @code{magic-fallback}
 @section @code{:magic}, @code{:magic-fallback}
 
-Similar to `:mode` and `:interpreter`, you can also use `:magic` and
+Similar to @code{:mode} and @code{:interpreter}, you can also use @code{:magic} and
-`:magic-fallback` to cause certain function to be run if the beginning of a
+@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 `:magic-fallback` has a lower priority than `:mode`. For example:
+that @code{:magic-fallback} has a lower priority than @code{:mode}. For example:
 
-``` elisp
+@lisp
 (use-package pdf-tools
   :load-path "site-lisp/pdf-tools/lisp"
   :magic ("%PDF" . pdf-view-mode)
   :config
   (pdf-tools-install))
-```
+@end lisp
 
-This registers an autoloaded command for `pdf-view-mode`, defers loading of
+This registers an autoloaded command for @code{pdf-view-mode}, defers loading of
-`pdf-tools`, and runs `pdf-view-mode` if the beginning of a buffer matches the
+@code{pdf-tools}, and runs @code{pdf-view-mode} if the beginning of a buffer matches the
-string `"%PDF"`.
+string @code{"%PDF"}.
 
 @node @code{no-require}
 @section @code{:no-require}
@@ -1001,4 +1055,5 @@ Please also see the @ref{FAQ}.
 
 @printindex vr
 
+Emacs 28.0.92 (Org mode 9.5.2)
 @bye