GNU bug report logs - #17403
24.4.50; package-alist doc-string error

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 17403 in the body.
You can then email your comments to 17403 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: Richard Kim <emacs18 <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.4.50; package-alist doc-string error
Date: Sun, 04 May 2014 18:42:18 -0700

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.
 

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Richard Kim <emacs18 <at> gmail.com>
Cc: 17403 <at> debbugs.gnu.org
Subject: Re: bug#17403: 24.4.50; package-alist doc-string error
Date: Sun, 14 Jul 2019 05:22:04 +0200

Richard Kim <emacs18 <at> 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

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 17403 <at> debbugs.gnu.org, Richard Kim <emacs18 <at> gmail.com>
Subject: Re: bug#17403: 24.4.50; package-alist doc-string error
Date: Sun, 14 Jul 2019 10:26:36 -0400

Stefan Kangas <stefan <at> marxist.se> writes:

> Richard Kim <emacs18 <at> 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)

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 17403 <at> debbugs.gnu.org
Subject: Re: bug#17403: 24.4.50; package-alist doc-string error
Date: Sun, 14 Jul 2019 17:58:16 +0200

Noam Postavsky <npostavs <at> 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.

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

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: Richard Kim <emacs18 <at> gmail.com>, 17403 <at> debbugs.gnu.org,
 Stefan Kangas <stefan <at> marxist.se>
Subject: Re: bug#17403: 24.4.50; package-alist doc-string error
Date: Mon, 15 Jul 2019 00:58:15 +0200

Noam Postavsky <npostavs <at> 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.

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

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: Richard Kim <emacs18 <at> gmail.com>, Stefan Kangas <stefan <at> marxist.se>,
 17403 <at> debbugs.gnu.org, Noam Postavsky <npostavs <at> gmail.com>
Subject: Re: bug#17403: 24.4.50; package-alist doc-string error
Date: Wed, 17 Jul 2019 15:10:46 +0100

Michael Heerdegen <michael_heerdegen <at> 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

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

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 17403 <at> debbugs.gnu.org, Noam Postavsky <npostavs <at> gmail.com>
Subject: Re: bug#17403: 24.4.50; package-alist doc-string error
Date: Wed, 17 Jul 2019 15:23:03 +0100

tags 17403 notabug
close 17403
quit

Stefan Kangas <stefan <at> 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

Previous Next

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