Hi Eli,

Eli Zaretskii <eliz@gnu.org> writes:

>> Cc: 78844@debbugs.gnu.org, Stefan Monnier <monnier@iro.umontreal.ca>
>> From: Xiyue Deng <manphiz@gmail.com>
>> Date: Fri, 27 Jun 2025 03:34:25 -0700
>> 
>> > and see if these packages need documentation in the Elisp manual (they
>> > may or may not).
>> >
>> 
>> 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.

>> +(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 return value is a list of names of built-in packages represented
>   as symbols.
>
> I don't see a need to mention that the list is not sorted, because not
> saying it's sorted should be enough for users not to rely on that.

Indeed, this seems to be an unnecessary detail to call out.

> (As a matter of fact, I think the list will be sorted, because
> package--builtin-versions is sorted.)
>

In fact, in 30.1 (which I'm using) it's almost sorted in descending
alphabetic order except that the last item is "emacs" and the second to
last is "all-out".  Anyway, as you mentioned, not mentioning the
ordering in the docstring should indicate that a caller should not make
any assumptions.

>> +(defun package-builtin-package-version (package)
>> +  "Return the version-list of PACKAGE (symbol).
>
> This uses "version-list", which is not accepted terminology in Emacs.
> I suggest
>
>     Return the version of a built-in PACKAGE given by its symbol.
>   Value is a list of integers representing the version of PACKAGE,
>   in the format returned by `version-to-list', or nil if PACKAGE
>   has no version or is not a built-in package.
>

Adapted.

>> diff --git a/etc/NEWS b/etc/NEWS
>> index eb85baae341..e940b5fce17 100644
>> --- a/etc/NEWS
>> +++ b/etc/NEWS
>> @@ -2607,6 +2607,13 @@ sleep state.
>>  and set the top-level buffer-local value of a variable.  A top-level
>>  value is the one that variable has outside of any let-bindings.
>>  
>> ++++
>> +** New functions to query builtin package information.
>> +'package-builtin-packages' returns a list of symbols of built-in
>> +packages; 'package-builtin-package-version' returns the version-list of
>> +a given package symbol.  These functions provide stable interfaces for
>> +external tools to query built-in package information.
>
> This should go under the "Package" section in NEWS.
>

Moved there.

> Thanks.

PTAL.

-- 
Regards,
Xiyue Deng