From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#66554: [PATCH] Add the public API of Compat to the core Date: Fri, 02 Feb 2024 14:36:41 +0200 Message-ID: <864jer59gm.fsf@gnu.org> References: <87pm1ggrdx.fsf@posteo.net> <87bk9raaad.fsf@daniel-mendler.de> <87a5pbvbxc.fsf@posteo.net> <875xzza8jw.fsf@daniel-mendler.de> <87edemldlw.fsf@posteo.net> <83cyu6ifzw.fsf@gnu.org> <875xzyl8lq.fsf@posteo.net> <837ckeievw.fsf@gnu.org> <87h6jiqtsp.fsf@daniel-mendler.de> <835xzyiagj.fsf@gnu.org> <871qamkx0m.fsf@posteo.net> <83wmsdhgw8.fsf@gnu.org> <87wmsdxvz6.fsf@daniel-mendler.de> <878r4ml8sg.fsf@posteo.net> <83v87qwg48.fsf@gnu.org> <87h6jaz8eo.fsf@daniel-mendler.de> <83r0idx1p1.fsf@gnu.org> <87mst1tgrt.fsf@posteo.net> <874jf39rn7.fsf@daniel-mendler.de> <871qa47ch1.fsf@posteo.net> <87a5osfka1.fsf@daniel-mendler.de> <87y1c3s2ts.fsf@posteo.net> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="2483"; mail-complaints-to="usenet@ciao.gmane.io" Cc: mail@daniel-mendler.de, stefankangas@gmail.com, monnier@iro.umontreal.ca, 66554@debbugs.gnu.org To: Philip Kaludercic Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri Feb 02 13:38:07 2024 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1rVso2-0000O4-T4 for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 02 Feb 2024 13:38:07 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rVsnp-0000OY-He; Fri, 02 Feb 2024 07:37:53 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rVsno-0000OB-3r for bug-gnu-emacs@gnu.org; Fri, 02 Feb 2024 07:37:52 -0500 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rVsnn-0002tz-Jz for bug-gnu-emacs@gnu.org; Fri, 02 Feb 2024 07:37:51 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1rVsnx-0004kA-UW for bug-gnu-emacs@gnu.org; Fri, 02 Feb 2024 07:38:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 02 Feb 2024 12:38:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 66554 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 66554-submit@debbugs.gnu.org id=B66554.170687742518167 (code B ref 66554); Fri, 02 Feb 2024 12:38:01 +0000 Original-Received: (at 66554) by debbugs.gnu.org; 2 Feb 2024 12:37:05 +0000 Original-Received: from localhost ([127.0.0.1]:43802 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rVsn2-0004iw-EB for submit@debbugs.gnu.org; Fri, 02 Feb 2024 07:37:04 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:54194) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rVsn0-0004iT-3s for 66554@debbugs.gnu.org; Fri, 02 Feb 2024 07:37:02 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rVsmi-0002ha-5l; Fri, 02 Feb 2024 07:36:44 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=vqcBBs3NmPqJitVYQRSDXlVdwikOu/zKJE6x0zkicNU=; b=fjf1I0wi59ne fK1UlkPITgK/xipVq/3CTn2lYreOFZHf3IdoJcuNyNZ3fmXVpxhjhKHF6jLRVwtzPahkZyoj+7kD0 1Xoij44+6hCAW+HWfZ+BFpMHKtTy91AUVAtTaKHBqM9ASXb+6LTRtx/yj8euoTRM5neXLd4gDnxds wwFRQc4b/44G5cx/0xepPCMjveWGeEjIpRkr4BFqsX8I3c6RScshY7P4w1QgDdAAodFqaT98SvClY QU6YzCznHWDgzCJ8E7TmlUilUQKI41a1LYUg4LVu69q1j5mEczVstVkPELZwL7WMczaLjXOPg4c19 Qtv8c+8qAxK6gHPdSKz6TQ==; In-Reply-To: <87y1c3s2ts.fsf@posteo.net> (message from Philip Kaludercic on Fri, 02 Feb 2024 08:11:27 +0000) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:279343 Archived-At: [Please ignore my previous response, it was mistakenly sent prematurely.] > From: Philip Kaludercic > Cc: 66554@debbugs.gnu.org, Eli Zaretskii , > stefankangas@gmail.com, monnier@iro.umontreal.ca > Date: Fri, 02 Feb 2024 08:11:27 +0000 > > diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi > index 6f52a33d194..071c87170f5 100644 > --- a/doc/lispref/package.texi > +++ b/doc/lispref/package.texi > @@ -28,6 +28,7 @@ Packaging > * Multi-file Packages:: How to package multiple files. > * Package Archives:: Maintaining package archives. > * Archive Web Server:: Interfacing to an archive web server. > +* Forwards-Compatibility:: Supporting older versions of Emacs. ^^^^^^^^^^^^^^^^^^^^^^ This should be "Forward Compatibility", without "s" and without the dash. > +@node Forwards-Compatibility Likewise. > +@section Supporting older versions of Emacs > +@cindex compatibility compat I suggest the following index entries: @cindex forward compatibility, in packages @cindex supporting older Emacs releases, in packages @cindex Compat package > +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. ^^^ That "one" should be removed. And the comma before it as well. > By depending on the package, Emacs > +can provide compatibility definitions for missing functionality. I think you mean "By depending on the Compat package, ..." > + > +The versioning of Compat follows that of Emacs, so next to the oldest > +version that a package relies on (via the @code{emacs}-package), one > +can also indicate what the newest version of Emacs is, that a package > +wishes to use definitions from: > + > +@example > +;; Package-Requires: ((emacs "27.2") (compat "29.1")) > +@end example That sentence is hard to grasp. I suggest to rephrase it: The version of Compat included with Emacs is the same as the Emacs release in which it was included. Thus, packages that want to use functionality from Emacs versions newer than the oldest one they support should @emph{also} depend on Compat from the newest Emacs release. For example: @example ;; Package-Requires: ((emacs "27.2") (compat "29.1")) @end example @noindent The above says that the package needs at least Emacs 27.2, but uses functionality introduced with Emacs 29.1, which in Emacs versions before 29.2 will come from the Compat package. > +By default, one can refer to compatibility definitions by their given > +names from future versions. For example, one can use the function > +@code{take} on before Emacs 29 as such. I suggest to rephrase the last sentence: For example, a package can call @code{take}, which was introduced in Emacs 29, also in older Emacs versions, and Compat will supply the missing function definition. > Due to changes of function > +and macro calling conventions over time, this is not always possible > +and it is occasionally necessary to explicitly refer to compatibility > +code. To this end one can use the Compat API: > + > +@defmac compat-call fun &rest args > +This macro calls the compatibility function @var{fun} with @var{args}. > +Many functions provided by Compat can be called directly without this > +macro. However in the case where Compat provides an alternative > +version of an existing function, the function call has to go through > +@code{compat-call}. > +@end defmac This description left me without understanding when I need to use compat-call and when I can just call FUN. Can you explain more? > +;; The versioning scheme of the Compat package follows that of Emacs, > +;; to indicate the version of Emacs, that functionality is being ^^^^ "whose", not "that" > +;; provided for. For example, the Compat version number 29.2.3.9 ^^^ Please remove that "for". Thanks.