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

[Eli Zaretskii <eliz@gnu.org>]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: mail@daniel-mendler.de,  66554@debbugs.gnu.org,  stefankangas@gmail.com,
>   monnier@iro.umontreal.ca
> Date: Thu, 08 Feb 2024 07:40:23 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> 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.

Thanks.  I suggest to copy the above paragraph to the ELisp reference
manual, and add a cross-reference to the Compat manual after it.

Btw, whenever you introduce terminology in our manuals, as in
``Extended Definitions'' above, it is best to use the @dfn markup
instead of literal quotes: the results look better in HTML and printed
output formats.