Daniel Mendler writes: > Philip Kaludercic writes: > >> Eli Zaretskii writes: >> >>>> From: Daniel Mendler >>>> Cc: Philip Kaludercic , 66554@debbugs.gnu.org, >>>> monnier@iro.umontreal.ca, stefankangas@gmail.com >>>> Date: Thu, 18 Jan 2024 21:35:59 +0100 >>>> >>>> Eli Zaretskii 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: