bug#63800: 30.0.50; [ELPA] Inaccurate installation instructions for built-in packages

bug#63800: 30.0.50; [ELPA] Inaccurate installation instructions for built-in packages

[Ihor Radchenko]

Hi,

All the Emacs packages distributed via ELPA share the same installation
instruction:

    To install this package, run in Emacs:
    
    M-x package-install RET <package-name> RET

However, this command will fail for built-in packages. This is
particularly a problem for older (<29) Emacs versions.

May the instruction be corrected?

Original discussion is for Org, but the same will apply for other
packages distributed with Emacs. https://orgmode.org/list/878rdbwlf3.fsf@localhost

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#63800: 30.0.50; [ELPA] Inaccurate installation instructions for built-in packages

[Philip Kaludercic]

Ihor Radchenko <yantar92@posteo.net> writes:

> Hi,
>
> All the Emacs packages distributed via ELPA share the same installation
> instruction:
>
>     To install this package, run in Emacs:
>     
>     M-x package-install RET <package-name> RET
>
> However, this command will fail for built-in packages. This is
> particularly a problem for older (<29) Emacs versions.

You probably want to set `package-install-upgrade-built-in' to non-nil,
or use the package menu to install packages.

> May the instruction be corrected?
>
> Original discussion is for Org, but the same will apply for other
> packages distributed with
> Emacs. https://orgmode.org/list/878rdbwlf3.fsf@localhost

bug#63800: 30.0.50; [ELPA] Inaccurate installation instructions for built-in packages

[Ihor Radchenko]

Philip Kaludercic <philipk@posteo.net> writes:

>> However, this command will fail for built-in packages. This is
>> particularly a problem for older (<29) Emacs versions.
>
> You probably want to set `package-install-upgrade-built-in' to non-nil,
> or use the package menu to install packages.

Sure. But only in Emacs >=29 and it is not mentioned on the ELPA page.
For Emacs <29 ELPA instruction simply does not work - attempting to
follow it will just produce unhelpful message that package is already
installed.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#63800: 30.0.50; [ELPA] Inaccurate installation instructions for built-in packages

[Philip Kaludercic]

Ihor Radchenko <yantar92@posteo.net> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>>> However, this command will fail for built-in packages. This is
>>> particularly a problem for older (<29) Emacs versions.
>>
>> You probably want to set `package-install-upgrade-built-in' to non-nil,
>> or use the package menu to install packages.
>
> Sure. But only in Emacs >=29 and it is not mentioned on the ELPA page.

I am not a fan of the option to begin with, and wouldn't want to
advertise it.  The official way of switching from built-in packages to
ELPA should still be to use the package menu.

> For Emacs <29 ELPA instruction simply does not work - attempting to
> follow it will just produce unhelpful message that package is already
> installed.

So what would you suggest changing?

bug#63800: 30.0.50; [ELPA] Inaccurate installation instructions for built-in packages

[Ihor Radchenko]

Philip Kaludercic <philipk@posteo.net> writes:

>>> You probably want to set `package-install-upgrade-built-in' to non-nil,
>>> or use the package menu to install packages.
>>
>> Sure. But only in Emacs >=29 and it is not mentioned on the ELPA page.
>
> I am not a fan of the option to begin with, and wouldn't want to
> advertise it.  The official way of switching from built-in packages to
> ELPA should still be to use the package menu.

I will not argue about this. This bug report merely raises the issue
with current installation instructions. You are in a better position to
recommend one or another way to install/upgrade core packages from ELPA.

>> For Emacs <29 ELPA instruction simply does not work - attempting to
>> follow it will just produce unhelpful message that package is already
>> installed.
>
> So what would you suggest changing?

I suggest changing

    To install this package, run in Emacs:
    
    M-x package-install RET <package-name> RET

to something like

   This package is a part of Emacs since Emacs XX.X.

   To install the package in Emacs <XX.X, run:

   M-x package-install RET <package-name

   To update the built-in package version in Emacs >=XX.X to ELPA version:
      
   <instructions to install the package that actually work>

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#63800: 30.0.50; [ELPA] Inaccurate installation instructions for built-in packages

[Dmitry Gutov]

On 31/05/2023 09:59, Ihor Radchenko wrote:
> Philip Kaludercic<philipk@posteo.net>  writes:
> 
>>> However, this command will fail for built-in packages. This is
>>> particularly a problem for older (<29) Emacs versions.
>> You probably want to set `package-install-upgrade-built-in' to non-nil,
>> or use the package menu to install packages.
> Sure. But only in Emacs >=29 and it is not mentioned on the ELPA page.
> For Emacs <29 ELPA instruction simply does not work - attempting to
> follow it will just produce unhelpful message that package is already
> installed.

Is that a problem with the command or with the expectations?

When Org is built-in, it *is* already installed, isn't it?

You will also see the same message if you try to use 'M-x 
package-install' as a means to upgrade any other already-installed 
package, whether it is built-in or not.

bug#63800: 30.0.50; [ELPA] Inaccurate installation instructions for built-in packages

[Ihor Radchenko]

Dmitry Gutov <dmitry@gutov.dev> writes:

>> Sure. But only in Emacs >=29 and it is not mentioned on the ELPA page.
>> For Emacs <29 ELPA instruction simply does not work - attempting to
>> follow it will just produce unhelpful message that package is already
>> installed.
>
> Is that a problem with the command or with the expectations?
>
> When Org is built-in, it *is* already installed, isn't it?

I have no problem with the command. I have problem with _ELPA page_
mentioning this command for built-in packages.

Org is always built-in. If a user goes to ELPA page, she most likely
wants to upgrade Org. And ELPA instructions do not tell how to do it.
Basically, what ELPA page for Org tells will not work for any common
Emacs version in the wild (and will not work for older Emacses that did
not ship with Org as well - they are not supported).

If you look into my other email, I suggested indicating on the ELPA
page when a package is built-in and also add instructions how to upgrade
it. That makes more sense _for ELPA page_.

This bug is not about `package-install'. This bug is about ELPA web page.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#63800: 30.0.50; [ELPA] Inaccurate installation instructions for built-in packages

[Dmitry Gutov]

On 15/06/2023 09:04, Ihor Radchenko wrote:
> I have no problem with the command. I have problem with_ELPA page_
> mentioning this command for built-in packages.

Cool.

> If you look into my other email, I suggested indicating on the ELPA
> page when a package is built-in and also add instructions how to upgrade
> it. That makes more sense_for ELPA page_.

Not a bad idea, though it will also require adding some metadata on when 
the package was added to Emacs.

Perhaps a simpler alternative is to stop referencing 'package-install' 
and instead point uses to 'M-x list-packages'.

bug#63800: 30.0.50; [ELPA] Inaccurate installation instructions for built-in packages

[Philip Kaludercic]

Dmitry Gutov <dmitry@gutov.dev> writes:

> On 15/06/2023 09:04, Ihor Radchenko wrote:
>> I have no problem with the command. I have problem with_ELPA page_
>> mentioning this command for built-in packages.
>
> Cool.
>
>> If you look into my other email, I suggested indicating on the ELPA
>> page when a package is built-in and also add instructions how to upgrade
>> it. That makes more sense_for ELPA page_.
>
> Not a bad idea, though it will also require adding some metadata on
> when the package was added to Emacs.
>
> Perhaps a simpler alternative is to stop referencing 'package-install'
> and instead point uses to 'M-x list-packages'.

I think this would be better as well.  A lot of users don't even know
what version they use, so we should have to describe how to find that
out as well.  And if that isn't enough, we would also have to explain
what core, built-in and ELPA packages are, and how they interact.  Not
worth it, IMO.

bug#63800: 30.0.50; [ELPA] Inaccurate installation instructions for built-in packages

[Ihor Radchenko]

Philip Kaludercic <philipk@posteo.net> writes:

>> Perhaps a simpler alternative is to stop referencing 'package-install'
>> and instead point uses to 'M-x list-packages'.
>
> I think this would be better as well.  A lot of users don't even know
> what version they use, so we should have to describe how to find that
> out as well.

I hope that we do not have a situation on ELPA where a package cannot be
installed at all on older Emacs.

> ... And if that isn't enough, we would also have to explain
> what core, built-in and ELPA packages are, and how they interact.  Not
> worth it, IMO.

I think it is still worth mentioning that some packages may already be
shipped with Emacs. I do not feel too strongly about this though.

I am OK with changing the installation/upgrade instructions to M-x
list-packages for built-in packages.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#63800: 30.0.50; [ELPA] Inaccurate installation instructions for built-in packages

[Ihor Radchenko]

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

Dmitry Gutov <dmitry@gutov.dev> writes:

> Perhaps a simpler alternative is to stop referencing 'package-install' 
> and instead point uses to 'M-x list-packages'.

See the attached patch.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Suggest-package-install-to-install-packages.patch --]
[-- Type: text/x-patch, Size: 1363 bytes --]

From e3e7eae381c0756b54935121c3f0a641685af666 Mon Sep 17 00:00:00 2001
Message-ID: <e3e7eae381c0756b54935121c3f0a641685af666.1688903858.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Sun, 9 Jul 2023 14:56:22 +0300
Subject: [PATCH] Suggest `package-install' to install packages

* elpa-admin.el (elpaa--html-make-pkg): Instruct using `list-packages'
to install packages instead of `package-install'.

See bug#63800.
---
 elpa-admin.el | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/elpa-admin.el b/elpa-admin.el
index 7ee385d0a..2b5c9b3dd 100644
--- a/elpa-admin.el
+++ b/elpa-admin.el
@@ -1879,7 +1879,8 @@ (defun elpaa--html-make-pkg (pkg pkg-spec files srcdir plain-readme)
       (elpaa--html-insert-docs pkg-spec)
       (insert "</dl>")
       (insert (format "<p>To install this package, run in Emacs:</p>
-                       <pre>M-x <span class=\"kw\">package-install</span> RET <span class=\"kw\">%s</span> RET</pre>"
+                       <pre>M-x <span class=\"kw\">list-packages</span> RET</pre>
+                       <p>Then, find <span class=\"kw\">%s</span> in the list, click on the link, and click <span class=\"kw\">Install</span>.</p>"
                       name))
       (let* ((readme-content (elpaa--get-README pkg-spec srcdir))
              (readme-text plain-readme)
-- 
2.41.0


[-- Attachment #3: Type: text/plain, Size: 224 bytes --]


-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#63800: 30.0.50; [ELPA] Inaccurate installation instructions for built-in packages

[Dmitry Gutov]

On 09/07/2023 14:59, Ihor Radchenko wrote:
> -                       <pre>M-x <span class=\"kw\">package-install</span> RET <span class=\"kw\">%s</span> RET</pre>"
> +                       <pre>M-x <span class=\"kw\">list-packages</span> RET</pre>
> +                       <p>Then, find <span class=\"kw\">%s</span> in the list, click on the link, and click <span class=\"kw\">Install</span>.</p>"

Looks like an improvement, thank you.

bug#63800: 30.0.50; [ELPA] Inaccurate installation instructions for built-in packages

[Philip Kaludercic]

Ihor Radchenko <yantar92@posteo.net> writes:

> Dmitry Gutov <dmitry@gutov.dev> writes:
>
>> Perhaps a simpler alternative is to stop referencing 'package-install' 
>> and instead point uses to 'M-x list-packages'.
>
> See the attached patch.

Looks good, just one nitpick:

> From e3e7eae381c0756b54935121c3f0a641685af666 Mon Sep 17 00:00:00 2001
> Message-ID: <e3e7eae381c0756b54935121c3f0a641685af666.1688903858.git.yantar92@posteo.net>
> From: Ihor Radchenko <yantar92@posteo.net>
> Date: Sun, 9 Jul 2023 14:56:22 +0300
> Subject: [PATCH] Suggest `package-install' to install packages
>
> * elpa-admin.el (elpaa--html-make-pkg): Instruct using `list-packages'
> to install packages instead of `package-install'.
>
> See bug#63800.
> ---
>  elpa-admin.el | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/elpa-admin.el b/elpa-admin.el
> index 7ee385d0a..2b5c9b3dd 100644
> --- a/elpa-admin.el
> +++ b/elpa-admin.el
> @@ -1879,7 +1879,8 @@ (defun elpaa--html-make-pkg (pkg pkg-spec files srcdir plain-readme)
>        (elpaa--html-insert-docs pkg-spec)
>        (insert "</dl>")
>        (insert (format "<p>To install this package, run in Emacs:</p>
> -                       <pre>M-x <span class=\"kw\">package-install</span> RET <span class=\"kw\">%s</span> RET</pre>"
> +                       <pre>M-x <span class=\"kw\">list-packages</span> RET</pre>
> +                       <p>Then, find <span class=\"kw\">%s</span> in the list, click on the link, and click <span class=\"kw\">Install</span>.</p>"

Are you sure that "Install" should have the class kw (I assume keyword)?

>                        name))
>        (let* ((readme-content (elpaa--get-README pkg-spec srcdir))
>               (readme-text plain-readme)
> -- 
> 2.41.0

Other than that, can you push the commit or should I do it?

bug#63800: 30.0.50; [ELPA] Inaccurate installation instructions for built-in packages

[Ihor Radchenko]

Philip Kaludercic <philipk@posteo.net> writes:

>> +                       <pre>M-x <span class=\"kw\">list-packages</span> RET</pre>
>> +                       <p>Then, find <span class=\"kw\">%s</span> in the list, click on the link, and click <span class=\"kw\">Install</span>.</p>"
>
> Are you sure that "Install" should have the class kw (I assume keyword)?

I am not sure, but I thought that it should be highlighted. "Install" is
displayed as a button in Emacs.

An alternative could be <pre>Install</pre> - it will look kinda similar
to how Emacs displays it.

Also, note that it will change how all the packages are displayed, not
just core packages.

> Other than that, can you push the commit or should I do it?

I can try. Never pushed to parts of Emacs project other than Org mode.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#63800: 30.0.50; [ELPA] Inaccurate installation instructions for built-in packages

[Philip Kaludercic]

Ihor Radchenko <yantar92@posteo.net> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>>> + <pre>M-x <span class=\"kw\">list-packages</span> RET</pre>
>>> + <p>Then, find <span class=\"kw\">%s</span> in the list, click on
>>> the link, and click <span class=\"kw\">Install</span>.</p>"
>>
>> Are you sure that "Install" should have the class kw (I assume keyword)?
>
> I am not sure, but I thought that it should be highlighted. "Install" is
> displayed as a button in Emacs.
>
> An alternative could be <pre>Install</pre> - it will look kinda similar
> to how Emacs displays it.

I think that would be better.

> Also, note that it will change how all the packages are displayed, not
> just core packages.

Of course.

>> Other than that, can you push the commit or should I do it?
>
> I can try. Never pushed to parts of Emacs project other than Org mode.

I believe you should have access.

bug#63800: 30.0.50; [ELPA] Inaccurate installation instructions for built-in packages

[Ihor Radchenko]

Philip Kaludercic <philipk@posteo.net> writes:

>> An alternative could be <pre>Install</pre> - it will look kinda similar
>> to how Emacs displays it.
>
> I think that would be better.

Applied, onto elpa-admin, with the suggested change.
I also moved the bug reference to commit summary.
https://git.savannah.gnu.org/cgit/emacs/elpa.git/commit/?h=elpa-admin&id=1d766451f81b54169215ffce65a3facf67192a99

>> I can try. Never pushed to parts of Emacs project other than Org mode.
>
> I believe you should have access.

Hope I did not break anything :)

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>