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: mail@daniel-mendler.de,  66554@debbugs.gnu.org,  stefankangas@gmail.com,
>>   monnier@iro.umontreal.ca
>> Date: Wed, 07 Feb 2024 17:15:45 +0000
>> 
>> >> 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?
>
> What does Compat manual say about this aspect?

--8<---------------cut here---------------start------------->8---
Note that Compat provides replacement functions with extended
functionality for functions that are already defined (@code{sort},
@code{assoc}, @dots{}).  These functions may have changed their
calling convention (additional optional arguments) or may have changed
their behavior.  These functions must be looked up explicitly with
@code{compat-function} or called explicitly with @code{compat-call}.
We call them ``Extended Definitions''.  In contrast, newly ``Added
Definitions'' can be called as usual.

@example
(compat-call assoc key alist testfn) ;; Call extended `assoc'
(mapcan fun seq)                     ;; Call newly added `mapcan'
@end example

@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}.  This happens for example when the calling
convention of a function has changed.
@end defmac

@defmac compat-function fun
This macro returns the compatibility function symbol for @var{fun}.
See @code{compat-call} for a more convenient macro to directly call
compatibility functions.
@end defmac
--8<---------------cut here---------------end--------------->8---

and then later on, for each version there is a section like this

--8<---------------cut here---------------start------------->8---
@subsection Extended Definitions
These functions must be called explicitly via @code{compat-call},
since their calling convention or behavior was extended in Emacs 29.1:

@c copied from lispref/keymaps.texi
@defun compat-call@ set-transient-map keymap &optional keep-pred on-exit message timeout
This function adds @var{keymap} as a @dfn{transient} keymap, which
takes precedence over other keymaps for one (or more) subsequent keys.
...
--8<---------------cut here---------------end--------------->8---