X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/1a941d6c9eab9a35682408d6b85a1a98cfb6b01d..81deba3d7a2b187d58fe26bd8b4eafb5687095e1:/doc/lispref/minibuf.texi

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index fa4ee04c76..24c7559c7d 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -102,8 +102,8 @@ the minibuffer is in a separate frame.  @xref{Minibuffers and Frames}.
   When Emacs is running in batch mode, any request to read from the
 minibuffer actually reads a line from the standard input descriptor that
 was supplied when Emacs was started.  This supports only basic input:
-none of the special minibuffer features (history, completion,
-password hiding, etc.) are available in batch mode.
+none of the special minibuffer features (history, completion, etc.)@:
+are available in batch mode.
 
 @node Text from Minibuffer
 @section Reading Text Strings with the Minibuffer
@@ -1738,7 +1738,7 @@ possible match, and ignore the match if the predicate returns
 
 @item
 A flag specifying the type of completion operation to perform.  This
-is one of the following four values:
+flag may be one of the following values.
 
 @table @code
 @item nil
@@ -1877,11 +1877,34 @@ next function in @code{completion-at-point-functions} instead of
 reporting a completion failure.
 @end table
 
+Supplying a function for @var{collection} is strongly recommended if
+generating the list of completions is an expensive operation.  Emacs
+may internally call functions in @code{completion-at-point-functions}
+many times, but care about the value of @var{collection} for only some
+of these calls.  By supplying a function for @var{collection}, Emacs
+can defer generating completions until necessary.  You can use
+@var{completion-table-dynamic} to create a wrapper function:
+
+@smallexample
+;; Avoid this pattern.
+(let ((beg ...) (end ...) (my-completions (my-make-completions)))
+  (list beg end my-completions))
+
+;; Use this instead.
+(let ((beg ...) (end ...))
+  (list beg
+        end
+        (completion-table-dynamic
+          (lambda (_)
+            (my-make-completions)))))
+@end smallexample
+
 A function in @code{completion-at-point-functions} may also return a
-function.  In that case, that returned function is called, with no
-argument, and it is entirely responsible for performing the
-completion.  We discourage this usage; it is intended to help convert
-old code to using @code{completion-at-point}.
+function instead of a list as described above.  In that case, that
+returned function is called, with no argument, and it is entirely
+responsible for performing the completion.  We discourage this usage;
+it is intended to help convert old code to using
+@code{completion-at-point}.
 
 The first function in @code{completion-at-point-functions} to return a
 non-@code{nil} value is used by @code{completion-at-point}.  The
@@ -2127,9 +2150,10 @@ function @code{read-passwd}.
 
 @defun read-passwd prompt &optional confirm default
 This function reads a password, prompting with @var{prompt}.  It does
-not echo the password as the user types it; instead, it echoes @samp{.}
-for each character in the password.  (Note that in batch mode, the
-input is not hidden.)
+not echo the password as the user types it; instead, it echoes
+@samp{.}  for each character in the password.  If you want to apply
+another character to hide the password, let-bind the variable
+@code{read-hide-char} with that character.
 
 The optional argument @var{confirm}, if non-@code{nil}, says to read the
 password twice and insist it must be the same both times.  If it isn't
@@ -2197,8 +2221,8 @@ contents of the minibuffer before the point.
 @section Minibuffer Windows
 @cindex minibuffer windows
 
-  These functions access and select minibuffer windows
-and test whether they are active.
+These functions access and select minibuffer windows, test whether they
+are active and control how they get resized.
 
 @defun active-minibuffer-window
 This function returns the currently active minibuffer window, or
@@ -2239,6 +2263,29 @@ This function returns non-@code{nil} if @var{window} is the currently
 active minibuffer window.
 @end defun
 
+The following two options control whether minibuffer windows are resized
+automatically and how large they can get in the process.
+
+@defopt resize-mini-windows
+This option specifies whether minibuffer windows are resized
+automatically.  The default value is @code{grow-only}, which means that
+a minibuffer window by default expands automatically to accommodate the
+text it displays and shrinks back to one line as soon as the minibuffer
+gets empty.  If the value is @code{t}, Emacs will always try to fit the
+height of a minibuffer window to the text it displays (with a minimum of
+one line).  If the value is @code{nil}, a minibuffer window never
+changes size automatically.  In that case the window resizing commands
+(@pxref{Resizing Windows}) can be used to adjust its height.
+@end defopt
+
+@defopt max-mini-window-height
+This option provides a maximum height for resizing minibuffer windows
+automatically.  A floating-point number specifies a fraction of the
+frame's height; an integer specifies the maximum number of lines.  The
+default value is 0.25.
+@end defopt
+
+
 @node Minibuffer Contents
 @section Minibuffer Contents
 @cindex access minibuffer contents