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

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

[Krystian Samp]

[-- Attachment #1: Type: text/plain, Size: 1006 bytes --]

Hello,

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.

Looking forward to your thoughts.
Krystian

[-- Attachment #2: Type: text/html, Size: 1174 bytes --]

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

[Eli Zaretskii]

> 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.

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

[Philip Kaludercic]

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

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

[Krystian Samp]

[-- 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)

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

[Eli Zaretskii]

> From: Krystian Samp <samp.krystian@gmail.com>
> Date: Wed, 4 Sep 2024 23:52:15 +0200
> Cc: Eli Zaretskii <eliz@gnu.org>, 72961@debbugs.gnu.org
> 
> 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.”

Thanks, I modified the text slightly differently.

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

[Krystian Samp]

[-- Attachment #1: Type: text/plain, Size: 1539 bytes --]

Thanks,

imho it'd be also useful to add there that Emacs will make the installed
packages available automatically at startup. Now it reads that Emacs will
add them to `load-path` but I wouldn't infer from this that Emacs will also
make these packages available. And right after that we say that "... making
the above manual customizations unnecessary for such packages" which
specifically refers to loading, not only adding to `load-path`. Just two
cents,

K

On Thu, 5 Sept 2024 at 08:25, Eli Zaretskii <eliz@gnu.org> wrote:

> > From: Krystian Samp <samp.krystian@gmail.com>
> > Date: Wed, 4 Sep 2024 23:52:15 +0200
> > Cc: Eli Zaretskii <eliz@gnu.org>, 72961@debbugs.gnu.org
> >
> > 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.”
>
> Thanks, I modified the text slightly differently.
>

[-- Attachment #2: Type: text/html, Size: 2332 bytes --]

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

[Eli Zaretskii]

> From: Krystian Samp <samp.krystian@gmail.com>
> Date: Thu, 5 Sep 2024 09:44:14 +0200
> Cc: philipk@posteo.net, 72961@debbugs.gnu.org
> 
> Thanks,
> 
> imho it'd be also useful to add there that Emacs will make the installed packages available automatically at
> startup. Now it reads that Emacs will add them to `load-path` but I wouldn't infer from this that Emacs will also
> make these packages available. And right after that we say that "... making the above manual customizations
> unnecessary for such packages" which specifically refers to loading, not only adding to `load-path`. Just two
> cents,

All of this is already described in the node "Package Installation",
to which this node points.  Cross-references in the manual are there
for a reason: interested readers are expected to follow them and to
read what the referenced nodes say.  We don't have the same
information in more than one place in the manual because that would
make it a maintenance burden: all of those places have to be found and
updated when something changes.  Our conventions are to describe each
feature in full in a single place, and then have cross-references to
that one place in other related places.

So I decided not to expand on this more in the sections which is only
tangentially related to package installation.  This text is there so
as to avoid creating an impression that what this node describes must
be done for packages installed via package.el.  It doesn't (and should
not) pretend to describe installation via package.el.

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

[Krystian Samp]

[-- Attachment #1: Type: text/plain, Size: 1729 bytes --]

This makes sense, thanks for taking the time to explain this in detail.

On Thu, 5 Sept 2024 at 11:10, Eli Zaretskii <eliz@gnu.org> wrote:

> > From: Krystian Samp <samp.krystian@gmail.com>
> > Date: Thu, 5 Sep 2024 09:44:14 +0200
> > Cc: philipk@posteo.net, 72961@debbugs.gnu.org
> >
> > Thanks,
> >
> > imho it'd be also useful to add there that Emacs will make the installed
> packages available automatically at
> > startup. Now it reads that Emacs will add them to `load-path` but I
> wouldn't infer from this that Emacs will also
> > make these packages available. And right after that we say that "...
> making the above manual customizations
> > unnecessary for such packages" which specifically refers to loading, not
> only adding to `load-path`. Just two
> > cents,
>
> All of this is already described in the node "Package Installation",
> to which this node points.  Cross-references in the manual are there
> for a reason: interested readers are expected to follow them and to
> read what the referenced nodes say.  We don't have the same
> information in more than one place in the manual because that would
> make it a maintenance burden: all of those places have to be found and
> updated when something changes.  Our conventions are to describe each
> feature in full in a single place, and then have cross-references to
> that one place in other related places.
>
> So I decided not to expand on this more in the sections which is only
> tangentially related to package installation.  This text is there so
> as to avoid creating an impression that what this node describes must
> be done for packages installed via package.el.  It doesn't (and should
> not) pretend to describe installation via package.el.
>

[-- Attachment #2: Type: text/html, Size: 2332 bytes --]

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

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: Krystian Samp <samp.krystian@gmail.com>,  72961@debbugs.gnu.org
> Date: Mon, 02 Sep 2024 18:49:40 +0000
> 
> 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. 

Thanks, I've updated the text accordingly on the emacs-30 release
branch, and I'm therefore closing this bug.