[elpa] externals/compat 3cb6624b61: Manual: Clarify limitations of the library

[ELPA Syncer]

branch: externals/compat
commit 3cb6624b61ad757ab9c0ec56140e1d78a58e8ed3
Author: Daniel Mendler <mail@daniel-mendler.de>
Commit: Daniel Mendler <mail@daniel-mendler.de>

    Manual: Clarify limitations of the library
---
 compat.texi | 48 +++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 37 insertions(+), 11 deletions(-)

diff --git a/compat.texi b/compat.texi
index b2f4878d84..f1aa74faeb 100644
--- a/compat.texi
+++ b/compat.texi
@@ -193,7 +193,9 @@ 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.  These might include:
+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:
 
 @itemize
 @item
@@ -203,6 +205,18 @@ level''.  Generally functions provided by Compat are 
non-interactive,
 such that the user interface (M-x) is unaffected by the presence of
 Compat.
 
+@item
+The function is not useful for package authors or not intended to be
+used by packages, but is only useful on the configuration level.  The
+macro @code{setopt} is such an example.
+
+@item
+The added or extended function belongs to the ``application level''
+and not the ``library level''.  Features which not preloaded often
+belong to the ``application level''.  Application examples are
+programming modes or modes like Dired, IRC and Gnus.  If these modes
+are extended with new functions, these are not ported back.
+
 @item
 An existing function or macro was extended by some new functionality.
 To support these cases, the function or macro would have to be
@@ -210,19 +224,30 @@ advised. Since this is invasive and adds significant 
overhead, even
 when the new feature is not used, Compat does not use advices.  As a
 compromise, compatibility functions and macros with a changed calling
 convention or behavior can be accessed via the @code{compat-function}
-and @code{compat-call} macros.
+and @code{compat-call} macros. An example is the function
+@code{plist-get}.
 
 @item
-New functionality was implemented in the C core, and depends on
-external libraries that cannot be reasonably duplicated in the scope
-of a compatibility library.
+Bug fixes are usually not ported back as part of Compat.  Sometimes
+library functions show wrong behavior for edge cases.  In those cases
+Compat could in principle provide a compatibility function which is
+invoked via @code{compat-call}. Such extended definitions would
+increase the maintainance burden of Compat. At the same time the
+benefits would be small given that Compat does not override existing
+definitions.
 
 @item
 New functionality depends on an entire new, non-trivial library.
-Sometimes these are provided via ELPA (xref, project, @dots{}), but
-other times it would be infeasible to duplicate an entire library
-within Compat while also providing the necessary backwards
-compatibility.
+Sometimes these are provided via ELPA (xref, project, seq, map,
+@dots{}), but other times it would be infeasible to duplicate an
+entire library within Compat while also providing the necessary
+backwards compatibility.
+
+@item
+New functionality was implemented in the C core, and depends on
+external libraries that cannot be reasonably duplicated in the scope
+of a compatibility library. For example a missing libxml cannot be
+emulated.
 
 @item
 The semantics of Elisp changed on a deep level. For example the
@@ -242,8 +267,9 @@ 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. Always begin by assuming that this might be the case,
-unless proven otherwise.
+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