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

[Philip Kaludercic <philipk@posteo.net>]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: Eli Zaretskii <eliz@gnu.org>,  66554@debbugs.gnu.org,
>>   monnier@iro.umontreal.ca,  stefankangas@gmail.com
>> Date: Thu, 18 Jan 2024 19:51:27 +0000
>> 
>> Pinging this thread with an updated version of the patch:
>
> 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 can go into more detail, integrating what Daniel explained, my
question just is if this is something that really interests someone
reading the Elisp manual?  One could duplicate or adjust the
documentation for `compat-call' and `compat-function', but explaining
things like how the compat.el file prevents installing Compat
unnecessarily seems like an internal detail to me.

>> +Packages that wish to support older releases of Emacs, without giving
>> +up on newer functionality from recent Emacs releases, one can make use
>> +of the Compat package on GNU ELPA.  For details on how to make use of
>> +the package, @xref{Usage,, Usage, compat, "Compat" Manual}. In case
>                 ^^^^^                                        ^^
> This should be "see @ref" or "@pxref".  @xref is only suitable at the
> beginning of a statement.  And please leave 2 spaces between sentences
> there.

Fixed.

>> +** New package Compat
>> +The Compat package on GNU ELPA provides forwards-compatibility
>> +support, so that packages that still provide support for older
>
> I think this is known as "backward compatibility".

My understanding is that "backwards compatibility" would refer to any
measures, that would assist keeping old code working in newer versions
of Emacs.  Compat doesn't do that (let alone the compat.el from this
patch), it just allows older packages to use newer functionality that
can be replicated for older systems.  The term is also used by the
nadvice package on ELPA.

>> +versions of Emacs can still make use of newer definitions that can be
>> +reasonably re-implemented in Elisp.  Now a "pseudo" Compat package is
>> +part of Emacs, that doesn't provide any compatibility support, but
>> +only implements the public-facing API of Compat so that core packages
>> +can use Compat, while also preventing the installation of Compat on
>> +the most recent version of Emacs.
>
> Not sure this detailed description is useful.  Why not just say that
> Compat is now also available with Emacs?

I was not sure how much detail to give, but if you think it is too much,
I can of course remove it.

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> +;;;; Hack to avoid installing Compat if not necessary
>> +
>> +;; The versioning scheme of the Compat package follows that of Emacs,
>> +;; to indicate what version of Emacs is being supported.  For example,
>> +;; the Compat version number 29.2.3.9 would attempt to provide
>> +;; compatibility definitions up to Emacs 29.2, while also designating
>> +;; that this is the third major release and ninth minor release of
>> +;; Compat, for the specific Emacs release.
>> +
>> +;; To ensure that if the user is using Emacs X.Y installed, the ELPA
>> +;; package Compat X.Y.Z* (for any values of Z*) does not get
>> +;; unnecessarily installed, as there are no missing features that
>> +;; Compat could provide, we programmatically specify the version of
>> +;; the package to be that of the current Emacs version plus a high
>> +;; "major release" to exceed the major version of Compat.
>> +
>> +;;;###autoload (push (list 'compat emacs-major-version
>> emacs-minor-version most-positive-fixnum) package--builtin-versions)
>
> Hack?  Why call it a hack?
>
> By definition a `compat-NN.MM` package is attempting to provide a subset
> of the API offered by Emacs-NN.MM, so Emacs-NN.MM very much provides
> a version of `compat-NN.MM`.
> IOW
>
>     (push (list 'compat emacs-major-version emacs-minor-version ...)
>           package--builtin-versions)
>
> is not a hack at all.
>
> If you want to label the `most-positive-fixnum` as a hack, I guess
> that's OK but then the comment should clarify what it's referring to.

In this case I just meant "hack" in the sense of a "clever trick", since
it was not immediately obvious to anyone until you brought it up.

> Also, please keep the line below the 80 columns limit, e.g.:
>
>     ;;;###autoload (push (list 'compat emacs-major-version
>     ;;;###autoload              emacs-minor-version most-positive-fixnum)
>     ;;;###autoload       package--builtin-versions)

Sure, done.

>
> -- Stefan