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

[Eli Zaretskii]

[Please ignore my previous response, it was mistakenly sent prematurely.]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: 66554@debbugs.gnu.org,  Eli Zaretskii <eliz@gnu.org>,
>   stefankangas@gmail.com,  monnier@iro.umontreal.ca
> Date: Fri, 02 Feb 2024 08:11:27 +0000
> 
> diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi
> index 6f52a33d194..071c87170f5 100644
> --- a/doc/lispref/package.texi
> +++ b/doc/lispref/package.texi
> @@ -28,6 +28,7 @@ Packaging
>  * Multi-file Packages::     How to package multiple files.
>  * Package Archives::        Maintaining package archives.
>  * Archive Web Server::      Interfacing to an archive web server.
> +* Forwards-Compatibility::  Supporting older versions of Emacs.
     ^^^^^^^^^^^^^^^^^^^^^^
This should be "Forward Compatibility", without "s" and without the
dash.

> +@node Forwards-Compatibility

Likewise.

> +@section Supporting older versions of Emacs
> +@cindex compatibility compat

I suggest the following index entries:

  @cindex forward compatibility, in packages
  @cindex supporting older Emacs releases, in packages
  @cindex Compat package

> +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.                    ^^^

That "one" should be removed.  And the comma before it as well.

>                                      By depending on the package, Emacs
> +can provide compatibility definitions for missing functionality.

I think you mean "By depending on the Compat package, ..."

> +
> +The versioning of Compat follows that of Emacs, so next to the oldest
> +version that a package relies on (via the @code{emacs}-package), one
> +can also indicate what the newest version of Emacs is, that a package
> +wishes to use definitions from:
> +
> +@example
> +;; Package-Requires: ((emacs "27.2") (compat "29.1"))
> +@end example

That sentence is hard to grasp.  I suggest to rephrase it:

  The version of Compat included with Emacs is the same as the Emacs
  release in which it was included.  Thus, packages that want to use
  functionality from Emacs versions newer than the oldest one they
  support should @emph{also} depend on Compat from the newest Emacs
  release.  For example:

  @example
  ;; Package-Requires: ((emacs "27.2") (compat "29.1"))
  @end example

  @noindent
  The above says that the package needs at least Emacs 27.2, but uses
  functionality introduced with Emacs 29.1, which in Emacs versions
  before 29.2 will come from the Compat package.

> +By default, one can refer to compatibility definitions by their given
> +names from future versions.  For example, one can use the function
> +@code{take} on before Emacs 29 as such.

I suggest to rephrase the last sentence:

  For example, a package can call @code{take}, which was introduced in
  Emacs 29, also in older Emacs versions, and Compat will supply the
  missing function definition.

>                                            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 versioning scheme of the Compat package follows that of Emacs,
> +;; to indicate the version of Emacs, that functionality is being
                                        ^^^^
"whose", not "that"

> +;; provided for.  For example, the Compat version number 29.2.3.9
               ^^^
Please remove that "for".

Thanks.