Document that 'byte-compile-dynamic' is obsolete

* doc/lispref/compile.texi (Dynamic Loading): Document that this
is deprecated.

* etc/NEWS: mark the 'byte-compile-dynamic' entry as documented.

2 files changed, 8 insertions, 3 deletions

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 311b6f5b3fb..e979fda41eb 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -302,7 +302,7 @@ function is called, it reads the full definition from the file, to
 replace the place-holder.
 
   The advantage of dynamic function loading is that loading the file
-becomes much faster.  This is a good thing for a file which contains
+should become faster.  This is a good thing for a file which contains
 many separate user-callable functions, if using one of them does not
 imply you will probably also use the rest.  A specialized mode which
 provides many keyboard commands often has that usage pattern: a user may
@@ -326,6 +326,10 @@ installed Emacs files.  But they are quite likely to happen with Lisp
 files that you are changing.  The easiest way to prevent these problems
 is to reload the new compiled file immediately after each recompilation.
 
+  @emph{Experience shows that using dynamic function loading provides
+benefits that are hardly measurable, so this feature is deprecated
+since Emacs 27.1.}
+
   The byte compiler uses the dynamic function loading feature if the
 variable @code{byte-compile-dynamic} is non-@code{nil} at compilation
 time.  Do not set this variable globally, since dynamic loading is
diff --git a/etc/NEWS b/etc/NEWS
index 02394768066..6b2de77f1bb 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -803,10 +803,11 @@ You can use this new user option to control indentation of arguments of
 
 ** byte compiler
 
++++
 *** 'byte-compile-dynamic' is now obsolete.
 This is because on the one hand it suffers from misbehavior in corner
-cases that have plagued it for years, and on the other experiments indicated
-that it doesn't bring any measurable benefit.
+cases that have plagued it for years, and on the other hand experience
+indicates that it doesn't bring any measurable benefit.
 
 ---
 *** The 'g' keystroke in "*Compile-Log*" buffers has been bound to a