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

[Krystian Samp <samp.krystian@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 3483 bytes --]

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 <philipk@posteo.net> wrote:

> Eli Zaretskii <eliz@gnu.org> writes:
>
> >> From: Krystian Samp <samp.krystian@gmail.com>
> >> 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
>

[-- Attachment #1.2: Type: text/html, Size: 4689 bytes --]

[-- Attachment #2: 0001-Fix-package-install-documentation-on-initialization-.patch --]
[-- Type: application/octet-stream, Size: 1152 bytes --]

From 0f6ad5c75a7b9e1ecf6bcfff1139c92f1ad380d5 Mon Sep 17 00:00:00 2001
From: Krystian Samp <samp.krystian@gmail.com>
Date: Wed, 4 Sep 2024 23:47:52 +0200
Subject: [PATCH] Fix package-install documentation on initialization behavior

---
 doc/emacs/building.texi | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi
index 1b079c2cef9..f5f1b536a40 100644
--- a/doc/emacs/building.texi
+++ b/doc/emacs/building.texi
@@ -1689,9 +1689,9 @@ command or function is invoked.  For example:
 
   Note that installing a package using @code{package-install}
 (@pxref{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.
+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.
 
 @node Lisp Eval
 @section Evaluating Emacs Lisp Expressions
-- 
2.39.3 (Apple Git-146)