From: Stefan Kangas <stefankangas@gmail.com>
Date: Fri, 9 Dec 2022 03:15:32 +0000 (+0100)
Subject: Add conditional loading examples to use-package manual
X-Git-Tag: emacs-29.0.90~1300
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=a17a6036dd4549514c7cecc7cdd93a571bf57ece;p=emacs.git

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
---

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}