Re: [PATCH] Fixing package-initialize, adding early init file

[Eli Zaretskii <eliz@gnu.org>]

> From: Radon Rosborough <radon.neon@gmail.com>
> Date: Sun, 28 Jan 2018 11:42:53 -0800
> Cc: emacs-devel <emacs-devel@gnu.org>
> 
> I've fixed all the problems noted by Stefan and Clément, and rebased
> onto the latest master. The revised patch is attached.

Thanks, I have a few minor comments below about the documentation
parts.

> --- a/doc/emacs/package.texi
> +++ b/doc/emacs/package.texi
> @@ -250,31 +250,18 @@ Package Installation
>  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 loaded by Emacs in
> +all subsequent sessions.

Is "automatically loaded" here accurate?  Wouldn't it be better to say
"it is available in all subsequent sessions, in that its functions and
variables will be automatically loaded when needed"?

> +the init file but after processing the early init file (@pxref{Early
> +Init File,,, elisp, The Emacs Lisp Reference Manual}).  As an

We cannot document the early init file, which is a user-level feature,
only in the ELisp manual.  it should be documented in the Emacs user
manual, where the "regular" init file is described.

> -@findex package-initialize

It looks like we are removing the index entry for package-initialize,
although it is a command?

> +@code{package-enable-at-startup} to @code{nil}.  You must do this in
> +the early init file, as the variable is read before loading the
> +regular init file.

There should be a cross-reference here to where the early init file is
described.

> +@cindex early init file
> +  Emacs also attempts to load a second init file, called the
> +  @dfn{early init file}, if it exists.  This is a file named

There's indentation here which is contrary to how we write stuff in
the manual sources.

> +  @file{early-init.el} in a subdirectory named @file{.emacs.d} in your
> +  home directory.

It's better and shorter to say

  @file{early-init.el} in your @file{~/.emacs.d} directory

Btw, is it only looked up in .emacs.d, or also in the directory where
.emacs is searched (which could be just the home directory)?

>                        The difference is that the early init file is
                         ^^^^^^^^^^^^^^^^^
Difference between what and what?

> +after loading the early init file, but before loading the regular init
> +file and abbrev file (if any) and before running
                                ^
You need a comma here.

> +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}).

This is for users, so it should be in the user manual, not in ELisp
manual.

> --- a/doc/misc/org.texi
> +++ b/doc/misc/org.texi
> @@ -890,9 +890,7 @@ Installation
>  been visited, i.e., where no Org built-in function have been loaded.
>  Otherwise autoload Org functions will mess up the installation.
>  
> -Then, to make sure your Org configuration is taken into account, initialize
> -the package system with @code{(package-initialize)} in your Emacs init file
> -before setting any Org option.  If you want to use Org's package repository,
> +If you want to use Org's package repository,
>  check out the @uref{http://orgmode.org/elpa.html, Org ELPA page}.

Why was this hunk necessary?

> +** Emacs can now be configured using an early init file.
> +The file is called 'early-init.el', in 'user-emacs-directory'.  It is
> +loaded very early in the startup process: before graphical elements
> +such as the tool bar are initialized, and before the package manager
> +is initialized.

Please add here a sentence regarding the purpose of this file (to
configure package.el initialization).

> +** Emacs now calls 'package-initialize' before loading the init file.
> +This is part of a change intended to eliminate the behavior of
> +package.el inserting a call to 'package-initialize' into the init
> +file, which was previously done when Emacs was started.  You only need
> +to make changes to your configuration if some of it needs to be run
> +before 'package-initialize' is called (for example, if you set
> +'package-load-list' or 'package-user-dir').  In that case, place the
> +configuration that needs to be run before 'package-initialize' into
> +the early init file.  Note that variables like 'package-archives' can
> +be set after 'package-initialize', so they can still be customized in
> +the regular init file.

The part starting with "You only need to make changes" sounds
unrelated to what precedes it.  You should probably insert there
something which explains that calling package-initialize before
loading the init file eliminates the need for such changes in most
cases?