Improve documentation of 'require-with-check'

* doc/lispref/loading.texi (Named Features): Document
'require-with-check'.

* etc/NEWS: Fix wording of entry about 'require-with-check'.

(cherry picked from commit 291763feca34174290345055a6748436839f7606)

diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 125011c780f87105635d6758249c4d0f7197b5c3..d35800fb4e0f038f1442b5026b52de542ed9eb1c 100644 (file)
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -1011,6 +1011,19 @@ If loading the file succeeds but does not provide @var{feature},
 @code{require} signals an error about the missing feature.
 @end defun
 
+@defun require-with-check feature &optional filename noerror
+This function works like @code{require}, except if @var{feature} is
+already loaded (i.e.@: is already a member of the list in
+@code{features}, see below).  If @var{feature} is already loaded, this
+function checks if @var{feature} was provided by a file different from
+@var{filename}, and if so, it by default signals an error.  If the
+value of the optional argument @var{noerror} is @code{reload}, the
+function doesn't signal an error, but instead forcibly reloads
+@var{filename}; if @var{noerror} is some other non-@code{nil} value,
+the function emits a warning about @var{feature} being already
+provided by another file.
+@end defun
+
 @defun featurep feature &optional subfeature
 This function returns @code{t} if @var{feature} has been provided in
 the current Emacs session (i.e., if @var{feature} is a member of

diff --git a/etc/NEWS b/etc/NEWS
index 30e6c13ad9cfce5e3ba3db856bfc3f409c08cd43..3c4c6449bd1f91b97f5d0329ea257e436725c670 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1411,7 +1411,11 @@ the region and never want to restrict 'undo' to that region, it is
 preferable to use the existing 'undo-inhibit-region' symbol property
 instead of this variable.
 
++++
 ** New function 'require-with-check' to detect new versions shadowing.
+This is like 'require', but it checks whether the argument 'feature'
+is already loaded, in which case it either signals an error or
+forcibly reloads the file that defines the feature.
 
 +++
 ** New 'pop-up-frames' action alist entry for 'display-buffer'.