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'.

2 files changed, 8 insertions, 2 deletions

diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index bccdca65e4e..c7b9e7286b3 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 3261e6d1888..3ba5fea4ca6 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