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

[Philip Kaludercic]

(Sorry for the delay)

Eli Zaretskii <eliz@gnu.org> writes:

As usual, your way of putting it was better, so I applied the changes
and have also taken care of the typos.

>>                                            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 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?