From a17a6036dd4549514c7cecc7cdd93a571bf57ece Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Fri, 9 Dec 2022 04:15:32 +0100 Subject: [PATCH 1/4] Add conditional loading examples to use-package manual * doc/misc/use-package.texi (Conditional loading): Expand section with examples. Resolves https://github.com/jwiegley/use-package/issues/693 --- doc/misc/use-package.texi | 51 ++++++++++++++++++++++++++++++++++----- 1 file changed, 45 insertions(+), 6 deletions(-) diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi index 2e1747fa78d..5e8af41d5e6 100644 --- a/doc/misc/use-package.texi +++ b/doc/misc/use-package.texi @@ -394,22 +394,61 @@ 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 occurs before even @code{:ensure} or @code{:preface}, use @code{when} From 0b3116971afc5cb76cd2745bef1c12405d79528f Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Fri, 9 Dec 2022 05:12:03 +0100 Subject: [PATCH 2/4] Clarify :after keyword in use-package docstring * lisp/use-package/use-package-core.el (use-package): Clarify the effect of :after in docstring. Resolves https://github.com/jwiegley/use-package/issues/825 --- lisp/use-package/use-package-core.el | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/lisp/use-package/use-package-core.el b/lisp/use-package/use-package-core.el index 868a65803a4..1c61ac0ed39 100644 --- a/lisp/use-package/use-package-core.el +++ b/lisp/use-package/use-package-core.el @@ -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. From c417fe4df3b65442c2196c124a088af2db637d24 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Fri, 9 Dec 2022 05:12:51 +0100 Subject: [PATCH 3/4] ; Refer to the manual in use-package docstring * lisp/use-package/use-package-core.el (use-package): Refer to manual. --- lisp/use-package/use-package-core.el | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lisp/use-package/use-package-core.el b/lisp/use-package/use-package-core.el index 1c61ac0ed39..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]]...) From 5b640f0abd3f83449e8780ce8060eb723574986b Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Fri, 9 Dec 2022 06:27:33 +0100 Subject: [PATCH 4/4] Improve :delight keyword example in use-package manual * use-package.texi (Diminish, Delight): Clarify what happens if the pre-requisite packages are not installed. Change an example with performance issues to one without any. Resolves https://github.com/jwiegley/use-package/issues/835 --- doc/misc/use-package.texi | 46 ++++++++++++++++++++++++++++----------- 1 file changed, 33 insertions(+), 13 deletions(-) diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi index 5e8af41d5e6..4f0f8a26773 100644 --- a/doc/misc/use-package.texi +++ b/doc/misc/use-package.texi @@ -1243,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) @@ -1270,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}). @@ -1281,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. -@lisp -;; Don't show anything for rainbow-mode. -(use-package rainbow-mode - :delight) +For example, the following hides everything for the @samp{foo-mode} +minor mode in the @samp{foo} package: +@lisp +(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