[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/compat 314e897648: Manual: Add section about limitation
From: |
ELPA Syncer |
Subject: |
[elpa] externals/compat 314e897648: Manual: Add section about limitations |
Date: |
Tue, 31 Jan 2023 16:57:26 -0500 (EST) |
branch: externals/compat
commit 314e8976482028ad2ca7bece7cc167a241192a8c
Author: Daniel Mendler <mail@daniel-mendler.de>
Commit: Daniel Mendler <mail@daniel-mendler.de>
Manual: Add section about limitations
---
NEWS.org | 3 ++-
compat.texi | 58 +++++++++++++++++++++++++++++++---------------------------
2 files changed, 33 insertions(+), 28 deletions(-)
diff --git a/NEWS.org b/NEWS.org
index 04ae9cb191..e770170138 100644
--- a/NEWS.org
+++ b/NEWS.org
@@ -3,7 +3,8 @@
* Development
- compat-26: Add ~make-temp-file~ with optional argument TEXT.
-- compat-27: Mark ~compat-call dired-get-marked-files~ as obsolete.
+- compat-27: Mark ~compat-call dired-get-marked-files~ as obsolete. See the
+ section limitations in the Compat manual.
- compat-29: Add ~funcall-with-delayed-message~ and ~with-delayed-message~.
- compat-29: Add ~ert-with-temp-file~ and ~ert-with-temp-directory~.
- compat-29: Add ~set-transient-map~ with optional arguments MESSAGE and
TIMEOUT.
diff --git a/compat.texi b/compat.texi
index f1aa74faeb..86f23459dd 100644
--- a/compat.texi
+++ b/compat.texi
@@ -65,7 +65,7 @@ Introduction
* Overview::
* Usage::
-* Intentions::
+* Limitations::
Support
@@ -84,21 +84,20 @@ Support
@menu
* Overview::
* Usage::
-* Intentions::
+* Limitations::
@end menu
@node Overview
@section Overview
The objective of Compat is to provide "forwards compatibility" library
-for Emacs Lisp. That is to say by using Compat, an Elisp package does
-not have to make the decision to either use new and useful
-functionality or support old versions of Emacs.
+for Emacs Lisp. By using Compat, an Elisp package does not have to
+make the decision to either use new and useful functionality or
+support old versions of Emacs.
-Version 24.4 is chosen as the oldest version we can support, since
-Elisp has seen significant changes at that version. On the library
-level subr-x was introduced in 24.4. Most popular Emacs packages
-already require 24.4 or even newer versions of Emacs.
+The library provides support back until Emacs 24.4. The intended
+audience are package developers that are interested in using newer
+developments, without having to break compatibility.
@node Usage
@section Usage
@@ -185,17 +184,29 @@ changes are made. We also provide a
list} (@email{~pkal/compat-devel@@lists.sr.ht,
~pkal/compat-devel@@lists.sr.ht}).
-@node Intentions
-@section Intentions
-
-The library intends to provide support back until Emacs 24.4. The
-intended audience are package developers that are interested in using
-newer developments, without having to break compatibility.
-
-Complete backwards compatibility cannot be provided due to the scope
-of Compat and for technical reasons. The scope is intentionally
-restricted in order to limit the size of Compat and to ensure that the
-library stays maintainable. The limitations include:
+@node Limitations
+@section Limitations
+
+The Compat library has a number of limitations. Complete backwards
+compatibility cannot be provided due to the scope of Compat and for
+technical reasons. The scope is intentionally restricted in order to
+limit the size of Compat and to ensure that the library stays
+maintainable.
+
+Emacs version 24.4 is chosen as the oldest version supported by
+Compat, since Elisp has seen significant changes at that version. On
+the library level, subr-x was introduced in 24.4. Most popular Emacs
+packages already require 24.4 or even newer versions of
+Emacs. Supporting for more historical Emacs versions would complicate
+maintainance significantly while only few packages and users would
+benefit.
+
+Below we list a number of reasons why certain functionality cannot be
+provided. Note that in some special cases exceptions can be made and
+functions can still be added to Compat even if they satisfy the
+criteria from the list. In case you miss functionality which you think
+should belong here, a @ref{Development, , report} would be much
+appreciated.
@itemize
@item
@@ -263,13 +274,6 @@ slower than the newer functionality, such that downstream
packages
would observe performance bugs. Examples are the
@code{string-pixel-width} function and the @code{json-parse-string}
function provided by libjansson.
-
-@item
-It just was not added without a good reason. If you happen to find
-such a function, @ref{Development, , reporting} it would be much
-appreciated. Note that in some special cases exceptions can be made
-and functions can still be added even if they satisfy the
-aforementioned criteria.
@end itemize
@node Support
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [elpa] externals/compat 314e897648: Manual: Add section about limitations,
ELPA Syncer <=