Hi Eli, Eli Zaretskii writes: >> From: Xiyue Deng >> Cc: spwhitton@spwhitton.name, 78844@debbugs.gnu.org, monnier@iro.umontreal.ca >> Date: Fri, 27 Jun 2025 17:25:41 -0700 >> >> >> I don't seem to find any Elisp manual for package.el (there is one in >> >> the Emacs manual but only has documents for user facing interfaces for >> >> the package buffer). But do let me know if there is. >> > >> > There's the "Packaging" chapter in the ELisp manual. Whether it is a >> > suitable place to add these interfaces depends on who is the intended >> > audience of the interfaces. If that chapter is not suitable, maybe >> > the "Loading" chapter is a better place. >> > >> >> Admittedly I tried to be lazy and want to just add the new functions to >> an existing section but didn't find any good fit. I just bit the bullet >> and added a new section in package.texi for these functions. Please >> help proofread. > > Thanks, comments below. However, packages.texi is not the right place > for this stuff, because it's for the user manual, not for the ELisp > reference manual. Since these APIs are for Lisp programmers, they > should be documented in the ELisp manual, and the chapters I mentioned > are in that manual. > I'm a bit confused: the file I changed was doc/lispref/package.texi, which I suppose is the ELisp manual, no? >> >> +(defun package-builtin-packages () >> >> + "Return a list of builtin package symbols. >> >> +The returned list is not guaranteed to be sorted." >> > >> > This doc string is too biased towards implementation, IMO. I would >> > rephrase it as follows: >> > >> > Return a list of all the built-in packages. >> >> To be precise, package--builtin-versions doesn't have all the built-in >> packages (which I think is a subset of the list populated by >> package--builtins). As here we are more interested in packages that do >> have a version associated, I have renamed the function to >> `package-versioned-builtin-packages' to hopefully better convey the >> intention. Let me know if this is desirable. > > The renaming could be fine if the intended users of this API will > indeed only want to know about versioned built-in packages, and won't > care about those who have no versions. Is that in fact true? If so, > why aren't unversioned packages important? > > If we do want to return the built-in packages that have no versions, > then the name should remain as it was, and we should instead amend the > implementation to also return packages that have no versions. > The motivation for introducing those functions is to be able to check whether a built-in package has higher version compared to the same package in other packaging system, which, in my case, is Debian's APT, and could be useful for other packaging systems. See my first mail[1] for a concrete motivating example and my reply[2] to Stefan's email for a more explanations. The current status quo is that most Emacs addons that are packaged in Debian are in `package--builtin-versions', so this is sufficient for our use case. Plus, on testing I realized that `package--builtins' is not populated by default until one loads `finder-inf', which means increased loading time to use that information. In summary, I think having `package-versioned-builtin-packages' is good enough for now. And if requirement changes in the future, we can still introduce `package-builtin-packages' to query `package--builtins'. >> +@node Package Information >> +@section Get built-in packages and versions >> +@cindex package information >> + >> +Emacs ships a list of built-in packages which may also be packaged > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > Emacs ships the packages themselves, not a list of packages. My English fails me often. Revised the wording a bit. PTAL. [1] https://debbugs.gnu.org/cgi/bugreport.cgi?bug=78844#5 [2] https://debbugs.gnu.org/cgi/bugreport.cgi?bug=78844#23 -- Regards, Xiyue Deng