Merge from origin/emacs-29

5b640f0abd3 Improve :delight keyword example in use-package manual
c417fe4df3b ; Refer to the manual in use-package docstring
0b3116971af Clarify :after keyword in use-package docstring
a17a6036dd4 Add conditional loading examples to use-package manual

2 files changed, 84 insertions, 22 deletions

diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi
index 2e1747fa78d..4f0f8a26773 100644
--- a/doc/misc/use-package.texi
+++ b/doc/misc/use-package.texi
@@ -394,21 +394,60 @@ is provided as an alias for @code{:if}.  Finally, the @code{:unless}
 keyword is the inverse of @code{:if}, such that @w{@code{:unless foo}}
 means the same thing as @w{@code{:if (not foo)}}.
 
-For example, if you only want @samp{foo} in graphical Emacs sessions,
-you could use the following:
+For example, if you only want to load @samp{foo} in graphical Emacs
+sessions, you could use the following:
 
 @lisp
 (use-package foo
   :if (display-graphic-p))
 @end lisp
 
-Another common use case is to make it conditional on the operating
-system:
+@subheading Some common use cases
+
+Here are some common cases for conditional loading, and how to achieve
+them.
+
+@itemize
+
+@item Operating system
+
+This example loads a package only on GNU/Linux.  See the
+@code{system-type} docstring for other valid values.
 
 @lisp
-(use-package foo
-  :if (memq window-system '(mac ns)))
+:if (eq system-type 'gnu/linux)
+@end lisp
+
+@item Window system
+
+This example loads a package only on macOS and X.  See the
+@code{window-system} docstring for valid values.
+
+@lisp
+:if (memq window-system '(ns x))
+@end lisp
+
+@item Installed package
+
+This example loads a package only when the @samp{foo} package is
+installed.
+
+@lisp
+:if (package-installed-p 'foo)
+@end lisp
+
+@item Libraries in @code{load-path}
+
+This example loads a package only when @file{foo.el} is available in
+your @code{load-path} (for example, if you installed that file
+manually):
+
+@lisp
+:if (locate-library "foo.el")
 @end lisp
+@end itemize
+
+@subheading Making conditional loading affect @code{:preface} and @code{:ensure}
 
 @cindex conditional loading before @code{:preface} or @code{:ensure}
 If you need to conditionalize a use-package form so that the condition
@@ -1204,10 +1243,12 @@ install the corresponding package from @acronym{GNU ELPA}.
 @findex :diminish
 When diminish@footnote{The diminish package is installable from
 @acronym{GNU ELPA}.} is installed, you can use the @code{:diminish}
-keyword.  First, add the following declaration to the beginning of
-your init file.  The optional @w{@code{:ensure t}} makes sure the
-package is installed if it isn't already (@pxref{Installing
-packages}).
+keyword.  If diminish is not installed, the @code{:diminish} keyword
+does nothing.
+
+First, add the following declaration to the beginning of your init
+file.  The optional @w{@code{:ensure t}} makes sure the package is
+installed if it isn't already (@pxref{Installing packages}).
 
 @lisp
 (use-package diminish :ensure t)
@@ -1231,7 +1272,9 @@ package name with @samp{-mode} appended at the end:
 
 @findex :delight
 When delight@footnote{The @samp{delight} package is installable from
-GNU ELPA.} is installed, you can use the @code{:delight} keyword.
+GNU ELPA.} is installed, you can use the @code{:delight} keyword.  If
+delight is not installed, the @code{:delight} keyword does nothing.
+
 First, add the following declaration to the beginning of your init
 file.  The optional @w{@code{:ensure t}} makes sure the package is
 installed if it isn't already (@pxref{Installing packages}).
@@ -1242,25 +1285,41 @@ installed if it isn't already (@pxref{Installing packages}).
 
 The @code{:delight} keyword takes a minor mode symbol, a replacement
 string, or quoted mode line data (in which case the minor mode symbol
-is guessed to be the package name with @samp{-mode} appended at the
+is assumed to be the package name with @samp{-mode} appended at the
 end), both of these, or several lists of both.  @xref{Mode Line
 Data,,, elisp, GNU Emacs Lisp Reference Manual}.  If no arguments are
 provided, the default mode name is hidden completely.
 
+For example, the following hides everything for the @samp{foo-mode}
+minor mode in the @samp{foo} package:
+
 @lisp
-;; Don't show anything for rainbow-mode.
-(use-package rainbow-mode
+(use-package foo
   :delight)
+@end lisp
 
+If the mode name doesn't match the package name with @samp{-mode}
+appended, provide a symbol instead.  For example, the following hides
+@code{auto-revert-mode} from the mode line:
+
+@lisp
 ;; Don't show anything for auto-revert-mode, which doesn't match
 ;; its package name.
 (use-package autorevert
   :delight auto-revert-mode)
+@end lisp
 
-;; Remove the mode name for projectile-mode, but show the project name.
-(use-package projectile
-  :delight '(:eval (concat " " (projectile-project-name))))
+You can also run arbitrary Lisp code.  For example, to replace
+@samp{foo-mode} with the value of the current buffer:
 
+@lisp
+(use-package foo
+  :delight '(:eval buffer-file-name))
+@end lisp
+
+Here is an example of hiding several built-in minor modes:
+
+@lisp
 ;; Completely hide visual-line-mode and change auto-fill-mode to " AF".
 (use-package emacs
   :delight
diff --git a/lisp/use-package/use-package-core.el b/lisp/use-package/use-package-core.el
index 868a65803a4..ed6a65494fa 100644
--- a/lisp/use-package/use-package-core.el
+++ b/lisp/use-package/use-package-core.el
@@ -1609,8 +1609,8 @@ no keyword implies `:all'."
 (defmacro use-package (name &rest args)
   "Declare an Emacs package by specifying a group of configuration options.
 
-For full documentation, please see the README file that came with
-this file.  Usage:
+For the full documentation, see Info node `(use-package) top'.
+Usage:
 
   (use-package package-name
      [:keyword [option]]...)
@@ -1647,12 +1647,15 @@ this file.  Usage:
                  `:magic-fallback', or `:interpreter'.  This can be an integer,
                  to force loading after N seconds of idle time, if the package
                  has not already been loaded.
-:after           Delay the use-package declaration until after the named modules
-                 have loaded. Once load, it will be as though the use-package
-                 declaration (without `:after') had been seen at that moment.
 :demand          Prevent the automatic deferred loading introduced by constructs
                  such as `:bind' (see `:defer' for the complete list).
 
+:after           Delay the effect of the use-package declaration
+                 until after the named libraries have loaded.
+                 Before they have been loaded, no other keyword
+                 has any effect at all, and once they have been
+                 loaded it is as if `:after' was not specified.
+
 :if EXPR         Initialize and load only if EXPR evaluates to a non-nil value.
 :disabled        The package is ignored completely if this keyword is present.
 :defines         Declare certain variables to silence the byte-compiler.