branch: externals/compat
commit d696cf92188e5c6062778c75762d2eaeec445d69
Author: Daniel Mendler <m...@daniel-mendler.de>
Commit: Daniel Mendler <m...@daniel-mendler.de>
Update manual
---
NEWS.org | 6 +++---
compat-tests.el | 2 +-
compat.texi | 25 +++++++++++++------------
3 files changed, 17 insertions(+), 16 deletions(-)
diff --git a/NEWS.org b/NEWS.org
index 9d0ae881e2..b35fd4e24f 100644
--- a/NEWS.org
+++ b/NEWS.org
@@ -14,9 +14,9 @@
- Add the macros ~compat-call~ and ~compat-function~ to call compatibility
functions. Since Compat avoids overwriting already existing functions, we
must
define separate compatibility function definitions for functions which
changed
- their calling convention. These compatibility definitions can be looked up
- using ~compat-function~ and called with ~compat-call~. For example ~assoc~
can be
- called with a ~TESTFN~ since Emacs 29. In Emacs 28 and older the calling
+ their calling convention or behavior. These compatibility definitions can be
+ looked up using ~compat-function~ and called with ~compat-call~. For example
~assoc~
+ can be called with a ~TESTFN~ since Emacs 29. In Emacs 28 and older the
calling
convention was ~(assoc KEY ALIST)~. In order to use the new calling
convention
you can use ~(compat-call assoc KEY ALIST TESTFN)~.
- Deprecate all ~compat-*~ prefixed functions. Instead use the aforementioned
diff --git a/compat-tests.el b/compat-tests.el
index 9e3e0e165b..470708bd23 100644
--- a/compat-tests.el
+++ b/compat-tests.el
@@ -27,7 +27,7 @@
;; The tests are written in a simple, explicit style. Please inspect the
;; tests in order to find out the supported calling conventions. In
;; particular, note the use of `compat-call' to call functions, where the
-;; calling convention changed between Emacs versions.
+;; calling convention or behavior changed between Emacs versions.
;; The functions tested here are guaranteed to work on the Emacs versions
;; tested by continuous integration. This includes 24.4, 24.5, 25.1, 25.2,
diff --git a/compat.texi b/compat.texi
index 4befe76fc5..c5f38bf495 100644
--- a/compat.texi
+++ b/compat.texi
@@ -136,14 +136,15 @@ the noerror flag should be specified.
@end example
This will load all implicit and explicit Compat definitions. Functions
-and macros where the calling convention has changed can be accessed
-explicitly via @code{compat-function} and @code{compat-call}. We
-call these definitions ``Explicit Definitions''. In contrast,
-``Implicit Definitions'' can be called as usual.
+and macros where the calling convention or behavior has changed can be
+accessed explicitly via @code{compat-function} and
+@code{compat-call}. We call these definitions ``Explicit
+Definitions''. In contrast, ``Implicit Definitions'' can be called as
+usual.
@example
-(compat-call sort SEQUENCE PREDICATE) ;; Explicit
-(mapcan FUNCTION SEQUENCE) ;; Implicit
+(compat-call assoc KEY ALIST TESTFN) ;; Explicit
+(mapcan FUNCTION SEQUENCE) ;; Implicit
@end example
@defmac compat-call FUN &rest ARGS
@@ -192,7 +193,7 @@ To support these cases, the function or macro would have to
be
advised. As this is regarded as invasive and adds significant
overhead, even when the new feature is not used, this approach is not
used. As a compromise, compatibility functions and macros with a
-changed calling convention can be accessed via the
+changed calling convention or behavior can be accessed via the
@code{compat-function} and @code{compat-call} macros.
@item
@@ -425,7 +426,7 @@ arguments, @var{objects}.
@subsection Explicit Definitions
These functions must be called explicitly via @code{compat-call},
-since their calling convention changed:
+since their calling convention or behavior changed:
@defun compat-call@ sort sequence predicate
This function sorts @var{sequence} stably. Note that this function
@@ -730,7 +731,7 @@ size, modes, inode-number and device-number.
@subsection Explicit Definitions
These functions must be called explicitly via @code{compat-call},
-since their calling convention changed:
+since their calling convention or behavior changed:
@defun compat-call@ assoc key alist &optional testfn
This function returns the first association for @var{key} in
@@ -1176,7 +1177,7 @@ function signals an error.
@subsection Explicit Definitions
These functions must be called explicitly via @code{compat-call},
-since their calling convention changed:
+since their calling convention or behavior changed:
@c based on lispref/windows.texi
@defun compat-call@ recenter &optional count redisplay
@@ -1910,7 +1911,7 @@ assume that there is a user named @samp{rms} but no user
named
@subsection Explicit Definitions
These functions must be called explicitly via @code{compat-call},
-since their calling convention changed:
+since their calling convention or behavior changed:
@c copied from lispref/files.texi
@defun compat-call@ unlock-buffer
@@ -2623,7 +2624,7 @@ This is comparable to @code{and-let*}.
@subsection Explicit Definitions
These functions must be called explicitly via @code{compat-call},
-since their calling convention changed:
+since their calling convention or behavior changed:
@c copied from lispref/keymaps.texi
@defun compat-call@ define-key
