From b5850ba3ae8758731d9420cf62c4fca6b765905c Mon Sep 17 00:00:00 2001
From: Philip Kaludercic <philipk@posteo.net>
Date: Fri, 4 Nov 2022 18:04:35 +0100
Subject: [PATCH] Document 'package-vc-selected-packages'

* doc/emacs/package.texi: Expand documentation and give example.
* etc/NEWS: Mention 'package-vc-selected-packages'.
* lisp/emacs-lisp/package-vc.el (package-vc--select-packages): Remove
function.
(package-vc-ensure-packages): Add function based on
'package-vc--select-packages'.
(package-vc-selected-packages): Call 'package-vc-ensure-packages' from
custom setter.
---
 doc/emacs/package.texi        | 23 +++++++++++++++++++++++
 etc/NEWS                      |  5 +++++
 lisp/emacs-lisp/package-vc.el | 22 ++++++++++++----------
 3 files changed, 40 insertions(+), 10 deletions(-)

diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index bd6d91a785d..51b86bb1471 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -558,6 +558,29 @@ regular package listing.  If you just wish to clone the source of a
 package, without adding it to the package list, use
 @code{package-vc-checkout}.
 
+@vindex package-vc-selected-packages
+@findex package-vc-ensure-packages
+  An alternative way to use @code{package-vc-install} is via the
+@code{package-vc-selected-packages} user option.  This is an alist of
+packages to install, where each key is a package name and the value is
+@code{nil}, indicating that any revision is to install, a string,
+indicating a specific revision or a package specification plist.  The
+side effect of setting the user option is to install the package, but
+the process can also be manually triggered using the function
+@code{package-vc-ensure-packages}.  Here is an example of how the user
+option:
+
+@example
+@group
+(setopt package-vc-selected-packages
+        '((modus-themes . "0f39eb3fd9") ;specific revision
+          (auctex . nil)                ;any revision
+          (foo                          ;a package specification
+           :url "https://git.sv.gnu.org/r/foo-mode.git"
+           :branch "trunk")))
+@end group
+@end example
+
 @findex package-report-bug
 @findex package-vc-prepare-patch
   With the source checkout, you might want to reproduce a bug against
diff --git a/etc/NEWS b/etc/NEWS
index d808e7ab90b..7550310935e 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1573,6 +1573,11 @@ packages checked out using 'package-vc-install'.
 This command helps you compose an email for sending bug reports to
 package maintainers.
 
++++
+*** New user option 'package-vc-selected-packages'
+By customising this user option you can specify specific packages to
+install.
+
 ** Emacs Sessions (Desktop)
 
 +++
diff --git a/lisp/emacs-lisp/package-vc.el b/lisp/emacs-lisp/package-vc.el
index 3eac55ba544..b18b5b1e483 100644
--- a/lisp/emacs-lisp/package-vc.el
+++ b/lisp/emacs-lisp/package-vc.el
@@ -103,13 +103,13 @@ symbol is used.  The value must be a member of
                            vc-handled-backends))
   :version "29.1")
 
-(defun package-vc--select-packages (sym val)
-  "Custom setter for `package-vc-selected-packages'.
-It will ensure that all the packages are installed as source
-packages.  Finally SYM is set to VAL."
-  (pcase-dolist (`(,(and (pred symbolp) name) . ,spec) val)
+(defun package-vc-ensure-packages ()
+  "Ensure source packages specified in `package-vc-selected-packages'."
+  (pcase-dolist (`(,(and (pred symbolp) name) . ,spec)
+                 package-vc-selected-packages)
     (let ((pkg-desc (cadr (assoc name package-alist #'string=))))
-      (unless (and name (package-installed-p name) (package-vc-p pkg-desc))
+      (unless (and name (package-installed-p name)
+                   (package-vc-p pkg-desc))
         (cond
          ((null spec)
           (package-vc-install name))
@@ -117,8 +117,7 @@ packages.  Finally SYM is set to VAL."
           (package-vc-install name nil spec))
          ((listp spec)
           (package-vc--archives-initialize)
-          (package-vc--unpack pkg-desc spec))))))
-  (custom-set-default sym val))
+          (package-vc--unpack pkg-desc spec)))))))
 
 ;;;###autoload
 (defcustom package-vc-selected-packages '()
@@ -134,7 +133,8 @@ is a symbol designating the package and SPEC is one of:
   specification.
 
 This user option differs from `package-selected-packages' in that
-it is meant to be specified manually."
+it is meant to be specified manually.  You can also use the
+function `package-vc-selected-packages' to apply the changes."
   :type '(alist :tag "List of ensured packages"
                 :key-type (symbol :tag "Package")
                 :value-type
@@ -145,7 +145,9 @@ it is meant to be specified manually."
                                          (:lisp-dir string)
                                          (:main-file string)
                                          (:vc-backend symbol)))))
-  :set #'package-vc--select-packages
+  :set (lambda (sym val)
+         (custom-set-default sym val)
+         (package-vc-ensure-packages))
   :version "29.1")
 
 (defvar package-vc--archive-spec-alist nil
-- 
2.39.5