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
@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
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
@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
@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
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