From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Philip Kaludercic Newsgroups: gmane.emacs.bugs Subject: bug#66554: [PATCH] Add the public API of Compat to the core Date: Thu, 18 Jan 2024 20:47:38 +0000 Message-ID: <87wms6jrmd.fsf@posteo.net> References: <87pm1ggrdx.fsf@posteo.net> <87y1cwpanh.fsf@posteo.net> <877ckgpa45.fsf@daniel-mendler.de> <87mstbpyd7.fsf@posteo.net> <87h6jjah1g.fsf@daniel-mendler.de> <87edenptba.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> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="11930"; mail-complaints-to="usenet@ciao.gmane.io" Cc: mail@daniel-mendler.de, stefankangas@gmail.com, monnier@iro.umontreal.ca, 66554@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Jan 18 21:48:21 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 1rQZJF-0002wU-Ni for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 18 Jan 2024 21:48:21 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rQZIw-00088x-2d; Thu, 18 Jan 2024 15:48:02 -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 1rQZIu-00088f-4f for bug-gnu-emacs@gnu.org; Thu, 18 Jan 2024 15:48:00 -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 1rQZIt-0004jE-Sd for bug-gnu-emacs@gnu.org; Thu, 18 Jan 2024 15:47:59 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1rQZIv-0000xL-KC for bug-gnu-emacs@gnu.org; Thu, 18 Jan 2024 15:48:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Philip Kaludercic Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 18 Jan 2024 20:48: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.17056108713613 (code B ref 66554); Thu, 18 Jan 2024 20:48:01 +0000 Original-Received: (at 66554) by debbugs.gnu.org; 18 Jan 2024 20:47:51 +0000 Original-Received: from localhost ([127.0.0.1]:56806 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rQZIk-0000w9-RA for submit@debbugs.gnu.org; Thu, 18 Jan 2024 15:47:51 -0500 Original-Received: from mout02.posteo.de ([185.67.36.66]:55735) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rQZIi-0000vB-Kp for 66554@debbugs.gnu.org; Thu, 18 Jan 2024 15:47:49 -0500 Original-Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 64499240103 for <66554@debbugs.gnu.org>; Thu, 18 Jan 2024 21:47:40 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1705610860; bh=q8Q/41FvhT44yMSisYo6UsNXEzpOPLf361LoFA5jyU4=; h=From:To:Cc:Subject:Autocrypt:OpenPGP:Date:Message-ID:MIME-Version: Content-Type:From; b=W+KcBNbDfQBeAykAmAbLdKMsVK+jQKMSuJEyNi9MrMjIhGe0MtbagvO71NrXUUiUJ A/tT6ttwUbXu/U/15p0NVnpN/MDxxU5h5ol1s30eSyTdJG3jtpH13/crBsjEykNbKn cxzAMlIc7+Hebju9dYU9JRk0uOVQ8cTG0bQwqG/yloFG4WUosVdqqJjrGh9xaKRR6X 4L0tcFZOAwnE8M6Ndcy3T0IQhm5IH5AM3u+2Y0vceI4YjufHug4uQMc0Pb2awDR1QN COotcSQaqpIviiJla+y7aherLxtuyHnzkuTcx6TgkWIGJ8n+9lDZRIAQ49f84phWhC 8Lieent2rekdA== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4TGFDq2RPpz6tvr; Thu, 18 Jan 2024 21:47:39 +0100 (CET) In-Reply-To: <83v87qwg48.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 18 Jan 2024 22:17:43 +0200") Autocrypt: addr=philipk@posteo.net; keydata= mDMEZBBQQhYJKwYBBAHaRw8BAQdAHJuofBrfqFh12uQu0Yi7mrl525F28eTmwUDflFNmdui0QlBo aWxpcCBLYWx1ZGVyY2ljIChnZW5lcmF0ZWQgYnkgYXV0b2NyeXB0LmVsKSA8cGhpbGlwa0Bwb3N0 ZW8ubmV0PoiWBBMWCAA+FiEEDg7HY17ghYlni8XN8xYDWXahwukFAmQQUEICGwMFCQHhM4AFCwkI BwIGFQoJCAsCBBYCAwECHgECF4AACgkQ8xYDWXahwulikAEA77hloUiSrXgFkUVJhlKBpLCHUjA0 mWZ9j9w5d08+jVwBAK6c4iGP7j+/PhbkxaEKa4V3MzIl7zJkcNNjHCXmvFcEuDgEZBBQQhIKKwYB BAGXVQEFAQEHQI5NLiLRjZy3OfSt1dhCmFyn+fN/QKELUYQetiaoe+MMAwEIB4h+BBgWCAAmFiEE Dg7HY17ghYlni8XN8xYDWXahwukFAmQQUEICGwwFCQHhM4AACgkQ8xYDWXahwukm+wEA8cml4JpK NeAu65rg+auKrPOP6TP/4YWRCTIvuYDm0joBALw98AMz7/qMHvSCeU/hw9PL6u6R2EScxtpKnWof z4oM OpenPGP: id=7126E1DE2F0CE35C770BED01F2C3CC513DB89F66; url="https://keys.openpgp.org/vks/v1/by-fingerprint/7126E1DE2F0CE35C770BED01F2C3CC513DB89F66"; preference=signencrypt 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:278454 Archived-At: Eli Zaretskii writes: >> From: Philip Kaludercic >> Cc: Eli Zaretskii , 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 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