Merge from origin/emacs-29

06ef030f936 use-package.texi: New section "Manual installation"
f4ce6fa7d3e Revert "Revert "Improve last change to xfaces.c" (05ece1e...
b8d2ec920f3 Revert "Improve last change to xfaces.c" (05ece1eb8b)
24c8c28ae61 Do not pare arguments unnecessarily.
9c0d7bb73bb Add automated tests for Eglot
d3669cfe156 Eglot: allow skipping compile-time warnings about LSP int...
04b7e01885d ; project.el: Bump version.
f2876014adb Add customizale faces for tree-sitter explorer
3e349ee1198 Fix error message when installing non-existent package
733cdeabfb9 Don't use diff-mode buffer as a patch when it's visiting ...
87475f4af21 Fix pcase rx patterns using rx-let bindings (bug#59814)
4893a156317 Fix use-package-defaults defcustom type (bug#59941)
074b7e6f4d1 ; * lisp/use-package/bind-key.el: Remove ineffective back...
864ed9dfa1f ; * lisp/progmodes/dockerfile-ts-mode.el: use \' instead ...
9f7e5584a4f * lisp/language/indian.el: Improve Brahmi composition rul...
78ad33bb05f ; Minor cleanup of last change in xfaces.c.
2024ade271d ; Improve docs of relaxing face-font attribute match (bug...

1 files changed, 48 insertions, 30 deletions

diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi
index 0aa8975f30a..c587d23d74b 100644
--- a/doc/misc/use-package.texi
+++ b/doc/misc/use-package.texi
@@ -248,10 +248,6 @@ packages using the built-in @code{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 @code{load-path}.  @xref{Lisp Libraries,,, emacs,
-GNU Emacs Manual}, for details.
-
 Some packages have more than one library.  In those cases, you might
 need more than one @code{use-package} declaration to make sure the
 package is properly loaded.  For complex configurations, you might
@@ -267,8 +263,7 @@ on Emacs start.  @xref{Installing packages}, for details.
 * Conditional loading::         Loading packages conditionally.
 * Loading sequentially::        Loading packages in sequence.
 * Load dependencies::           Don't load without dependencies.
-* Load path::                   Using a custom @code{load-path}.
-* Manual autoloads::            Setting up autoloads manually.
+* Manual installation::         Loading manually installed packages.
 @end menu
 
 @node Loading basics
@@ -623,36 +618,54 @@ As a convenience, a list of such packages may be specified:
 For more complex logic, such as that supported by @code{:after},
 simply use @code{:if} and the appropriate Lisp expression.
 
+@node Manual installation
+@section Manually installed package
+
+When installing packages manually, without Emacs' built-in package
+manager (@file{package.el}), it will obviously not help you set up
+autoloads or add it to your @code{load-path}.  You must do it
+yourself.  However, use-package makes this more convenient.
+
+@menu
+* Load path::                   Using a custom @code{load-path}.
+* Manual autoloads::            Setting up autoloads manually.
+@end menu
+
 @node Load path
-@section Setting a custom @code{load-path}
+@subsection Setting a custom @code{load-path}
 @cindex custom @code{load-path} for loading a package
 @cindex @code{load-path}, add directories for loading a package
 
+When installing packages manually, you must make sure its libraries
+are available on your @code{load-path}.  @xref{Lisp Libraries,,,
+emacs, GNU Emacs Manual}, for more details about package loading.
+
 @findex :load-path
-If a package resides in some directory that is not in your
-@code{load-path}, use the @code{:load-path} keyword to add it.  It
-takes as argument a symbol, a function, a string or a list of strings.
-If a directory is specified as a relative file name, it is expanded
-relative to @code{user-emacs-directory}.
+The @code{:load-path} keyword provides a convenient way to add
+directories to your load path.  It takes as argument a symbol, a
+function, a string or a list of strings.  If a directory is specified
+as a relative file name, it is expanded relative to
+@code{user-emacs-directory}.
 
 For example:
 
 @lisp
 @group
-(use-package ess-site
-  :load-path "site-lisp/ess/lisp/"
-  :commands R)
+(use-package org
+  :load-path "site-lisp/org/lisp/"
+  :commands org-mode)
 @end group
 @end lisp
 
-Note that when using a symbol or a function to provide a dynamically
-generated list of directories, you must inform the byte-compiler of this
-definition so that the value is available at byte-compilation time.
+When using a symbol or a function to provide a dynamically generated
+list of directories, 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 @code{eval-and-compile} (as
 opposed to @code{eval-when-compile}, @pxref{Eval During Compile,,,
-elisp, GNU Emacs Lisp Reference Manual}).  Further, this value is fixed at
-whatever was determined during compilation, to avoid looking up the
-same information again on each startup.  For example:
+elisp, GNU Emacs Lisp Reference Manual}).  Furthermore, this value is
+fixed to the value it had during compilation.  If the operation is
+costly, you do not have to repeat it again on each startup.  For
+example:
 
 @lisp
 @group
@@ -669,20 +682,25 @@ same information again on each startup.  For example:
 @end lisp
 
 @node Manual autoloads
-@section Setting up autoloads manually
+@subsection Setting up autoloads manually
+
+Packages often document how to set up its autoloads when it is being
+manually installed.  If it does, follow those instructions.
+Otherwise, you might want to set them up manually.
+
 @cindex autoloads for packages, setting up manually
 @cindex package autoloads, setting up manually
 
 @findex :commands
 @findex :autoload
-To autoload an interactive command, use the @code{:commands} keyword.
-When you use the @code{:commands} keyword, it creates autoloads for
-those commands (which defers loading of the module until those commands are
-used).  The @code{:commands} keyword takes either a symbol or a list
-of symbols as its argument.
-
-The @code{:autoload} keyword works like @code{:commands}, but is used
-to autoload non-interactive functions.  Here is an example:
+To autoload an interactive command, use the @code{:commands} keyword,
+which takes either a symbol or a list of symbols as its argument.  It
+creates autoloads for those commands (which defers loading of the
+module until those commands are used).
+
+The @code{:autoload} keyword takes the same arguments as
+@code{:commands}, but is used to autoload non-interactive functions.
+Here is an example:
 
 @lisp
 @group