emacs-27 08c042b: Document that 'byte-compile-dynamic' is obsolete

[Eli Zaretskii]

branch: emacs-27
commit 08c042bd26f9a194a25aef241f8747ce47ac2798
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    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.
---
 doc/lispref/compile.texi | 6 +++++-
 etc/NEWS                 | 5 +++--
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 311b6f5..e979fda 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 0239476..6b2de77 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