Documentation copyedits for 'package-install-upgrade-built-in' etc

* etc/NEWS: More details about the new option
'package-install-upgrade-built-in'.

* lisp/emacs-lisp/package.el (package-install-upgrade-built-in)
(package--active-built-in-p, package-install): Doc fixes.
(Bug#62720)

diff --git a/etc/NEWS b/etc/NEWS
index 0789fa49d75de9c3e201e5e532bfc7470646063f..0d31fc679dafd035a07ed789be3ea59e23fc0928 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1878,8 +1878,16 @@ install.
 
 ---
 *** New user option 'package-install-upgrade-built-in'.
-When enabled, 'package-install' can be used to install
-newer versions of built-in packages.
+When enabled, 'package-install' will include in the list of
+upgradeable packages those built-in packages (like Eglot and
+use-package, for example) for which a newer version is available in
+package archives, and will allow to install those newer versions.  By
+default, this is disabled; however, if 'package-install' is invoked
+with a prefix argument, it will act as if this new option were
+enabled.
+
+If you customize this option, we recommend to place its non-default
+setting in your early-init file.
 
 ** Emacs Sessions (Desktop)
 
@@ -3249,6 +3257,10 @@ based on data provided by language servers using the Language Server
 Protocol (LSP).  See the new Info manual "(eglot) Top" for more.  Also
 see "etc/EGLOT-NEWS".
 
+If you want to be able to use 'package-install' to upgrade Eglot to
+newer versions released on GNU ELPA, customize the new option
+'package-install-upgrade-built-in' to a non-nil value.
+
 +++
 ** use-package: Declarative package configuration.
 use-package is now shipped with Emacs.  It provides the 'use-package'
@@ -3256,6 +3268,10 @@ macro, which allows you to isolate package configuration in your init
 file in a way that is declarative, tidy, and performance-oriented.
 See the new Info manual "(use-package) Top" for more.
 
+If you want to be able to use 'package-install' to upgrade use-package
+to newer versions released on GNU ELPA, customize the new option
+'package-install-upgrade-built-in' to a non-nil value.
+
 ---
 ** New package 'wallpaper'.
 This package provides the command 'wallpaper-set', which sets the

diff --git a/lisp/emacs-lisp/package.el b/lisp/emacs-lisp/package.el
index c0cc7bebeb2c4c13617ae99c5b5bcc567f95ea75..ffa6272dd1f4c7d283bb0c731d73896be96cbed8 100644 (file)
--- a/lisp/emacs-lisp/package.el
+++ b/lisp/emacs-lisp/package.el
@@ -798,7 +798,7 @@ specifying the minimum acceptable version."
         (assq package package--builtins))))))
 
 (defun package--active-built-in-p (package)
-  "Return non-nil if PACKAGE if the built-in version is used.
+  "Return non-nil if the built-in version of PACKAGE is used.
 If the built-in version of PACKAGE is used and PACKAGE is
 also available for installation from an archive, it is an
 indication that PACKAGE was never upgraded to any newer
@@ -2200,7 +2200,7 @@ using `package-compute-transaction'."
 (defcustom package-install-upgrade-built-in nil
   "Non-nil means that built-in packages can be upgraded via a package archive.
 If disabled, then `package-install' will not suggest to replace a
-built-in package with a version from a package archive."
+built-in package with a (possibly newer) version from a package archive."
   :type 'boolean
   :version "29.1")
 
@@ -2220,9 +2220,9 @@ non-nil, install the package but do not add it to
 If PKG is a `package-desc' and it is already installed, don't try
 to install it but still mark it as selected.
 
-If the command is invoked with a prefix argument, the upgrading
-of built-in packages will be possible, as if
-`package-install-upgrade-built-in' had been enabled."
+If the command is invoked with a prefix argument, it will allow
+upgrading of built-in packages, as if `package-install-upgrade-built-in'
+had been enabled."
   (interactive
    (progn
      ;; Initialize the package system to get the list of package