From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Daniel Mendler via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#66554: [PATCH] Add the public API of Compat to the core Date: Wed, 07 Feb 2024 18:31:39 +0100 Message-ID: <87jzngw58k.fsf@daniel-mendler.de> References: <87pm1ggrdx.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> <864jer59gm.fsf@gnu.org> <87h6ils91z.fsf@posteo.net> <86r0hpz8o2.fsf@gnu.org> <87r0hpqs8i.fsf@posteo.net> <875xz05h6m.fsf@posteo.net> Reply-To: Daniel Mendler Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="17607"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Cc: 66554@debbugs.gnu.org, Eli Zaretskii , stefankangas@gmail.com, monnier@iro.umontreal.ca To: Philip Kaludercic Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Feb 07 18:33:11 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 1rXlnK-0004M1-Hj for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 07 Feb 2024 18:33:10 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rXln1-0003er-TG; Wed, 07 Feb 2024 12:32:51 -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 1rXlmz-0003ea-3q for bug-gnu-emacs@gnu.org; Wed, 07 Feb 2024 12:32:50 -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 1rXlmy-0007nf-RL for bug-gnu-emacs@gnu.org; Wed, 07 Feb 2024 12:32:48 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1rXlnC-000462-3p for bug-gnu-emacs@gnu.org; Wed, 07 Feb 2024 12:33:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Daniel Mendler Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 07 Feb 2024 17:33:02 +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.170732712415686 (code B ref 66554); Wed, 07 Feb 2024 17:33:02 +0000 Original-Received: (at 66554) by debbugs.gnu.org; 7 Feb 2024 17:32:04 +0000 Original-Received: from localhost ([127.0.0.1]:57829 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rXlmF-00044v-R3 for submit@debbugs.gnu.org; Wed, 07 Feb 2024 12:32:04 -0500 Original-Received: from server.qxqx.de ([2a01:4f8:c012:9177::1]:41867 helo=mail.qxqx.de) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rXlmC-00044P-IK for 66554@debbugs.gnu.org; Wed, 07 Feb 2024 12:32:01 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=daniel-mendler.de; s=key; h=Content-Type:MIME-Version:Message-ID:Date: References:In-Reply-To:Subject:Cc:To:From:Sender:Reply-To: Content-Transfer-Encoding:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id: List-Help:List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=NFNjzw+lT5H4PPyQo4OCPCSyi2S9EljojjHmWKtpxZw=; b=PJFMaoFbLrYP+WMrY/9Mjeuu0Q htRvpnoLXHNh4RZtCtJkvDr1+LrAihIWaL9ixQYNHcoY93kj7sI997pIpc9/ng6emFug0Bjp7e5V0 0JA6cd0IcPWZsfwkeTbL2aXe+ThtSNme93e1cwP2TVNoJxXAcyM1TP3Hj04b3XMoFDfc=; In-Reply-To: <875xz05h6m.fsf@posteo.net> (Philip Kaludercic's message of "Wed, 07 Feb 2024 17:15:45 +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:279567 Archived-At: Philip Kaludercic writes: > Philip Kaludercic writes: > >> Eli Zaretskii writes: >> >>>> From: Philip Kaludercic >>>> Cc: mail@daniel-mendler.de, 66554@debbugs.gnu.org, stefankangas@gmail.com, >>>> monnier@iro.umontreal.ca >>>> Date: Tue, 06 Feb 2024 19:10:32 +0000 >>>> >>>> >> +@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 intention was for this paragraph to catch that case, >>>> >>>> However in the case where Compat provides an alternative version of an >>>> existing function, the function call has to go through >>>> @code{compat-call}. >>>> >>>> though the real information is to be found in the Compat manual, where >>>> the functions that have to be called via compat-call are documented. >>>> >>>> Should the above sentence be rephrased to give a general feeling for >>>> when this is the case >>>> >>>> However in the case where Compat provides an alternative version of an >>>> existing function, the function call has to go through >>>> @code{compat-call}. This is the case when, for example the signature >>>> changes between versions, preventing older versions of Emacs from >>>> using optional arguments introduced in newer releases. >>>> >>>> or should we just refer to the external manual? >>> >>> Let me try to make my point more clear: I'd prefer that the reader >>> emerges from reading this description with a practical way of knowing >>> when to call the function directly and when to call it via >>> 'compat-call'. If that's not easy to understand, perhaps we should >>> tell that 'compat-call' should always be used, to avoid some rare >>> corner cases where a direct call will not do, and be done? >> >> I don't think we should recommend always using `compat-call', that would >> make code unreadable. What definitions have to be called via >> `compat-call' really depends on how they were defined in Compat. I >> don't know of a better rule to describe it without copying the >> documentation from the Compat manual (that wouldn't be a good idea >> either, because it wouldn't stay up to date). > > Daniel, do have any ideas how to improve the documentation here? It > seems to me that the authoritative source of information on what > functions to compat-call is Compat itself, right? The Compat manual explicitly lists how each function should be called. This information is not static, since new functions are added with every Compat release. Examples from the Compat manual: Function: compat-call plist-get plist prop &optional predicate Function: ntake n list I think we should explain the general idea in the compat.el file in Emacs itself (docstrings and commentary) and refer to the Compat manual for the list of supported functions and their calling convention. The explanations in the current patch look good to me. Daniel