Subject: Re: bug#72961: Possible documentation improvement: Clarification for package installation

From: Krystian Samp <[email-masked]>
Date: Wed, 4 Sep 2024 23:52:15 +0200

Also note that the preceding paragraph in 28.8 talks about the need to
'load' or 'require' libraries that you want to make available at startup.
So reading in the very next paragraph: "[...] and also writes the necessary
initialization code into your init files" sets the expectation that
package-install will write 'load' or 'require' into the init file.

On the other hand in another part of the manual (49.3): "Installed packages
are automatically made available by Emacs in all subsequent sessions". This
is simpler and more accurate imho, and doesn't suggest the init files are
altered in any way.

I'd propose to make a simple change in 28.8 that is consistent with 49.3:

Original:
"Note that installing a package using package-install (see Package
Installation) takes care of placing the package's Lisp files in a directory
where Emacs will find it, and also writes the necessary initialization code
into your init files, making the above manual customizations unnecessary"

Proposed:

“Note that installing a package using package-install (see Package
Installation) takes care of placing the package’s Lisp files in a directory
where Emacs will find it. Installed packages are automatically made
available by Emacs in all subsequent sessions, making the above manual
customizations unnecessary.”

Does this make sense?

Thanks,
Krystian

On Mon, 2 Sept 2024 at 20:49, Philip Kaludercic <[email-masked]> wrote:

> Eli Zaretskii <[email-masked]> writes:
>
> >> From: Krystian Samp <[email-masked]>
> >> Date: Mon, 2 Sep 2024 12:41:11 +0200
> >>
> >> I was reading the section on "Libraries of Lisp Code for Emacs"
> (section 28.8) in the Emacs manual, and I
> >> encountered a passage that seems a bit unclear. The text suggests that
> when using package-install, Emacs
> >> might automatically add initialization code to the init.el file, which
> doesn’t seem to match my experience.
> >>
> >> Specifically, the manual states: "Installing a package using
> package-install takes care of placing the package’s
> >> Lisp files in a directory where Emacs will find it, and also writes the
> necessary initialization code into your init
> >> files [...]"
> >>
> >> From my understanding, package-install does not modify init.el
> directly, which is how I interpret the
> >> documentation above. Instead, Emacs calls package-initialize which
> makes the installed packages available,
> >> automatically.
> >>
> >> I want to check if this is a valid concern / interpretation that
> warrants a documentation change. If so, I'll be
> >> happy to create a patch.
> >
> > Is package-quickstart.el considered "init file" or not?
> >
> > And I add Philip to this discussion, as he knows the package.el code
> > better than I do.
>
> I believe the documentation here is just outdated.  From NEWS.27:
>
>   ** Installed packages are now activated *before* loading the init file.
>   As a result of this change, it is no longer necessary to call
>   'package-initialize' in your init file.
>
>   Previously, a call to 'package-initialize' was automatically inserted
>   into the init file when Emacs was started.  This call can now safely
>   be removed.
>
> Otherwise it might also refer to the fact that user option
> `package-selected-packages' is saved, which by default will be stored in
> the default Emacs configuration file.
>
> --
>         Philip Kaludercic on peregrine
>