GNU bug report logs - #72961
Possible documentation improvement: Clarification for package installation

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 72961 in the body.
You can then email your comments to 72961 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Krystian Samp <samp.krystian <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Possible documentation improvement: Clarification for package
 installation
Date: Mon, 2 Sep 2024 12:41:11 +0200

[Message part 1 (text/plain, inline)]

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

[Message part 2 (text/html, inline)]

Message #8 received at 72961 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Krystian Samp <samp.krystian <at> gmail.com>,
 Philip Kaludercic <philipk <at> posteo.net>
Cc: 72961 <at> debbugs.gnu.org
Subject: Re: bug#72961: Possible documentation improvement: Clarification for
 package installation
Date: Mon, 02 Sep 2024 15:03:42 +0300

> From: Krystian Samp <samp.krystian <at> 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.

Message #11 received at 72961 <at> debbugs.gnu.org (full text, mbox):

From: Philip Kaludercic <philipk <at> posteo.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Krystian Samp <samp.krystian <at> gmail.com>, 72961 <at> debbugs.gnu.org
Subject: Re: bug#72961: Possible documentation improvement: Clarification
 for package installation
Date: Mon, 02 Sep 2024 18:49:40 +0000

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Krystian Samp <samp.krystian <at> 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

Message #14 received at 72961 <at> debbugs.gnu.org (full text, mbox):

From: Krystian Samp <samp.krystian <at> gmail.com>
To: Philip Kaludercic <philipk <at> posteo.net>
Cc: 72961 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#72961: Possible documentation improvement: Clarification for
 package installation
Date: Wed, 4 Sep 2024 23:52:15 +0200

[Message part 1 (text/plain, inline)]

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

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

[Message part 2 (text/html, inline)]

[0001-Fix-package-install-documentation-on-initialization-.patch (application/octet-stream, attachment)]

Message #19 received at 72961-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Philip Kaludercic <philipk <at> posteo.net>
Cc: samp.krystian <at> gmail.com, 72961-done <at> debbugs.gnu.org
Subject: Re: bug#72961: Possible documentation improvement: Clarification
 for package installation
Date: Thu, 05 Sep 2024 09:24:54 +0300

> From: Philip Kaludercic <philipk <at> posteo.net>
> Cc: Krystian Samp <samp.krystian <at> gmail.com>,  72961 <at> 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.

Message #22 received at 72961 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Krystian Samp <samp.krystian <at> gmail.com>
Cc: 72961 <at> debbugs.gnu.org, philipk <at> posteo.net
Subject: Re: bug#72961: Possible documentation improvement: Clarification for
 package installation
Date: Thu, 05 Sep 2024 09:25:43 +0300

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

Message #25 received at 72961 <at> debbugs.gnu.org (full text, mbox):

From: Krystian Samp <samp.krystian <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 72961 <at> debbugs.gnu.org, philipk <at> posteo.net
Subject: Re: bug#72961: Possible documentation improvement: Clarification for
 package installation
Date: Thu, 5 Sep 2024 09:44:14 +0200

[Message part 1 (text/plain, inline)]

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 <at> gnu.org> wrote:

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

[Message part 2 (text/html, inline)]

Message #28 received at 72961 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Krystian Samp <samp.krystian <at> gmail.com>
Cc: 72961 <at> debbugs.gnu.org, philipk <at> posteo.net
Subject: Re: bug#72961: Possible documentation improvement: Clarification for
 package installation
Date: Thu, 05 Sep 2024 12:10:08 +0300

> From: Krystian Samp <samp.krystian <at> gmail.com>
> Date: Thu, 5 Sep 2024 09:44:14 +0200
> Cc: philipk <at> posteo.net, 72961 <at> 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.

Message #31 received at 72961 <at> debbugs.gnu.org (full text, mbox):

From: Krystian Samp <samp.krystian <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 72961 <at> debbugs.gnu.org, philipk <at> posteo.net
Subject: Re: bug#72961: Possible documentation improvement: Clarification for
 package installation
Date: Thu, 5 Sep 2024 11:23:12 +0200

[Message part 1 (text/plain, inline)]

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

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

> > From: Krystian Samp <samp.krystian <at> gmail.com>
> > Date: Thu, 5 Sep 2024 09:44:14 +0200
> > Cc: philipk <at> posteo.net, 72961 <at> 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.
>

[Message part 2 (text/html, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.