bug#66554: [PATCH] Add the public API of Compat to the core

[Philip Kaludercic]

Daniel Mendler <mail@daniel-mendler.de> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> Eli Zaretskii <eliz@gnu.org> writes:
>>
>>>> From: Daniel Mendler <mail@daniel-mendler.de>
>>>> Cc: Philip Kaludercic <philipk@posteo.net>,  66554@debbugs.gnu.org,
>>>>   monnier@iro.umontreal.ca,  stefankangas@gmail.com
>>>> Date: Thu, 18 Jan 2024 21:35:59 +0100
>>>> 
>>>> Eli Zaretskii <eliz@gnu.org> writes:
>>>> 
>>>> > I find the documentation of this arrangement still insufficient.  The
>>>> > way this stuff works (which required Daniel to write 150 lines of
>>>> > explanation) is mostly kept out of the written docs, so we'll have to
>>>> > rely on people's memory.  Can we document this machinery better?
>>>> 
>>>> I agree. Where do you suggest to add the documentation? My intention is
>>>> to update the Compat manual (of the Compat ELPA package) with a more
>>>> detailed explanation of the mechanism as soon as the compat.el file gets
>>>> added to the Emacs core. We may want to avoid to duplicate the
>>>> information, by keeping the documentation in the Emacs compat.el file
>>>> concise, referring mainly to the Compat manual.
>>>
>>> The Compat manual cannot be the only place, because the information
>>> I'm talking about should be aimed at the Emacs developers, so it must
>>> be part of Emacs.  I suggest to have it in the commentary in
>>> compat.el.
>>
>> OK.
>
> Philip, do you plan to submit a new version of the patch or do you want
> me to update the patch with a more extensive explanation? We should keep
> in mind that the information we add to the Emacs compat.el cannot be
> self sufficient. Emacs developers who want to use Compat must consult
> the Compat manual, since that's the place where we document the
> available compatibility definitions. Therefore referring to the manual
> for further details should be okay, as long as the general mechanism
> (and the versioning) is explained sufficiently well in the commentary of
> the compat.el file in Emacs.

I have tried to update the patch to clarify some of the points in the
discussion, but feel free to change anything you think ought to be changed:

0001-Add-the-public-API-of-Compat-to-the-core.patch
Description: Text Data