From e3b57bedf521b814d32c4fe3698b5ffc726d8e22 Mon Sep 17 00:00:00 2001
From: Radon Rosborough <radon.neon@gmail.com>
Date: Fri, 2 Mar 2018 20:33:34 -0800
Subject: [PATCH] Documentation fixes for early init file changes

* doc/emacs/custom.texi (Early Init File): Add more details about
which variables must be set in the early init file rather than the
regular init file.  See [1].

* lisp/emacs-lisp/package.el (package-enable-at-startup): Update
docstring to note that packages are now made available before loading
the init file, rather than afterwards.  See [2].
(package-load-list): Refer to "making available" rather than "loading"
for packages.  See [3].

[1]: https://lists.nongnu.org/archive/html/bug-gnu-emacs/2018-02/msg00827.html
[2]: https://lists.gnu.org/archive/html/emacs-devel/2018-02/msg00632.html
[3]: https://lists.gnu.org/archive/html/emacs-devel/2018-02/msg00298.html
---
 doc/emacs/custom.texi      | 11 ++++++++---
 lisp/emacs-lisp/package.el | 27 ++++++++++++++++-----------
 2 files changed, 24 insertions(+), 14 deletions(-)

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 0905ae7bb1..ca842bd1e1 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -2606,9 +2606,14 @@ Early Init File
 earlier than the normal init file is processed.  Such customizations
 can be put in the early init file, @file{~/.emacs.d/early-init.el}.
 This file is loaded before the package system is initialized, so in it
-you can customize variables that affect the initialization process,
-such as @code{package-enable-at-startup} and @code{package-load-list}.
-@xref{Package Installation}.
+you can customize variables that affect the initialization process
+(i.e. @code{package-initialize}), such as
+@code{package-enable-at-startup}, @code{package-load-list}, and
+@code{package-user-dir}.  Note that variables like
+@code{package-archives} which only affect the installation of new
+packages, and not the process of making already-installed packages
+available, may be customized in the regular init file.  @xref{Package
+Installation}.
 
   For more information on the early init file, @pxref{Init File,,,
 elisp, The Emacs Lisp Reference Manual}.
diff --git a/lisp/emacs-lisp/package.el b/lisp/emacs-lisp/package.el
index 999e0d0752..6c307cc37c 100644
--- a/lisp/emacs-lisp/package.el
+++ b/lisp/emacs-lisp/package.el
@@ -161,29 +161,34 @@ package
 ;;; Customization options
 ;;;###autoload
 (defcustom package-enable-at-startup t
-  "Whether to activate installed packages when Emacs starts.
-If non-nil, packages are activated after reading the init file
-and before `after-init-hook'.  Activation is not done if
-`user-init-file' is nil (e.g. Emacs was started with \"-q\").
+  "Whether to make installed packages available when Emacs starts.
+If non-nil, packages are made available before reading the init
+file (but after reading the early init file).  This means that if
+you wish to set this variable, you must do so in the early init
+file.  Regardless of the value of this variable, packages are not
+made available if `user-init-file' is nil (e.g. Emacs was started
+with \"-q\").
 
 Even if the value is nil, you can type \\[package-initialize] to
-activate the package system at any time."
+make installed packages available at any time, or you can
+call (package-initialize) in your init-file."
   :type 'boolean
   :version "24.1")
 
 (defcustom package-load-list '(all)
-  "List of packages for `package-initialize' to load.
+  "List of packages for `package-initialize' to make available.
 Each element in this list should be a list (NAME VERSION), or the
-symbol `all'.  The symbol `all' says to load the latest installed
-versions of all packages not specified by other elements.
+symbol `all'.  The symbol `all' says to make available the latest
+installed versions of all packages not specified by other
+elements.
 
 For an element (NAME VERSION), NAME is a package name (a symbol).
 VERSION should be t, a string, or nil.
-If VERSION is t, the most recent version is activated.
-If VERSION is a string, only that version is ever loaded.
+If VERSION is t, the most recent version is made available.
+If VERSION is a string, only that version is ever made available.
  Any other version, even if newer, is silently ignored.
  Hence, the package is \"held\" at that version.
-If VERSION is nil, the package is not loaded (it is \"disabled\")."
+If VERSION is nil, the package is not made available (it is \"disabled\")."
   :type '(repeat (choice (const all)
                          (list :tag "Specific package"
                                (symbol :tag "Package name")
-- 
2.16.2

