GNU bug report logs - #66554
[PATCH] Add the public API of Compat to the core

Previous Next

Full log

Message #157 received at 66554 <at> debbugs.gnu.org (full text, mbox):

From: Philip Kaludercic <philipk <at> posteo.net>
To: Daniel Mendler <mail <at> daniel-mendler.de>
Cc: 66554 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>, stefankangas <at> gmail.com,
 monnier <at> iro.umontreal.ca
Subject: Re: bug#66554: [PATCH] Add the public API of Compat to the core
Date: Fri, 26 Jan 2024 07:58:18 +0000

[Message part 1 (text/plain, inline)]

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

> Philip Kaludercic <philipk <at> posteo.net> writes:
>
>> Eli Zaretskii <eliz <at> gnu.org> writes:
>>
>>>> From: Daniel Mendler <mail <at> daniel-mendler.de>
>>>> Cc: Philip Kaludercic <philipk <at> posteo.net>,  66554 <at> debbugs.gnu.org,
>>>>   monnier <at> iro.umontreal.ca,  stefankangas <at> gmail.com
>>>> Date: Thu, 18 Jan 2024 21:35:59 +0100
>>>> 
>>>> Eli Zaretskii <eliz <at> 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 (text/x-diff, attachment)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.