reading the arguments for a command, in the @code{interactive}
specification. @xref{Defining Commands}.
-@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method keep-all
+@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method
This function is the most general way to get input through the
minibuffer. By default, it accepts arbitrary text and returns it as a
string; however, if @var{read} is non-@code{nil}, then it uses
Representations}) from whichever buffer was current before entering the
minibuffer.
-If @var{keep-all} is non-@code{nil}, even empty and duplicate inputs
-are added to the history list.
-
Use of @var{initial-contents} is mostly deprecated; we recommend using
a non-@code{nil} value only in conjunction with specifying a cons cell
for @var{hist}. @xref{Initial Input}.
history list symbol. The variable @code{history-delete-duplicates}
specifies whether to delete duplicates in history.
-@defun add-to-history history-var newelt &optional maxelt keep-dups
-This function adds a new element @var{newelt} to the history list
-stored in the variable @var{history-var}, and returns the updated
-history list. By default, the list length is limited by the value
-specified by @code{history-length} (described below), but the optional
-argument @var{maxelt} overrides that. The possible values of
-@var{maxelt} have the same meaning as the values of
-@code{history-length}.
-
-Duplicate members are removed from the history list, unless
-@code{history-delete-duplicates} is @code{nil} or the second optional
-argument of this function @var{keep-dups} is non-@code{nil}.
+@defun add-to-history history-var newelt &optional maxelt keep-all
+This function adds a new element @var{newelt}, if it isn't the empty
+string, to the history list stored in the variable @var{history-var},
+and returns the updated history list. It limits the list length to
+the value of @var{maxelt} (if non-@code{nil}) or @code{history-length}
+(described below). The possible values of @var{maxelt} have the same
+meaning as the values of @code{history-length}.
+
+Normally, @code{add-to-history} removes duplicate members from the
+history list if @code{history-delete-duplicates} is non-@code{nil}.
+However, if @var{keep-all} is non-@code{nil}, that says not to remove
+duplicates, and to add @var{newelt} to the list even if it is empty.
@end defun
+@defvar history-add-new-input
+If the value of this variable is @code{nil}, standard functions that
+read from the minibuffer don't add new elements to the history list.
+This lets Lisp programs explicitly manage input history by using
+@code{add-to-history}. By default, @code{history-add-new-input} is
+set to a non-@code{nil} value.
+@end defvar
+
@defvar history-length
The value of this variable specifies the maximum length for all
history lists that don't specify their own maximum lengths. If the
Several of the functions for minibuffer input have an argument called
@var{initial} or @var{initial-contents}. This is a mostly-deprecated
-feature for specifiying that the minibuffer should start out with
+feature for specifying that the minibuffer should start out with
certain text, instead of empty as usual.
If @var{initial} is a string, the minibuffer starts out containing the
If the user then types @kbd{fill-p @key{RET}}, @code{read-variable}
returns @code{fill-prefix}.
-This function is similar to @code{read-command}, but uses the
-predicate @code{user-variable-p} instead of @code{commandp}:
+In general, @code{read-variable} is similar to @code{read-command},
+but uses the predicate @code{user-variable-p} instead of
+@code{commandp}:
@cindex @code{user-variable-p} example
@example
@var{existing} is @code{nil}, then the name of a nonexistent file is
acceptable.
-The function @code{read-file-name} uses
+@code{read-file-name} uses
@code{minibuffer-local-filename-completion-map} as the keymap if
@var{existing} is @code{nil}, and uses
@code{minibuffer-local-must-match-filename-map} if @var{existing} is
@end defun
@defun minibuffer-prompt-end
-@tindex minibuffer-prompt-end
This function returns the current
position of the end of the minibuffer prompt, if a minibuffer is
current. Otherwise, it returns the minimum valid buffer position.
@end defun
@defun minibuffer-contents
-@tindex minibuffer-contents
This function returns the editable
contents of the minibuffer (that is, everything except the prompt) as
a string, if a minibuffer is current. Otherwise, it returns the
@end defun
@defun minibuffer-contents-no-properties
-@tindex minibuffer-contents-no-properties
This is like @code{minibuffer-contents}, except that it does not copy text
properties, just the characters themselves. @xref{Text Properties}.
@end defun
@defun minibuffer-completion-contents
-@tindex minibuffer-completion-contents
This is like @code{minibuffer-contents}, except that it returns only
the contents before point. That is the part that completion commands
operate on. @xref{Minibuffer Completion}.
@end defun
@defun delete-minibuffer-contents
-@tindex delete-minibuffer-contents
This function erases the editable contents of the minibuffer (that is,
everything except the prompt), if a minibuffer is current. Otherwise,
it erases the entire current buffer.