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

[Daniel Mendler via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

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.

Daniel