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, 19 insertions, 11 deletions

diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi
index 21dfe1c2717..877aaf89a35 100644
--- a/doc/lispref/package.texi
+++ b/doc/lispref/package.texi
@@ -105,24 +105,32 @@ adds the package's content directory to @code{load-path}, and
 evaluates the autoload definitions in @file{@var{name}-autoloads.el}.
 
   Whenever Emacs starts up, it automatically calls the function
-@code{package-initialize} to load installed packages.  This is done
-after loading the init file and abbrev file (if any) and before
-running @code{after-init-hook} (@pxref{Startup Summary}).  Automatic
-package loading is disabled if the user option
-@code{package-enable-at-startup} is @code{nil}.
+@code{package-initialize} to make installed packages available to the
+current session.  This is done after loading the early init file, but
+before loading the regular init file (@pxref{Startup Summary}).
+Packages are not automatically made available if the user option
+@code{package-enable-at-startup} is set to @code{nil} in the early
+init file.
 
 @deffn Command package-initialize &optional no-activate
 This function initializes Emacs' internal record of which packages are
-installed, and loads them.  The user option @code{package-load-list}
-specifies which packages to load; by default, all installed packages
-are loaded.  If called during startup, this function also sets
+installed, and makes the packages available to the current session.
+The user option @code{package-load-list} specifies which packages to
+make available; by default, all installed packages are made available.
+If called during startup, this function also sets
 @code{package-enable-at-startup} to @code{nil}, to avoid accidentally
-loading the packages twice.  @xref{Package Installation,,, emacs, The
-GNU Emacs Manual}.
+evaluating package autoloads more than once.  @xref{Package
+Installation,,, emacs, The GNU Emacs Manual}.
 
 The optional argument @var{no-activate}, if non-@code{nil}, causes
 Emacs to update its record of installed packages without actually
-loading them; it is for internal use only.
+making them available; it is for internal use only.
+
+In most cases, you should not need to call @code{package-initialize},
+as this is done automatically during startup.  Simply make sure to put
+any code that should run before @code{package-initialize} in the early
+init file, and any code that should run after it in the primary init
+file (@xref{Init File,,, emacs, The GNU Emacs Manual}).
 @end deffn
 
 @node Simple Packages