Deprecate use of the INITIAL argument for completing-read.

1 files changed, 5 insertions, 0 deletions

diff --git a/lispref/minibuf.texi b/lispref/minibuf.texi
index 5d8dc146bb..0f15e02acd 100644
--- a/lispref/minibuf.texi
+++ b/lispref/minibuf.texi
@@ -697,6 +697,11 @@ into the minibuffer as part of the input.  Then it allows the user to
 edit the input, providing several commands to attempt completion.
 In most cases, we recommend using @var{default}, and not @var{initial}.
 
+@strong{We discourage use of a non-@code{nil} value for
+@var{initial}}, because it is an intrusive interface.  The history
+list (which did not exist when we introduced @var{initial}) is a far
+more convenient way for the user to get the default and edit it.
+
 If the argument @var{inherit-input-method} is non-@code{nil}, then the
 minibuffer inherits the current input method (@pxref{Input
 Methods}) and the setting of @code{enable-multibyte-characters}