Add early init file, stop package-initialize insertion

Discussion on emacs-devel leading up to this change (approximately 150
messages):

- https://lists.gnu.org/archive/html/emacs-devel/2017-08/msg00154.html
- https://lists.gnu.org/archive/html/emacs-devel/2017-08/msg00433.html
- https://lists.gnu.org/archive/html/emacs-devel/2017-09/msg00023.html
- https://lists.gnu.org/archive/html/emacs-devel/2017-09/msg00599.html
- https://lists.gnu.org/archive/html/emacs-devel/2017-10/msg00332.html

* lisp/startup.el (early-init-file): New variable.
(load-user-init-file): New function.
(command-line): Load the early init file using `load-user-init-file'.
Move the check for an invalid username to just before that, and move
the initialization of the package system to just after.  Load the
regular init file using `load-user-init-file'.
* lisp/emacs-lisp/package.el (package--ensure-init-file): Remove
definition, usage, and documentation.
(package--init-file-ensured): Remove definition and usage.

* src/lread.c (Vuser_init_file): Note change in semantics due to its
usage while loading the early init file.

* doc/emacs/custom.texi: Document early init file.
* doc/emacs/package.texi: Document changes to when package-initialize
is called.  Change terminology for package 'loading'.
* doc/lispref/os.texi: Document early init file.  Update startup
summary.
* doc/lispref/package.texi: Document changes to when
package-initialize is called, and advise against calling it in the
init file.  Change terminology for package 'loading'.
* doc/misc/org.texi: Don't recommend to call package-initialize in the
init file.

1 files changed, 40 insertions, 42 deletions

diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index bc6afb7966a..6c7493790d3 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -241,57 +241,55 @@ lower-priority archives will not be shown in the menu, if the same
 package is available from a higher-priority archive.  (This is
 controlled by the value of @code{package-menu-hide-low-priority}.)
 
-  Once a package is downloaded and installed, it is @dfn{loaded} into
-the current Emacs session.  Loading a package is not quite the same as
-loading a Lisp library (@pxref{Lisp Libraries}); loading a package
-adds its directory to @code{load-path} and loads its autoloads.  The
-effect of a package's autoloads varies from package to package.  Most
-packages just make some new commands available, while others have more
+  Once a package is downloaded and installed, it is made available to
+the current Emacs session.  Making a package available adds its
+directory to @code{load-path} and loads its autoloads.  The effect of
+a package's autoloads varies from package to package.  Most packages
+just make some new commands available, while others have more
 wide-ranging effects on the Emacs session.  For such information,
 consult the package's help buffer.
 
-  By default, Emacs also automatically loads all installed packages in
-subsequent Emacs sessions.  This happens at startup, after processing
-the init file (@pxref{Init File}).  As an exception, Emacs does not
-load packages at startup if invoked with the @samp{-q} or
-@samp{--no-init-file} options (@pxref{Initial Options}).
+  After a package is installed, it is automatically made available by
+Emacs in all subsequent sessions.  This happens at startup, before
+processing the init file but after processing the early init file
+(@pxref{Early Init File,,, elisp, The Emacs Lisp Reference Manual}).
+As an exception, Emacs does not make packages available at startup if
+invoked with the @samp{-q} or @samp{--no-init-file} options
+(@pxref{Initial Options}).
 
 @vindex package-enable-at-startup
-  To disable automatic package loading, change the variable
-@code{package-enable-at-startup} to @code{nil}.
+  To keep Emacs from automatically making packages available at
+startup, change the variable @code{package-enable-at-startup} to
+@code{nil}.  You must do this in the early init file (@pxref{Early
+Init File,,, elisp, The Emacs Lisp Reference Manual}), as the variable
+is read before loading the regular init file.  Currently this variable
+cannot be set via Customize.
 
 @findex package-initialize
-  The reason automatic package loading occurs after loading the init
-file is that user options only receive their customized values after
-loading the init file, including user options which affect the
-packaging system.  In some circumstances, you may want to load
-packages explicitly in your init file (usually because some other code
-in your init file depends on a package).  In that case, your init file
-should call the function @code{package-initialize}.  It is up to you
-to ensure that relevant user options, such as @code{package-load-list}
-(see below), are set up prior to the @code{package-initialize} call.
-This will automatically set @code{package-enable-at-startup} to @code{nil}, to
-avoid loading the packages again after processing the init file.
-Alternatively, you may choose to completely inhibit package loading at
-startup, and invoke the command @kbd{M-x package-initialize} to load
-your packages manually.
+  If you have set @code{package-enable-at-startup} to @code{nil}, you
+can still make packages available either during or after startup.  To
+make installed packages available during startup, call the function
+@code{package-initialize} in your init file.  To make installed
+packages available after startup, invoke the command @kbd{M-x
+package-initialize}.
 
 @vindex package-load-list
-  For finer control over package loading, you can use the variable
-@code{package-load-list}.  Its value should be a list.  A list element
-of the form @code{(@var{name} @var{version})} tells Emacs to load
-version @var{version} of the package named @var{name}.  Here,
-@var{version} should be a version string (corresponding to a specific
-version of the package), or @code{t} (which means to load any
-installed version), or @code{nil} (which means no version; this
-disables the package, preventing it from being loaded).  A list
-element can also be the symbol @code{all}, which means to load the
-latest installed version of any package not named by the other list
-elements.  The default value is just @code{'(all)}.
-
-  For example, if you set @code{package-load-list} to @code{'((muse
-"3.20") all)}, then Emacs only loads version 3.20 of the @samp{muse}
-package, plus any installed version of packages other than
+  For finer control over which packages are made available at startup,
+you can use the variable @code{package-load-list}.  Its value should
+be a list.  A list element of the form @w{@code{(@var{name}
+@var{version})}} tells Emacs to make available version @var{version} of
+the package named @var{name}.  Here, @var{version} should be a version
+string (corresponding to a specific version of the package), or
+@code{t} (which means to make available any installed version), or
+@code{nil} (which means no version; this disables the package,
+preventing it from being made available).  A list element can also be
+the symbol @code{all}, which means to make available the latest
+installed version of any package not named by the other list elements.
+The default value is just @code{'(all)}.
+
+  For example, if you set @code{package-load-list} to @w{@code{'((muse
+"3.20") all)}}, then Emacs only makes available version 3.20 of the
+@samp{muse} package, plus any installed version of packages other than
 @samp{muse}.  Any other version of @samp{muse} that happens to be
 installed will be ignored.  The @samp{muse} package will be listed in
 the package menu with the @samp{held} status.