bug#17403: 24.4.50; package-alist doc-string error

bug#17403: 24.4.50; package-alist doc-string error

[Richard Kim]

I believe the doc-string for package-alist is incorrect.
Each element is (PKG DESCS) rather than (PKG . DESCS), i.e.,
each item is (list PKG DESCS) rather than (cons PKG DESCS).
To fix this, the patch shown below can be applied.

My assertion is confirmed by the following code from package.el:

    (defun package-process-define-package (exp origin)
       ...
            ;; If there's no old package, just add this to `package-alist'.
            (push (list name new-pkg-desc) package-alist)
       ...
       )

where the new item added to package-alist is a list of two items rather
than a cons of two items.

The git diff of the propose change follows next.

Changes from HEAD to working tree
1 file changed, 1 insertion(+), 1 deletion(-)
 lisp/emacs-lisp/package.el |    2 +-

	Modified   lisp/emacs-lisp/package.el
diff --git a/lisp/emacs-lisp/package.el b/lisp/emacs-lisp/package.el
index 7be0354..cbd4671 100644
--- a/lisp/emacs-lisp/package.el
+++ b/lisp/emacs-lisp/package.el
@@ -409,7 +409,7 @@ name (a symbol) and DESC is a `package--bi-desc' structure.")
 
 (defvar package-alist nil
   "Alist of all packages available for activation.
-Each element has the form (PKG . DESCS), where PKG is a package
+Each element has the form (PKG DESCS), where PKG is a package
 name (a symbol) and DESCS is a non-empty list of `package-desc' structure,
 sorted by decreasing versions.
 

bug#17403: 24.4.50; package-alist doc-string error

[Stefan Kangas]

Richard Kim <emacs18@gmail.com> writes:

> I believe the doc-string for package-alist is incorrect.
> Each element is (PKG DESCS) rather than (PKG . DESCS), i.e.,
> each item is (list PKG DESCS) rather than (cons PKG DESCS).
> To fix this, the patch shown below can be applied.

You are correct.  There is indeed a difference between what the
documentation says and what the code does.  According to the code,
package-alist is *not* an alist, but a list of lists. (This goes back
to at least 2013 AFAICT.)

Yet it has the suffix "-alist".

I see three ways to rectify this:

    1) Change the code so that it is an alist.

    2) Update the documentation, rename the variable to
       something like package-list.

    3) Update the documentation, ignore that it's not an alist.

Out of these alternatives, I think the first is by far the least
attractive.  It has already been changed to not be an alist once.  But
which is the better of alternatives 2 and 3?

It would be good to hear what others think.

Thanks,
Stefan Kangas

bug#17403: 24.4.50; package-alist doc-string error

[Noam Postavsky]

Stefan Kangas <stefan@marxist.se> writes:

> Richard Kim <emacs18@gmail.com> writes:
>
>> I believe the doc-string for package-alist is incorrect.
>> Each element is (PKG DESCS) rather than (PKG . DESCS), i.e.,
>> each item is (list PKG DESCS) rather than (cons PKG DESCS).
>> To fix this, the patch shown below can be applied.
>
> You are correct.  There is indeed a difference between what the
> documentation says and what the code does.  According to the code,
> package-alist is *not* an alist, but a list of lists. (This goes back
> to at least 2013 AFAICT.)
>
> Yet it has the suffix "-alist".

The only structural requirement for "alist"ness is to be a list of
conses.  As long as none of the lists are empty, a list of lists is (or
can be viewed as) an alist.  I don't think there is a bug here, just a
misunderstanding of dot notation.

>> My assertion is confirmed by the following code from package.el:
>> 
>>     (defun package-process-define-package (exp origin)
>>        ...
>>             ;; If there's no old package, just add this to `package-alist'.
>>             (push (list name new-pkg-desc) package-alist)

Note that this is equivalent to this:

    (push (cons name (list new-pkg-desc)) package-alist)

bug#17403: 24.4.50; package-alist doc-string error

[Stefan Kangas]

Noam Postavsky <npostavs@gmail.com> writes:

> The only structural requirement for "alist"ness is to be a list of
> conses.  As long as none of the lists are empty, a list of lists is (or
> can be viewed as) an alist.

OK, interesting.

>  I don't think there is a bug here, just a
> misunderstanding of dot notation.

Hmm, I had to think a minute about this but you're right, of course.
Not sure what confused me.

Is it a problem that this is documented as "(PKG . DESCS)" when the
printed representation is "(PKG DESCS)"?

If not, we can close this as notabug.

Thanks,
Stefan Kangas

PS. Took the original reporter off Cc because it bounced the first time.

bug#17403: 24.4.50; package-alist doc-string error

[Michael Heerdegen]

Noam Postavsky <npostavs@gmail.com> writes:

> misunderstanding of dot notation.

Yes probably, but

"Each element has the form (PKG . DESCS), where PKG is a package name (a
symbol) and DESCS is a non-empty list of `package-desc' structure"
                                                                 ^
Isn't there an "s" missing (plural)?

Michael.

bug#17403: 24.4.50; package-alist doc-string error

[Basil L. Contovounesios]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> "Each element has the form (PKG . DESCS), where PKG is a package name (a
> symbol) and DESCS is a non-empty list of `package-desc' structure"
>                                                                  ^
> Isn't there an "s" missing (plural)?

Indeed.  Now fixed in emacs-26:

Fix typo in package-alist docstring
76538d09b7 2019-07-17 15:07:16 +0100
https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=76538d09b711c9f0fb2a48be70f12e776c4ecbb5

Thanks,

-- 
Basil

bug#17403: 24.4.50; package-alist doc-string error

[Basil L. Contovounesios]

tags 17403 notabug
close 17403
quit

Stefan Kangas <stefan@marxist.se> writes:

> Is it a problem that this is documented as "(PKG . DESCS)" when the
> printed representation is "(PKG DESCS)"?

No, because the implicit printed representation is actually
(PKG DESC...), not (PKG DESCS).  In other words, the cadr of each alist
element is a single package-desc structure, not a list thereof.  Both
the code and the docstring agree on this AFAICT.

Dotted notation is often employed in documentation in order to more
explicitly describe metasyntactic structure.  This may initially confuse
users who see the implicit printed representation, but sooner or later
all Emacsites ought to learn that (A B) is equivalent to (A . (B)).

> If not, we can close this as notabug.

Done, thanks.

-- 
Basil