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.

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 311b6f5b3fb14bb6fb201ba5252150b58d3bd6ea..e979fda41eb073e519c3c97cc3d2fe60f91e5f2c 100644 (file)
--- 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 02394768066f2f82b87210ee4651e7510c8b9d12..6b2de77f1bbe476280a738cf50aecce5f70f4dc7 100644 (file)
--- 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