* bug#17403: 24.4.50; package-alist doc-string error
@ 2014-05-05 1:42 Richard Kim
2019-07-14 3:22 ` Stefan Kangas
0 siblings, 1 reply; 7+ messages in thread
From: Richard Kim @ 2014-05-05 1:42 UTC (permalink / raw
To: 17403
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.
^ permalink raw reply related [flat|nested] 7+ messages in thread
* bug#17403: 24.4.50; package-alist doc-string error
2014-05-05 1:42 bug#17403: 24.4.50; package-alist doc-string error Richard Kim
@ 2019-07-14 3:22 ` Stefan Kangas
2019-07-14 14:26 ` Noam Postavsky
0 siblings, 1 reply; 7+ messages in thread
From: Stefan Kangas @ 2019-07-14 3:22 UTC (permalink / raw
To: Richard Kim; +Cc: 17403
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
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#17403: 24.4.50; package-alist doc-string error
2019-07-14 3:22 ` Stefan Kangas
@ 2019-07-14 14:26 ` Noam Postavsky
2019-07-14 15:58 ` Stefan Kangas
2019-07-14 22:58 ` Michael Heerdegen
0 siblings, 2 replies; 7+ messages in thread
From: Noam Postavsky @ 2019-07-14 14:26 UTC (permalink / raw
To: Stefan Kangas; +Cc: Richard Kim, 17403
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)
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#17403: 24.4.50; package-alist doc-string error
2019-07-14 14:26 ` Noam Postavsky
@ 2019-07-14 15:58 ` Stefan Kangas
2019-07-17 14:23 ` Basil L. Contovounesios
2019-07-14 22:58 ` Michael Heerdegen
1 sibling, 1 reply; 7+ messages in thread
From: Stefan Kangas @ 2019-07-14 15:58 UTC (permalink / raw
To: Noam Postavsky; +Cc: 17403
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.
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#17403: 24.4.50; package-alist doc-string error
2019-07-14 14:26 ` Noam Postavsky
2019-07-14 15:58 ` Stefan Kangas
@ 2019-07-14 22:58 ` Michael Heerdegen
2019-07-17 14:10 ` Basil L. Contovounesios
1 sibling, 1 reply; 7+ messages in thread
From: Michael Heerdegen @ 2019-07-14 22:58 UTC (permalink / raw
To: Noam Postavsky; +Cc: 17403, Stefan Kangas, Richard Kim
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.
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#17403: 24.4.50; package-alist doc-string error
2019-07-14 22:58 ` Michael Heerdegen
@ 2019-07-17 14:10 ` Basil L. Contovounesios
0 siblings, 0 replies; 7+ messages in thread
From: Basil L. Contovounesios @ 2019-07-17 14:10 UTC (permalink / raw
To: Michael Heerdegen; +Cc: Stefan Kangas, 17403, Richard Kim, Noam Postavsky
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
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#17403: 24.4.50; package-alist doc-string error
2019-07-14 15:58 ` Stefan Kangas
@ 2019-07-17 14:23 ` Basil L. Contovounesios
0 siblings, 0 replies; 7+ messages in thread
From: Basil L. Contovounesios @ 2019-07-17 14:23 UTC (permalink / raw
To: Stefan Kangas; +Cc: 17403, Noam Postavsky
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
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2019-07-17 14:23 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2014-05-05 1:42 bug#17403: 24.4.50; package-alist doc-string error Richard Kim
2019-07-14 3:22 ` Stefan Kangas
2019-07-14 14:26 ` Noam Postavsky
2019-07-14 15:58 ` Stefan Kangas
2019-07-17 14:23 ` Basil L. Contovounesios
2019-07-14 22:58 ` Michael Heerdegen
2019-07-17 14:10 ` Basil L. Contovounesios
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.