emacs-27 e1ce9f3 1/2: Don't recommend using 'module-load' for loading modules.

[Philipp Stephani]

branch: emacs-27
commit e1ce9f34239f0c0d1940223d135797d98f65672d
Author: Philipp Stephani <address@hidden>
Commit: Philipp Stephani <address@hidden>

    Don't recommend using 'module-load' for loading modules.
    
    'module-load' most likely doesn't do what users expect.  Users should
    use 'load' and its wrappers, which do the right thing.
    
    * doc/lispref/loading.texi (Dynamic Modules): Document
    disadvantages of 'module-load' and recommend normal 'load' and
    its wrappers instead.
    
    * doc/lispref/internals.texi (Module Functions): Recommend
    'load' over 'module-load'.
---
 doc/lispref/internals.texi | 4 ++--
 doc/lispref/loading.texi   | 6 ++++++
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index bccdca6..c7b9e72 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -1423,8 +1423,8 @@ following simple Lisp wrapper:
 @end lisp
 
 The Lisp package which goes with your module could then load the
-module using the @code{module-load} primitive (@pxref{Dynamic
-Modules}) when the package is loaded into Emacs.
+module using the @code{load} primitive (@pxref{Dynamic Modules}) when
+the package is loaded into Emacs.
 
 @node Module Values
 @subsection Conversion Between Lisp and Module Values
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 3261e6d..3ba5fea 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -1217,6 +1217,12 @@ during the initialization.  If the initialization 
succeeds,
 @code{module-load} returns @code{t}.  Note that @var{file} must
 already have the proper file-name extension, as this function doesn't
 try looking for files with known extensions, unlike @code{load}.
+
+Unlike @code{load}, @code{module-load} doesn't record the module in
+@code{load-history}, doesn't print any messages, and doesn't protect
+against recursive loads.  Most users should therefore use @code{load},
+@code{load-file}, @code{load-library}, or @code{require} instead of
+@code{module-load}.
 @end defun
 
 Loadable modules in Emacs are enabled by using the