[Emacs-diffs] Changes to minibuf.texi

[Glenn Morris]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Glenn Morris <gm>       07/09/06 04:13:03

Index: minibuf.texi
===================================================================
RCS file: minibuf.texi
diff -N minibuf.texi
--- minibuf.texi        11 Apr 2007 16:27:33 -0000      1.95
+++ /dev/null   1 Jan 1970 00:00:00 -0000
@@ -1,1964 +0,0 @@
address@hidden -*-texinfo-*-
address@hidden This is part of the GNU Emacs Lisp Reference Manual.
address@hidden Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 
2001, 2002,
address@hidden   2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
address@hidden See the file elisp.texi for copying conditions.
address@hidden ../info/minibuf
address@hidden Minibuffers, Command Loop, Read and Print, Top
address@hidden Minibuffers
address@hidden arguments, reading
address@hidden complex arguments
address@hidden minibuffer
-
-  A @dfn{minibuffer} is a special buffer that Emacs commands use to
-read arguments more complicated than the single numeric prefix
-argument.  These arguments include file names, buffer names, and
-command names (as in @kbd{M-x}).  The minibuffer is displayed on the
-bottom line of the frame, in the same place as the echo area
-(@pxref{The Echo Area}), but only while it is in use for reading an
-argument.
-
address@hidden
-* Intro to Minibuffers::      Basic information about minibuffers.
-* Text from Minibuffer::      How to read a straight text string.
-* Object from Minibuffer::    How to read a Lisp object or expression.
-* Minibuffer History::       Recording previous minibuffer inputs
-                               so the user can reuse them.
-* Initial Input::             Specifying initial contents for the minibuffer.
-* Completion::                How to invoke and customize completion.
-* Yes-or-No Queries::         Asking a question with a simple answer.
-* Multiple Queries::         Asking a series of similar questions.
-* Reading a Password::       Reading a password from the terminal.
-* Minibuffer Commands::       Commands used as key bindings in minibuffers.
-* Minibuffer Contents::       How such commands access the minibuffer text.
-* Minibuffer Windows::        Operating on the special minibuffer windows.
-* Recursive Mini::            Whether recursive entry to minibuffer is allowed.
-* Minibuffer Misc::           Various customization hooks and variables.
address@hidden menu
-
address@hidden Intro to Minibuffers
address@hidden Introduction to Minibuffers
-
-  In most ways, a minibuffer is a normal Emacs buffer.  Most operations
address@hidden a buffer, such as editing commands, work normally in a
-minibuffer.  However, many operations for managing buffers do not apply
-to minibuffers.  The name of a minibuffer always has the form @address@hidden
address@hidden, and it cannot be changed.  Minibuffers are
-displayed only in special windows used only for minibuffers; these
-windows always appear at the bottom of a frame.  (Sometimes frames have
-no minibuffer window, and sometimes a special kind of frame contains
-nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
-
-  The text in the minibuffer always starts with the @dfn{prompt string},
-the text that was specified by the program that is using the minibuffer
-to tell the user what sort of input to type.  This text is marked
-read-only so you won't accidentally delete or change it.  It is also
-marked as a field (@pxref{Fields}), so that certain motion functions,
-including @code{beginning-of-line}, @code{forward-word},
address@hidden, and @code{forward-paragraph}, stop at the
-boundary between the prompt and the actual text.  (In older Emacs
-versions, the prompt was displayed using a special mechanism and was not
-part of the buffer contents.)
-
-  The minibuffer's window is normally a single line; it grows
-automatically if necessary if the contents require more space.  You can
-explicitly resize it temporarily with the window sizing commands; it
-reverts to its normal size when the minibuffer is exited.  You can
-resize it permanently by using the window sizing commands in the frame's
-other window, when the minibuffer is not active.  If the frame contains
-just a minibuffer, you can change the minibuffer's size by changing the
-frame's size.
-
-  Use of the minibuffer reads input events, and that alters the values
-of variables such as @code{this-command} and @code{last-command}
-(@pxref{Command Loop Info}).  Your program should bind them around the
-code that uses the minibuffer, if you do not want that to change them.
-
-  If a command uses a minibuffer while there is an active minibuffer,
-this is called a @dfn{recursive minibuffer}.  The first minibuffer is
-named @address@hidden *Minibuf-0*}}.  Recursive minibuffers are named by
-incrementing the number at the end of the name.  (The names begin with a
-space so that they won't show up in normal buffer lists.)  Of several
-recursive minibuffers, the innermost (or most recently entered) is the
-active minibuffer.  We usually call this ``the'' minibuffer.  You can
-permit or forbid recursive minibuffers by setting the variable
address@hidden or by putting properties of that
-name on command symbols (@pxref{Recursive Mini}).
-
-  Like other buffers, a minibuffer uses a local keymap
-(@pxref{Keymaps}) to specify special key bindings.  The function that
-invokes the minibuffer also sets up its local map according to the job
-to be done.  @xref{Text from Minibuffer}, for the non-completion
-minibuffer local maps.  @xref{Completion Commands}, for the minibuffer
-local maps for completion.
-
-  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.
-
address@hidden Text from Minibuffer
address@hidden Reading Text Strings with the Minibuffer
-
-  Most often, the minibuffer is used to read text as a string.  It can
-also be used to read a Lisp object in textual form.  The most basic
-primitive for minibuffer input is @code{read-from-minibuffer}; it can do
-either one.  There are also specialized commands for reading
-commands, variables, file names, etc. (@pxref{Completion}).
-
-  In most cases, you should not call minibuffer input functions in the
-middle of a Lisp function.  Instead, do all minibuffer input as part of
-reading the arguments for a command, in the @code{interactive}
-specification.  @xref{Defining Commands}.
-
address@hidden 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 address@hidden, then it uses
address@hidden to convert the text into a Lisp object (@pxref{Input
-Functions}).
-
-The first thing this function does is to activate a minibuffer and
-display it with @var{prompt-string} as the prompt.  This value must be a
-string.  Then the user can edit text in the minibuffer.
-
-When the user types a command to exit the minibuffer,
address@hidden constructs the return value from the text in
-the minibuffer.  Normally it returns a string containing that text.
-However, if @var{read} is address@hidden, @code{read-from-minibuffer}
-reads the text and returns the resulting Lisp object, unevaluated.
-(@xref{Input Functions}, for information about reading.)
-
-The argument @var{default} specifies a default value to make available
-through the history commands.  It should be a string, or @code{nil}.
-If address@hidden, the user can access it using
address@hidden, usually bound in the minibuffer to
address@hidden  If @var{read} is address@hidden, then @var{default} is
-also used as the input to @code{read}, if the user enters empty input.
-(If @var{read} is address@hidden and @var{default} is @code{nil}, empty
-input results in an @code{end-of-file} error.)  However, in the usual
-case (where @var{read} is @code{nil}), @code{read-from-minibuffer}
-ignores @var{default} when the user enters empty input and returns an
-empty string, @code{""}.  In this respect, it is different from all
-the other minibuffer input functions in this chapter.
-
-If @var{keymap} is address@hidden, that keymap is the local keymap to
-use in the minibuffer.  If @var{keymap} is omitted or @code{nil}, the
-value of @code{minibuffer-local-map} is used as the keymap.  Specifying
-a keymap is the most important way to customize the minibuffer for
-various applications such as completion.
-
-The argument @var{hist} specifies which history list variable to use
-for saving the input and for history commands used in the minibuffer.
-It defaults to @code{minibuffer-history}.  @xref{Minibuffer History}.
-
-If the variable @code{minibuffer-allow-text-properties} is
address@hidden, then the string which is returned includes whatever text
-properties were present in the minibuffer.  Otherwise all the text
-properties are stripped when the value is returned.
-
-If the argument @var{inherit-input-method} is address@hidden, then the
-minibuffer inherits the current input method (@pxref{Input Methods}) and
-the setting of @code{enable-multibyte-characters} (@pxref{Text
-Representations}) from whichever buffer was current before entering the
-minibuffer.
-
-Use of @var{initial-contents} is mostly deprecated; we recommend using
-a address@hidden value only in conjunction with specifying a cons cell
-for @var{hist}.  @xref{Initial Input}.
address@hidden defun
-
address@hidden read-string prompt &optional initial history default 
inherit-input-method
-This function reads a string from the minibuffer and returns it.  The
-arguments @var{prompt}, @var{initial}, @var{history} and
address@hidden are used as in @code{read-from-minibuffer}.
-The keymap used is @code{minibuffer-local-map}.
-
-The optional argument @var{default} is used as in
address@hidden, except that, if address@hidden, it also
-specifies a default value to return if the user enters null input.  As
-in @code{read-from-minibuffer} it should be a string, or @code{nil},
-which is equivalent to an empty string.
-
-This function is a simplified interface to the
address@hidden function:
-
address@hidden
address@hidden
-(read-string @var{prompt} @var{initial} @var{history} @var{default} 
@var{inherit})
address@hidden
-(let ((value
-       (read-from-minibuffer @var{prompt} @var{initial} nil nil
-                             @var{history} @var{default} @var{inherit})))
-  (if (and (equal value "") @var{default})
-      @var{default}
-    value))
address@hidden group
address@hidden smallexample
address@hidden defun
-
address@hidden minibuffer-allow-text-properties
-If this variable is @code{nil}, then @code{read-from-minibuffer} strips
-all text properties from the minibuffer input before returning it.
-This variable also affects @code{read-string}.  However,
address@hidden (see below), as well as
address@hidden and related functions (@pxref{Object from
-Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all
-functions that do minibuffer input with completion, discard text
-properties unconditionally, regardless of the value of this variable.
address@hidden defvar
-
address@hidden minibuffer-local-map
-This
address@hidden of minibuffer-local-map}
address@hidden avoid page break at anchor; work around Texinfo deficiency
-is the default local keymap for reading from the minibuffer.  By
-default, it makes the following bindings:
-
address@hidden @asis
address@hidden @kbd{C-j}
address@hidden
-
address@hidden @key{RET}
address@hidden
-
address@hidden @kbd{C-g}
address@hidden
-
address@hidden @kbd{M-n}
address@hidden @key{DOWN}
address@hidden
-
address@hidden @kbd{M-p}
address@hidden @key{UP}
address@hidden
-
address@hidden @kbd{M-s}
address@hidden
-
address@hidden @kbd{M-r}
address@hidden
address@hidden table
address@hidden defvar
-
address@hidden In version 18, initial is required
address@hidden Emacs 19 feature
address@hidden read-no-blanks-input prompt &optional initial 
inherit-input-method
-This function reads a string from the minibuffer, but does not allow
-whitespace characters as part of the input: instead, those characters
-terminate the input.  The arguments @var{prompt}, @var{initial}, and
address@hidden are used as in @code{read-from-minibuffer}.
-
-This is a simplified interface to the @code{read-from-minibuffer}
-function, and passes the value of the @code{minibuffer-local-ns-map}
-keymap as the @var{keymap} argument for that function.  Since the keymap
address@hidden does not rebind @kbd{C-q}, it @emph{is}
-possible to put a space into the string, by quoting it.
-
-This function discards text properties, regardless of the value of
address@hidden
-
address@hidden
address@hidden
-(read-no-blanks-input @var{prompt} @var{initial})
address@hidden
-(let (minibuffer-allow-text-properties)
-  (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map))
address@hidden group
address@hidden smallexample
address@hidden defun
-
address@hidden minibuffer-local-ns-map
-This built-in variable is the keymap used as the minibuffer local keymap
-in the function @code{read-no-blanks-input}.  By default, it makes the
-following bindings, in addition to those of @code{minibuffer-local-map}:
-
address@hidden @asis
address@hidden @key{SPC}
address@hidden @key{SPC} in minibuffer
address@hidden
-
address@hidden @key{TAB}
address@hidden @key{TAB} in minibuffer
address@hidden
-
address@hidden @kbd{?}
address@hidden @kbd{?} in minibuffer
address@hidden
address@hidden table
address@hidden defvar
-
address@hidden Object from Minibuffer
address@hidden Reading Lisp Objects with the Minibuffer
-
-  This section describes functions for reading Lisp objects with the
-minibuffer.
-
address@hidden read-minibuffer prompt &optional initial
-This function reads a Lisp object using the minibuffer, and returns it
-without evaluating it.  The arguments @var{prompt} and @var{initial} are
-used as in @code{read-from-minibuffer}.
-
-This is a simplified interface to the
address@hidden function:
-
address@hidden
address@hidden
-(read-minibuffer @var{prompt} @var{initial})
address@hidden
-(let (minibuffer-allow-text-properties)
-  (read-from-minibuffer @var{prompt} @var{initial} nil t))
address@hidden group
address@hidden smallexample
-
-Here is an example in which we supply the string @code{"(testing)"} as
-initial input:
-
address@hidden
address@hidden
-(read-minibuffer
- "Enter an expression: " (format "%s" '(testing)))
-
-;; @r{Here is how the minibuffer is displayed:}
address@hidden group
-
address@hidden
----------- Buffer: Minibuffer ----------
-Enter an expression: (testing)@point{}
----------- Buffer: Minibuffer ----------
address@hidden group
address@hidden smallexample
-
address@hidden
-The user can type @key{RET} immediately to use the initial input as a
-default, or can edit the input.
address@hidden defun
-
address@hidden eval-minibuffer prompt &optional initial
-This function reads a Lisp expression using the minibuffer, evaluates
-it, then returns the result.  The arguments @var{prompt} and
address@hidden are used as in @code{read-from-minibuffer}.
-
-This function simply evaluates the result of a call to
address@hidden:
-
address@hidden
address@hidden
-(eval-minibuffer @var{prompt} @var{initial})
address@hidden
-(eval (read-minibuffer @var{prompt} @var{initial}))
address@hidden group
address@hidden smallexample
address@hidden defun
-
address@hidden edit-and-eval-command prompt form
-This function reads a Lisp expression in the minibuffer, and then
-evaluates it.  The difference between this command and
address@hidden is that here the initial @var{form} is not
-optional and it is treated as a Lisp object to be converted to printed
-representation rather than as a string of text.  It is printed with
address@hidden, so if it is a string, double-quote characters (@samp{"})
-appear in the initial text.  @xref{Output Functions}.
-
-The first thing @code{edit-and-eval-command} does is to activate the
-minibuffer with @var{prompt} as the prompt.  Then it inserts the printed
-representation of @var{form} in the minibuffer, and lets the user edit it.
-When the user exits the minibuffer, the edited text is read with
address@hidden and then evaluated.  The resulting value becomes the value
-of @code{edit-and-eval-command}.
-
-In the following example, we offer the user an expression with initial
-text which is a valid form already:
-
address@hidden
address@hidden
-(edit-and-eval-command "Please edit: " '(forward-word 1))
-
-;; @r{After evaluation of the preceding expression,}
-;;   @r{the following appears in the minibuffer:}
address@hidden group
-
address@hidden
----------- Buffer: Minibuffer ----------
-Please edit: (forward-word 1)@point{}
----------- Buffer: Minibuffer ----------
address@hidden group
address@hidden smallexample
-
address@hidden
-Typing @key{RET} right away would exit the minibuffer and evaluate the
-expression, thus moving point forward one word.
address@hidden returns @code{nil} in this example.
address@hidden defun
-
address@hidden Minibuffer History
address@hidden Minibuffer History
address@hidden minibuffer history
address@hidden history list
-
-  A @dfn{minibuffer history list} records previous minibuffer inputs so
-the user can reuse them conveniently.  A history list is actually a
-symbol, not a list; it is a variable whose value is a list of strings
-(previous inputs), most recent first.
-
-  There are many separate history lists, used for different kinds of
-inputs.  It's the Lisp programmer's job to specify the right history
-list for each use of the minibuffer.
-
-  You specify the history list with the optional @var{hist} argument
-to either @code{read-from-minibuffer} or @code{completing-read}.  Here
-are the possible values for it:
-
address@hidden @asis
address@hidden @var{variable}
-Use @var{variable} (a symbol) as the history list.
-
address@hidden (@var{variable} . @var{startpos})
-Use @var{variable} (a symbol) as the history list, and assume that the
-initial history position is @var{startpos} (a nonnegative integer).
-
-Specifying 0 for @var{startpos} is equivalent to just specifying the
-symbol @var{variable}.  @code{previous-history-element} will display
-the most recent element of the history list in the minibuffer.  If you
-specify a positive @var{startpos}, the minibuffer history functions
-behave as if @code{(elt @var{variable} (1- @var{STARTPOS}))} were the
-history element currently shown in the minibuffer.
-
-For consistency, you should also specify that element of the history
-as the initial minibuffer contents, using the @var{initial} argument
-to the minibuffer input function (@pxref{Initial Input}).
address@hidden table
-
-  If you don't specify @var{hist}, then the default history list
address@hidden is used.  For other standard history lists,
-see below.  You can also create your own history list variable; just
-initialize it to @code{nil} before the first use.
-
-  Both @code{read-from-minibuffer} and @code{completing-read} add new
-elements to the history list automatically, and provide commands to
-allow the user to reuse items on the list.  The only thing your program
-needs to do to use a history list is to initialize it and to pass its
-name to the input functions when you wish.  But it is safe to modify the
-list by hand when the minibuffer input functions are not using it.
-
-  Emacs functions that add a new element to a history list can also
-delete old elements if the list gets too long.  The variable
address@hidden specifies the maximum length for most history
-lists.  To specify a different maximum length for a particular history
-list, put the length in the @code{history-length} property of the
-history list symbol.  The variable @code{history-delete-duplicates}
-specifies whether to delete duplicates in history.
-
address@hidden 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 address@hidden) 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 address@hidden
-However, if @var{keep-all} is address@hidden, that says not to remove
-duplicates, and to add @var{newelt} to the list even if it is empty.
address@hidden defun
-
address@hidden 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
address@hidden  By default, @code{history-add-new-input} is
-set to a address@hidden value.
address@hidden defvar
-
address@hidden 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
-value is @code{t}, that means there no maximum (don't delete old
-elements).  The value of @code{history-length} property of the history
-list variable's symbol, if set, overrides this variable for that
-particular history list.
address@hidden defvar
-
address@hidden history-delete-duplicates
-If the value of this variable is @code{t}, that means when adding a
-new history element, all previous identical elements are deleted.
address@hidden defvar
-
-  Here are some of the standard minibuffer history list variables:
-
address@hidden minibuffer-history
-The default history list for minibuffer history input.
address@hidden defvar
-
address@hidden query-replace-history
-A history list for arguments to @code{query-replace} (and similar
-arguments to other commands).
address@hidden defvar
-
address@hidden file-name-history
-A history list for file-name arguments.
address@hidden defvar
-
address@hidden buffer-name-history
-A history list for buffer-name arguments.
address@hidden defvar
-
address@hidden regexp-history
-A history list for regular expression arguments.
address@hidden defvar
-
address@hidden extended-command-history
-A history list for arguments that are names of extended commands.
address@hidden defvar
-
address@hidden shell-command-history
-A history list for arguments that are shell commands.
address@hidden defvar
-
address@hidden read-expression-history
-A history list for arguments that are Lisp expressions to evaluate.
address@hidden defvar
-
address@hidden Initial Input
address@hidden Initial Input
-
-Several of the functions for minibuffer input have an argument called
address@hidden or @var{initial-contents}.  This is a mostly-deprecated
-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
-text of the string, with point at the end, when the user starts to
-edit the text.  If the user simply types @key{RET} to exit the
-minibuffer, it will use the initial input string to determine the
-value to return.
-
address@hidden discourage use of a address@hidden value for
address@hidden, because initial input is an intrusive interface.
-History lists and default values provide a much more convenient method
-to offer useful default inputs to the user.
-
-There is just one situation where you should specify a string for an
address@hidden argument.  This is when you specify a cons cell for the
address@hidden or @var{history} argument.  @xref{Minibuffer History}.
-
address@hidden can also be a cons cell of the form @code{(@var{string}
-. @var{position})}.  This means to insert @var{string} in the
-minibuffer but put point at @var{position} within the string's text.
-
-As a historical accident, @var{position} was implemented
-inconsistently in different functions.  In @code{completing-read},
address@hidden's value is interpreted as origin-zero; that is, a value
-of 0 means the beginning of the string, 1 means after the first
-character, etc.  In @code{read-minibuffer}, and the other
-non-completion minibuffer input functions that support this argument,
-1 means the beginning of the string 2 means after the first character,
-etc.
-
-Use of a cons cell as the value for @var{initial} arguments is
-deprecated in user code.
-
address@hidden Completion
address@hidden Completion
address@hidden completion
-
-  @dfn{Completion} is a feature that fills in the rest of a name
-starting from an abbreviation for it.  Completion works by comparing the
-user's input against a list of valid names and determining how much of
-the name is determined uniquely by what the user has typed.  For
-example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then
-type the first few letters of the name of the buffer to which you wish
-to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs
-extends the name as far as it can.
-
-  Standard Emacs commands offer completion for names of symbols, files,
-buffers, and processes; with the functions in this section, you can
-implement completion for other kinds of names.
-
-  The @code{try-completion} function is the basic primitive for
-completion: it returns the longest determined completion of a given
-initial string, with a given set of strings to match against.
-
-  The function @code{completing-read} provides a higher-level interface
-for completion.  A call to @code{completing-read} specifies how to
-determine the list of valid names.  The function then activates the
-minibuffer with a local keymap that binds a few keys to commands useful
-for completion.  Other functions provide convenient simple interfaces
-for reading certain kinds of names with completion.
-
address@hidden
-* Basic Completion::       Low-level functions for completing strings.
-                             (These are too low level to use the minibuffer.)
-* Minibuffer Completion::  Invoking the minibuffer with completion.
-* Completion Commands::    Minibuffer commands that do completion.
-* High-Level Completion::  Convenient special cases of completion
-                             (reading buffer name, file name, etc.)
-* Reading File Names::     Using completion to read file names.
-* Programmed Completion::  Writing your own completion-function.
address@hidden menu
-
address@hidden Basic Completion
address@hidden Basic Completion Functions
-
-  The completion functions @code{try-completion},
address@hidden and @code{test-completion} have nothing in
-themselves to do with minibuffers.  We describe them in this chapter
-so as to keep them near the higher-level completion features that do
-use the minibuffer.
-
-  If you store a completion alist in a variable, you should mark the
-variable as ``risky'' with a address@hidden
address@hidden property.
-
address@hidden try-completion string collection &optional predicate
-This function returns the longest common substring of all possible
-completions of @var{string} in @var{collection}.  The value of
address@hidden must be a list of strings or symbols, an alist, an
-obarray, a hash table, or a function that implements a virtual set of
-strings (see below).
-
-Completion compares @var{string} against each of the permissible
-completions specified by @var{collection}; if the beginning of the
-permissible completion equals @var{string}, it matches.  If no permissible
-completions match, @code{try-completion} returns @code{nil}.  If only
-one permissible completion matches, and the match is exact, then
address@hidden returns @code{t}.  Otherwise, the value is the
-longest initial sequence common to all the permissible completions that
-match.
-
-If @var{collection} is an alist (@pxref{Association Lists}), the
-permissible completions are the elements of the alist that are either
-strings, symbols, or conses whose @sc{car} is a string or symbol.
-Symbols are converted to strings using @code{symbol-name}.  Other
-elements of the alist are ignored. (Remember that in Emacs Lisp, the
-elements of alists do not @emph{have} to be conses.)  In particular, a
-list of strings or symbols is allowed, even though we usually do not
-think of such lists as alists.
-
address@hidden obarray in completion
-If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
-of all symbols in the obarray form the set of permissible completions.  The
-global variable @code{obarray} holds an obarray containing the names of
-all interned Lisp symbols.
-
-Note that the only valid way to make a new obarray is to create it
-empty and then add symbols to it one by one using @code{intern}.
-Also, you cannot intern a given symbol in more than one obarray.
-
-If @var{collection} is a hash table, then the keys that are strings
-are the possible completions.  Other keys are ignored.
-
-You can also use a symbol that is a function as @var{collection}.  Then
-the function is solely responsible for performing completion;
address@hidden returns whatever this function returns.  The
-function is called with three arguments: @var{string}, @var{predicate}
-and @code{nil}.  (The reason for the third argument is so that the same
-function can be used in @code{all-completions} and do the appropriate
-thing in either case.)  @xref{Programmed Completion}.
-
-If the argument @var{predicate} is address@hidden, then it must be a
-function of one argument, unless @var{collection} is a hash table, in
-which case it should be a function of two arguments.  It is used to
-test each possible match, and the match is accepted only if
address@hidden returns address@hidden  The argument given to
address@hidden is either a string or a cons cell (the @sc{car} of
-which is a string) from the alist, or a symbol (@emph{not} a symbol
-name) from the obarray.  If @var{collection} is a hash table,
address@hidden is called with two arguments, the string key and the
-associated value.
-
-In addition, to be acceptable, a completion must also match all the
-regular expressions in @code{completion-regexp-list}.  (Unless
address@hidden is a function, in which case that function has to
-handle @code{completion-regexp-list} itself.)
-
-In the first of the following examples, the string @samp{foo} is
-matched by three of the alist @sc{car}s.  All of the matches begin with
-the characters @samp{fooba}, so that is the result.  In the second
-example, there is only one possible match, and it is exact, so the value
-is @code{t}.
-
address@hidden
address@hidden
-(try-completion
- "foo"
- '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
-     @result{} "fooba"
address@hidden group
-
address@hidden
-(try-completion "foo" '(("barfoo" 2) ("foo" 3)))
-     @result{} t
address@hidden group
address@hidden smallexample
-
-In the following example, numerous symbols begin with the characters
address@hidden, and all of them begin with the word @samp{forward}.  In
-most of the symbols, this is followed with a @samp{-}, but not in all,
-so no more than @samp{forward} can be completed.
-
address@hidden
address@hidden
-(try-completion "forw" obarray)
-     @result{} "forward"
address@hidden group
address@hidden smallexample
-
-Finally, in the following example, only two of the three possible
-matches pass the predicate @code{test} (the string @samp{foobaz} is
-too short).  Both of those begin with the string @samp{foobar}.
-
address@hidden
address@hidden
-(defun test (s)
-  (> (length (car s)) 6))
-     @result{} test
address@hidden group
address@hidden
-(try-completion
- "foo"
- '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
- 'test)
-     @result{} "foobar"
address@hidden group
address@hidden smallexample
address@hidden defun
-
address@hidden all-completions string collection &optional predicate nospace
-This function returns a list of all possible completions of
address@hidden  The arguments to this function (aside from
address@hidden) are the same as those of @code{try-completion}.  Also,
-this function uses @code{completion-regexp-list} in the same way that
address@hidden does.  The optional argument @var{nospace} only
-matters if @var{string} is the empty string.  In that case, if
address@hidden is address@hidden, completions that start with a space
-are ignored.
-
-If @var{collection} is a function, it is called with three arguments:
address@hidden, @var{predicate} and @code{t}; then @code{all-completions}
-returns whatever the function returns.  @xref{Programmed Completion}.
-
-Here is an example, using the function @code{test} shown in the
-example for @code{try-completion}:
-
address@hidden
address@hidden
-(defun test (s)
-  (> (length (car s)) 6))
-     @result{} test
address@hidden group
-
address@hidden
-(all-completions
- "foo"
- '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
- 'test)
-     @result{} ("foobar1" "foobar2")
address@hidden group
address@hidden smallexample
address@hidden defun
-
address@hidden test-completion string collection &optional predicate
address@hidden of test-completion}
-This function returns address@hidden if @var{string} is a valid
-completion possibility specified by @var{collection} and
address@hidden  The arguments are the same as in
address@hidden  For instance, if @var{collection} is a list of
-strings, this is true if @var{string} appears in the list and
address@hidden is satisfied.
-
-This function uses @code{completion-regexp-list} in the same
-way that @code{try-completion} does.
-
-If @var{predicate} is address@hidden and if @var{collection} contains
-several strings that are equal to each other, as determined by
address@hidden according to @code{completion-ignore-case},
-then @var{predicate} should accept either all or none of them.
-Otherwise, the return value of @code{test-completion} is essentially
-unpredictable.
-
-If @var{collection} is a function, it is called with three arguments,
-the values @var{string}, @var{predicate} and @code{lambda}; whatever
-it returns, @code{test-completion} returns in turn.
address@hidden defun
-
address@hidden completion-ignore-case
-If the value of this variable is address@hidden, Emacs does not
-consider case significant in completion.
address@hidden defvar
-
address@hidden completion-regexp-list
-This is a list of regular expressions.  The completion functions only
-consider a completion acceptable if it matches all regular expressions
-in this list, with @code{case-fold-search} (@pxref{Searching and Case})
-bound to the value of @code{completion-ignore-case}.
address@hidden defvar
-
address@hidden lazy-completion-table var fun
-This macro provides a way to initialize the variable @var{var} as a
-collection for completion in a lazy way, not computing its actual
-contents until they are first needed.  You use this macro to produce a
-value that you store in @var{var}.  The actual computation of the
-proper value is done the first time you do completion using @var{var}.
-It is done by calling @var{fun} with no arguments.  The
-value @var{fun} returns becomes the permanent value of @var{var}.
-
-Here is an example of use:
-
address@hidden
-(defvar foo (lazy-completion-table foo make-my-alist))
address@hidden smallexample
address@hidden defmac
-
address@hidden Minibuffer Completion
address@hidden Completion and the Minibuffer
address@hidden minibuffer completion
address@hidden reading from minibuffer with completion
-
-  This section describes the basic interface for reading from the
-minibuffer with completion.
-
address@hidden completing-read prompt collection &optional predicate 
require-match initial hist default inherit-input-method
-This function reads a string in the minibuffer, assisting the user by
-providing completion.  It activates the minibuffer with prompt
address@hidden, which must be a string.
-
-The actual completion is done by passing @var{collection} and
address@hidden to the function @code{try-completion}.  This happens
-in certain commands bound in the local keymaps used for completion.
-Some of these commands also call @code{test-completion}.  Thus, if
address@hidden is address@hidden, it should be compatible with
address@hidden and @code{completion-ignore-case}.  @xref{Definition
-of test-completion}.
-
-If @var{require-match} is @code{nil}, the exit commands work regardless
-of the input in the minibuffer.  If @var{require-match} is @code{t}, the
-usual minibuffer exit commands won't exit unless the input completes to
-an element of @var{collection}.  If @var{require-match} is neither
address@hidden nor @code{t}, then the exit commands won't exit unless the
-input already in the buffer matches an element of @var{collection}.
-
-However, empty input is always permitted, regardless of the value of
address@hidden; in that case, @code{completing-read} returns
address@hidden, or @code{""}, if @var{default} is @code{nil}.  The
-value of @var{default} (if address@hidden) is also available to the
-user through the history commands.
-
-The function @code{completing-read} uses
address@hidden as the keymap if
address@hidden is @code{nil}, and uses
address@hidden if @var{require-match} is
address@hidden  @xref{Completion Commands}.
-
-The argument @var{hist} specifies which history list variable to use for
-saving the input and for minibuffer history commands.  It defaults to
address@hidden  @xref{Minibuffer History}.
-
-The argument @var{initial} is mostly deprecated; we recommend using a
address@hidden value only in conjunction with specifying a cons cell
-for @var{hist}.  @xref{Initial Input}.  For default input, use
address@hidden instead.
-
-If the argument @var{inherit-input-method} is address@hidden, then the
-minibuffer inherits the current input method (@pxref{Input
-Methods}) and the setting of @code{enable-multibyte-characters}
-(@pxref{Text Representations}) from whichever buffer was current before
-entering the minibuffer.
-
-If the built-in variable @code{completion-ignore-case} is
address@hidden, completion ignores case when comparing the input
-against the possible matches.  @xref{Basic Completion}.  In this mode
-of operation, @var{predicate} must also ignore case, or you will get
-surprising results.
-
-Here's an example of using @code{completing-read}:
-
address@hidden
address@hidden
-(completing-read
- "Complete a foo: "
- '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
- nil t "fo")
address@hidden group
-
address@hidden
-;; @r{After evaluation of the preceding expression,}
-;;   @r{the following appears in the minibuffer:}
-
----------- Buffer: Minibuffer ----------
-Complete a foo: address@hidden
----------- Buffer: Minibuffer ----------
address@hidden group
address@hidden smallexample
-
address@hidden
-If the user then types @address@hidden @key{DEL} b @key{RET}},
address@hidden returns @code{barfoo}.
-
-The @code{completing-read} function binds variables to pass
-information to the commands that actually do completion.
-They are described in the following section.
address@hidden defun
-
address@hidden Completion Commands
address@hidden Minibuffer Commands that Do Completion
-
-  This section describes the keymaps, commands and user options used
-in the minibuffer to do completion.  The description refers to the
-situation when Partial Completion mode is disabled (as it is by
-default).  When enabled, this minor mode uses its own alternatives to
-some of the commands described below.  @xref{Completion Options,,,
-emacs, The GNU Emacs Manual}, for a short description of Partial
-Completion mode.
-
address@hidden minibuffer-completion-table
-The value of this variable is the collection used for completion in
-the minibuffer.  This is the global variable that contains what
address@hidden passes to @code{try-completion}.  It is used by
-minibuffer completion commands such as @code{minibuffer-complete-word}.
address@hidden defvar
-
address@hidden minibuffer-completion-predicate
-This variable's value is the predicate that @code{completing-read}
-passes to @code{try-completion}.  The variable is also used by the other
-minibuffer completion functions.
address@hidden defvar
-
address@hidden minibuffer-completion-confirm
-When the value of this variable is address@hidden, Emacs asks for
-confirmation of a completion before exiting the minibuffer.
address@hidden binds this variable, and the function
address@hidden checks the value before exiting.
address@hidden defvar
-
address@hidden Command minibuffer-complete-word
-This function completes the minibuffer contents by at most a single
-word.  Even if the minibuffer contents have only one completion,
address@hidden does not add any characters beyond the
-first character that is not a word constituent.  @xref{Syntax Tables}.
address@hidden deffn
-
address@hidden Command minibuffer-complete
-This function completes the minibuffer contents as far as possible.
address@hidden deffn
-
address@hidden Command minibuffer-complete-and-exit
-This function completes the minibuffer contents, and exits if
-confirmation is not required, i.e., if
address@hidden is @code{nil}.  If confirmation
address@hidden required, it is given by repeating this command
-immediately---the command is programmed to work without confirmation
-when run twice in succession.
address@hidden deffn
-
address@hidden Command minibuffer-completion-help
-This function creates a list of the possible completions of the
-current minibuffer contents.  It works by calling @code{all-completions}
-using the value of the variable @code{minibuffer-completion-table} as
-the @var{collection} argument, and the value of
address@hidden as the @var{predicate} argument.
-The list of completions is displayed as text in a buffer named
address@hidden
address@hidden deffn
-
address@hidden display-completion-list completions &optional common-substring
-This function displays @var{completions} to the stream in
address@hidden, usually a buffer.  (@xref{Read and Print}, for more
-information about streams.)  The argument @var{completions} is normally
-a list of completions just returned by @code{all-completions}, but it
-does not have to be.  Each element may be a symbol or a string, either
-of which is simply printed.  It can also be a list of two strings,
-which is printed as if the strings were concatenated.  The first of
-the two strings is the actual completion, the second string serves as
-annotation.
-
-The argument @var{common-substring} is the prefix that is common to
-all the completions.  With normal Emacs completion, it is usually the
-same as the string that was completed.  @code{display-completion-list}
-uses this to highlight text in the completion list for better visual
-feedback.  This is not needed in the minibuffer; for minibuffer
-completion, you can pass @code{nil}.
-
-This function is called by @code{minibuffer-completion-help}.  The
-most common way to use it is together with
address@hidden, like this:
-
address@hidden
-(with-output-to-temp-buffer "*Completions*"
-  (display-completion-list
-    (all-completions (buffer-string) my-alist)
-    (buffer-string)))
address@hidden example
address@hidden defun
-
address@hidden completion-auto-help
-If this variable is address@hidden, the completion commands
-automatically display a list of possible completions whenever nothing
-can be completed because the next character is not uniquely determined.
address@hidden defopt
-
address@hidden minibuffer-local-completion-map
address@hidden uses this value as the local keymap when an
-exact match of one of the completions is not required.  By default, this
-keymap makes the following bindings:
-
address@hidden @asis
address@hidden @kbd{?}
address@hidden
-
address@hidden @key{SPC}
address@hidden
-
address@hidden @key{TAB}
address@hidden
address@hidden table
-
address@hidden
-with other characters bound as in @code{minibuffer-local-map}
-(@pxref{Definition of minibuffer-local-map}).
address@hidden defvar
-
address@hidden minibuffer-local-must-match-map
address@hidden uses this value as the local keymap when an
-exact match of one of the completions is required.  Therefore, no keys
-are bound to @code{exit-minibuffer}, the command that exits the
-minibuffer unconditionally.  By default, this keymap makes the following
-bindings:
-
address@hidden @asis
address@hidden @kbd{?}
address@hidden
-
address@hidden @key{SPC}
address@hidden
-
address@hidden @key{TAB}
address@hidden
-
address@hidden @kbd{C-j}
address@hidden
-
address@hidden @key{RET}
address@hidden
address@hidden table
-
address@hidden
-with other characters bound as in @code{minibuffer-local-map}.
address@hidden defvar
-
address@hidden minibuffer-local-filename-completion-map
-This is like @code{minibuffer-local-completion-map}
-except that it does not bind @key{SPC}.  This keymap is used by the
-function @code{read-file-name}.
address@hidden defvar
-
address@hidden minibuffer-local-must-match-filename-map
-This is like @code{minibuffer-local-must-match-map}
-except that it does not bind @key{SPC}.  This keymap is used by the
-function @code{read-file-name}.
address@hidden defvar
-
address@hidden High-Level Completion
address@hidden High-Level Completion  Functions
-
-  This section describes the higher-level convenient functions for
-reading certain sorts of names with completion.
-
-  In most cases, you should not call these functions in the middle of a
-Lisp function.  When possible, do all minibuffer input as part of
-reading the arguments for a command, in the @code{interactive}
-specification.  @xref{Defining Commands}.
-
address@hidden read-buffer prompt &optional default existing
-This function reads the name of a buffer and returns it as a string.
-The argument @var{default} is the default name to use, the value to
-return if the user exits with an empty minibuffer.  If address@hidden,
-it should be a string or a buffer.  It is mentioned in the prompt, but
-is not inserted in the minibuffer as initial input.
-
-The argument @var{prompt} should be a string ending with a colon and a
-space.  If @var{default} is address@hidden, the function inserts it in
address@hidden before the colon to follow the convention for reading from
-the minibuffer with a default value (@pxref{Programming Tips}).
-
-If @var{existing} is address@hidden, then the name specified must be
-that of an existing buffer.  The usual commands to exit the minibuffer
-do not exit if the text is not valid, and @key{RET} does completion to
-attempt to find a valid name.  If @var{existing} is neither @code{nil}
-nor @code{t}, confirmation is required after completion.  (However,
address@hidden is not checked for validity; it is returned, whatever it
-is, if the user exits with the minibuffer empty.)
-
-In the following example, the user enters @samp{minibuffer.t}, and
-then types @key{RET}.  The argument @var{existing} is @code{t}, and the
-only buffer name starting with the given input is
address@hidden, so that name is the value.
-
address@hidden
-(read-buffer "Buffer name: " "foo" t)
address@hidden
-;; @r{After evaluation of the preceding expression,}
-;;   @r{the following prompt appears,}
-;;   @r{with an empty minibuffer:}
address@hidden group
-
address@hidden
----------- Buffer: Minibuffer ----------
-Buffer name (default foo): @point{}
----------- Buffer: Minibuffer ----------
address@hidden group
-
address@hidden
-;; @r{The user types @kbd{minibuffer.t @key{RET}}.}
-     @result{} "minibuffer.texi"
address@hidden group
address@hidden example
address@hidden defun
-
address@hidden read-buffer-function
-This variable specifies how to read buffer names.  For example, if you
-set this variable to @code{iswitchb-read-buffer}, all Emacs commands
-that call @code{read-buffer} to read a buffer name will actually use the
address@hidden package to read it.
address@hidden defvar
-
address@hidden read-command prompt &optional default
-This function reads the name of a command and returns it as a Lisp
-symbol.  The argument @var{prompt} is used as in
address@hidden  Recall that a command is anything for
-which @code{commandp} returns @code{t}, and a command name is a symbol
-for which @code{commandp} returns @code{t}.  @xref{Interactive Call}.
-
-The argument @var{default} specifies what to return if the user enters
-null input.  It can be a symbol or a string; if it is a string,
address@hidden interns it before returning it.  If @var{default} is
address@hidden, that means no default has been specified; then if the user
-enters null input, the return value is @code{(intern "")}, that is, a
-symbol whose name is an empty string.
-
address@hidden
-(read-command "Command name? ")
-
address@hidden
-;; @r{After evaluation of the preceding expression,}
-;;   @r{the following prompt appears with an empty minibuffer:}
address@hidden group
-
address@hidden
----------- Buffer: Minibuffer ----------
-Command name?
----------- Buffer: Minibuffer ----------
address@hidden group
address@hidden example
-
address@hidden
-If the user types @kbd{forward-c @key{RET}}, then this function returns
address@hidden
-
-The @code{read-command} function is a simplified interface to
address@hidden  It uses the variable @code{obarray} so as to
-complete in the set of extant Lisp symbols, and it uses the
address@hidden predicate so as to accept only command names:
-
address@hidden @code{commandp} example
address@hidden
address@hidden
-(read-command @var{prompt})
address@hidden
-(intern (completing-read @var{prompt} obarray
-                         'commandp t nil))
address@hidden group
address@hidden example
address@hidden defun
-
address@hidden read-variable prompt &optional default
address@hidden of read-variable}
-This function reads the name of a user variable and returns it as a
-symbol.
-
-The argument @var{default} specifies what to return if the user enters
-null input.  It can be a symbol or a string; if it is a string,
address@hidden interns it before returning it.  If @var{default}
-is @code{nil}, that means no default has been specified; then if the
-user enters null input, the return value is @code{(intern "")}.
-
address@hidden
address@hidden
-(read-variable "Variable name? ")
-
-;; @r{After evaluation of the preceding expression,}
-;;   @r{the following prompt appears,}
-;;   @r{with an empty minibuffer:}
address@hidden group
-
address@hidden
----------- Buffer: Minibuffer ----------
-Variable name? @point{}
----------- Buffer: Minibuffer ----------
address@hidden group
address@hidden example
-
address@hidden
-If the user then types @kbd{fill-p @key{RET}}, @code{read-variable}
-returns @code{fill-prefix}.
-
-In general, @code{read-variable} is similar to @code{read-command},
-but uses the predicate @code{user-variable-p} instead of
address@hidden:
-
address@hidden @code{user-variable-p} example
address@hidden
address@hidden
-(read-variable @var{prompt})
address@hidden
-(intern
- (completing-read @var{prompt} obarray
-                  'user-variable-p t nil))
address@hidden group
address@hidden example
address@hidden defun
-
-  See also the functions @code{read-coding-system} and
address@hidden, in @ref{User-Chosen Coding Systems},
-and @code{read-input-method-name}, in @ref{Input Methods}.
-
address@hidden Reading File Names
address@hidden Reading File Names
address@hidden read file names
address@hidden prompt for file name
-
-  Here is another high-level completion function, designed for reading a
-file name.  It provides special features including automatic insertion
-of the default directory.
-
address@hidden read-file-name prompt &optional directory default existing 
initial predicate
-This function reads a file name in the minibuffer, prompting with
address@hidden and providing completion.
-
-If @var{existing} is address@hidden, then the user must specify the name
-of an existing file; @key{RET} performs completion to make the name
-valid if possible, and then refuses to exit if it is not valid.  If the
-value of @var{existing} is neither @code{nil} nor @code{t}, then
address@hidden also requires confirmation after completion.  If
address@hidden is @code{nil}, then the name of a nonexistent file is
-acceptable.
-
address@hidden uses
address@hidden as the keymap if
address@hidden is @code{nil}, and uses
address@hidden if @var{existing} is
address@hidden  @xref{Completion Commands}.
-
-The argument @var{directory} specifies the directory to use for
-completion of relative file names.  It should be an absolute directory
-name.  If @code{insert-default-directory} is address@hidden,
address@hidden is also inserted in the minibuffer as initial input.
-It defaults to the current buffer's value of @code{default-directory}.
-
address@hidden Emacs 19 feature
-If you specify @var{initial}, that is an initial file name to insert
-in the buffer (after @var{directory}, if that is inserted).  In this
-case, point goes at the beginning of @var{initial}.  The default for
address@hidden is @code{nil}---don't insert any file name.  To see what
address@hidden does, try the command @kbd{C-x C-v}.  @strong{Please
-note:} we recommend using @var{default} rather than @var{initial} in
-most cases.
-
-If @var{default} is address@hidden, then the function returns
address@hidden if the user exits the minibuffer with the same non-empty
-contents that @code{read-file-name} inserted initially.  The initial
-minibuffer contents are always non-empty if
address@hidden is address@hidden, as it is by
-default.  @var{default} is not checked for validity, regardless of the
-value of @var{existing}.  However, if @var{existing} is
address@hidden, the initial minibuffer contents should be a valid file
-(or directory) name.  Otherwise @code{read-file-name} attempts
-completion if the user exits without any editing, and does not return
address@hidden  @var{default} is also available through the history
-commands.
-
-If @var{default} is @code{nil}, @code{read-file-name} tries to find a
-substitute default to use in its place, which it treats in exactly the
-same way as if it had been specified explicitly.  If @var{default} is
address@hidden, but @var{initial} is address@hidden, then the default is
-the absolute file name obtained from @var{directory} and
address@hidden  If both @var{default} and @var{initial} are @code{nil}
-and the buffer is visiting a file, @code{read-file-name} uses the
-absolute file name of that file as default.  If the buffer is not
-visiting a file, then there is no default.  In that case, if the user
-types @key{RET} without any editing, @code{read-file-name} simply
-returns the pre-inserted contents of the minibuffer.
-
-If the user types @key{RET} in an empty minibuffer, this function
-returns an empty string, regardless of the value of @var{existing}.
-This is, for instance, how the user can make the current buffer visit
-no file using @code{M-x set-visited-file-name}.
-
-If @var{predicate} is address@hidden, it specifies a function of one
-argument that decides which file names are acceptable completion
-possibilities.  A file name is an acceptable value if @var{predicate}
-returns address@hidden for it.
-
address@hidden does not automatically expand file names.  You
-must call @code{expand-file-name} yourself if an absolute file name is
-required.
-
-Here is an example:
-
address@hidden
address@hidden
-(read-file-name "The file is ")
-
-;; @r{After evaluation of the preceding expression,}
-;;   @r{the following appears in the minibuffer:}
address@hidden group
-
address@hidden
----------- Buffer: Minibuffer ----------
-The file is /gp/gnu/elisp/@point{}
----------- Buffer: Minibuffer ----------
address@hidden group
address@hidden example
-
address@hidden
-Typing @kbd{manual @key{TAB}} results in the following:
-
address@hidden
address@hidden
----------- Buffer: Minibuffer ----------
-The file is /gp/gnu/elisp/address@hidden
----------- Buffer: Minibuffer ----------
address@hidden group
address@hidden example
-
address@hidden Wordy to avoid overfull hbox in smallbook mode.
address@hidden
-If the user types @key{RET}, @code{read-file-name} returns the file name
-as the string @code{"/gp/gnu/elisp/manual.texi"}.
address@hidden defun
-
address@hidden read-file-name-function
-If address@hidden, this should be a function that accepts the same
-arguments as @code{read-file-name}.  When @code{read-file-name} is
-called, it calls this function with the supplied arguments instead of
-doing its usual work.
address@hidden defvar
-
address@hidden read-file-name-completion-ignore-case
-If this variable is address@hidden, @code{read-file-name} ignores case
-when performing completion.
address@hidden defvar
-
address@hidden read-directory-name prompt &optional directory default existing 
initial
-This function is like @code{read-file-name} but allows only directory
-names as completion possibilities.
-
-If @var{default} is @code{nil} and @var{initial} is address@hidden,
address@hidden constructs a substitute default by
-combining @var{directory} (or the current buffer's default directory
-if @var{directory} is @code{nil}) and @var{initial}.  If both
address@hidden and @var{initial} are @code{nil}, this function uses
address@hidden as substitute default, or the current buffer's default
-directory if @var{directory} is @code{nil}.
address@hidden defun
-
address@hidden insert-default-directory
-This variable is used by @code{read-file-name}, and thus, indirectly,
-by most commands reading file names.  (This includes all commands that
-use the code letters @samp{f} or @samp{F} in their interactive form.
address@hidden Codes,, Code Characters for interactive}.)  Its
-value controls whether @code{read-file-name} starts by placing the
-name of the default directory in the minibuffer, plus the initial file
-name if any.  If the value of this variable is @code{nil}, then
address@hidden does not place any initial input in the
-minibuffer (unless you specify initial input with the @var{initial}
-argument).  In that case, the default directory is still used for
-completion of relative file names, but is not displayed.
-
-If this variable is @code{nil} and the initial minibuffer contents are
-empty, the user may have to explicitly fetch the next history element
-to access a default value.  If the variable is address@hidden, the
-initial minibuffer contents are always non-empty and the user can
-always request a default value by immediately typing @key{RET} in an
-unedited minibuffer.  (See above.)
-
-For example:
-
address@hidden
address@hidden
-;; @r{Here the minibuffer starts out with the default directory.}
-(let ((insert-default-directory t))
-  (read-file-name "The file is "))
address@hidden group
-
address@hidden
----------- Buffer: Minibuffer ----------
-The file is ~lewis/manual/@point{}
----------- Buffer: Minibuffer ----------
address@hidden group
-
address@hidden
-;; @r{Here the minibuffer is empty and only the prompt}
-;;   @r{appears on its line.}
-(let ((insert-default-directory nil))
-  (read-file-name "The file is "))
address@hidden group
-
address@hidden
----------- Buffer: Minibuffer ----------
-The file is @point{}
----------- Buffer: Minibuffer ----------
address@hidden group
address@hidden example
address@hidden defopt
-
address@hidden Programmed Completion
address@hidden Programmed Completion
address@hidden programmed completion
-
-  Sometimes it is not possible to create an alist or an obarray
-containing all the intended possible completions.  In such a case, you
-can supply your own function to compute the completion of a given string.
-This is called @dfn{programmed completion}.
-
-  To use this feature, pass a symbol with a function definition as the
address@hidden argument to @code{completing-read}.  The function
address@hidden arranges to pass your completion function along
-to @code{try-completion} and @code{all-completions}, which will then let
-your function do all the work.
-
-  The completion function should accept three arguments:
-
address@hidden @bullet
address@hidden
-The string to be completed.
-
address@hidden
-The predicate function to filter possible matches, or @code{nil} if
-none.  Your function should call the predicate for each possible match,
-and ignore the possible match if the predicate returns @code{nil}.
-
address@hidden
-A flag specifying the type of operation.
address@hidden itemize
-
-  There are three flag values for three operations:
-
address@hidden @bullet
address@hidden
address@hidden specifies @code{try-completion}.  The completion function
-should return the completion of the specified string, or @code{t} if the
-string is a unique and exact match already, or @code{nil} if the string
-matches no possibility.
-
-If the string is an exact match for one possibility, but also matches
-other longer possibilities, the function should return the string, not
address@hidden
-
address@hidden
address@hidden specifies @code{all-completions}.  The completion function
-should return a list of all possible completions of the specified
-string.
-
address@hidden
address@hidden specifies @code{test-completion}.  The completion
-function should return @code{t} if the specified string is an exact
-match for some possibility; @code{nil} otherwise.
address@hidden itemize
-
-  It would be consistent and clean for completion functions to allow
-lambda expressions (lists that are functions) as well as function
-symbols as @var{collection}, but this is impossible.  Lists as
-completion tables already have other meanings, and it would be
-unreliable to treat one differently just because it is also a possible
-function.  So you must arrange for any function you wish to use for
-completion to be encapsulated in a symbol.
-
-  Emacs uses programmed completion when completing file names.
address@hidden Name Completion}.
-
address@hidden dynamic-completion-table function
-This macro is a convenient way to write a function that can act as
-programmed completion function.  The argument @var{function} should be
-a function that takes one argument, a string, and returns an alist of
-possible completions of it.  You can think of
address@hidden as a transducer between that interface
-and the interface for programmed completion functions.
address@hidden defmac
-
address@hidden Yes-or-No Queries
address@hidden Yes-or-No Queries
address@hidden asking the user questions
address@hidden querying the user
address@hidden yes-or-no questions
-
-  This section describes functions used to ask the user a yes-or-no
-question.  The function @code{y-or-n-p} can be answered with a single
-character; it is useful for questions where an inadvertent wrong answer
-will not have serious consequences.  @code{yes-or-no-p} is suitable for
-more momentous questions, since it requires three or four characters to
-answer.
-
-   If either of these functions is called in a command that was invoked
-using the mouse---more precisely, if @code{last-nonmenu-event}
-(@pxref{Command Loop Info}) is either @code{nil} or a list---then it
-uses a dialog box or pop-up menu to ask the question.  Otherwise, it
-uses keyboard input.  You can force use of the mouse or use of keyboard
-input by binding @code{last-nonmenu-event} to a suitable value around
-the call.
-
-  Strictly speaking, @code{yes-or-no-p} uses the minibuffer and
address@hidden does not; but it seems best to describe them together.
-
address@hidden y-or-n-p prompt
-This function asks the user a question, expecting input in the echo
-area.  It returns @code{t} if the user types @kbd{y}, @code{nil} if the
-user types @kbd{n}.  This function also accepts @key{SPC} to mean yes
-and @key{DEL} to mean no.  It accepts @kbd{C-]} to mean ``quit,'' like
address@hidden, because the question might look like a minibuffer and for
-that reason the user might try to use @kbd{C-]} to get out.  The answer
-is a single character, with no @key{RET} needed to terminate it.  Upper
-and lower case are equivalent.
-
-``Asking the question'' means printing @var{prompt} in the echo area,
-followed by the string @address@hidden(y or n) }}.  If the input is not one of
-the expected answers (@kbd{y}, @kbd{n}, @address@hidden,
address@hidden@key{DEL}}, or something that quits), the function responds
address@hidden answer y or n.}, and repeats the request.
-
-This function does not actually use the minibuffer, since it does not
-allow editing of the answer.  It actually uses the echo area (@pxref{The
-Echo Area}), which uses the same screen space as the minibuffer.  The
-cursor moves to the echo area while the question is being asked.
-
-The answers and their meanings, even @samp{y} and @samp{n}, are not
-hardwired.  The keymap @code{query-replace-map} specifies them.
address@hidden and Replace}.
-
-In the following example, the user first types @kbd{q}, which is
-invalid.  At the next prompt the user types @kbd{y}.
-
address@hidden
address@hidden
-(y-or-n-p "Do you need a lift? ")
-
-;; @r{After evaluation of the preceding expression,}
-;;   @r{the following prompt appears in the echo area:}
address@hidden group
-
address@hidden
----------- Echo area ----------
-Do you need a lift? (y or n)
----------- Echo area ----------
address@hidden group
-
-;; @r{If the user then types @kbd{q}, the following appears:}
-
address@hidden
----------- Echo area ----------
-Please answer y or n.  Do you need a lift? (y or n)
----------- Echo area ----------
address@hidden group
-
-;; @r{When the user types a valid answer,}
-;;   @r{it is displayed after the question:}
-
address@hidden
----------- Echo area ----------
-Do you need a lift? (y or n) y
----------- Echo area ----------
address@hidden group
address@hidden smallexample
-
address@hidden
-We show successive lines of echo area messages, but only one actually
-appears on the screen at a time.
address@hidden defun
-
address@hidden y-or-n-p-with-timeout prompt seconds default-value
-Like @code{y-or-n-p}, except that if the user fails to answer within
address@hidden seconds, this function stops waiting and returns
address@hidden  It works by setting up a timer; see @ref{Timers}.
-The argument @var{seconds} may be an integer or a floating point number.
address@hidden defun
-
address@hidden yes-or-no-p prompt
-This function asks the user a question, expecting input in the
-minibuffer.  It returns @code{t} if the user enters @samp{yes},
address@hidden if the user types @samp{no}.  The user must type @key{RET} to
-finalize the response.  Upper and lower case are equivalent.
-
address@hidden starts by displaying @var{prompt} in the echo area,
-followed by @address@hidden(yes or no) }}.  The user must type one of the
-expected responses; otherwise, the function responds @samp{Please answer
-yes or no.}, waits about two seconds and repeats the request.
-
address@hidden requires more work from the user than
address@hidden and is appropriate for more crucial decisions.
-
-Here is an example:
-
address@hidden
address@hidden
-(yes-or-no-p "Do you really want to remove everything? ")
-
-;; @r{After evaluation of the preceding expression,}
-;;   @r{the following prompt appears,}
-;;   @r{with an empty minibuffer:}
address@hidden group
-
address@hidden
----------- Buffer: minibuffer ----------
-Do you really want to remove everything? (yes or no)
----------- Buffer: minibuffer ----------
address@hidden group
address@hidden smallexample
-
address@hidden
-If the user first types @kbd{y @key{RET}}, which is invalid because this
-function demands the entire word @samp{yes}, it responds by displaying
-these prompts, with a brief pause between them:
-
address@hidden
address@hidden
----------- Buffer: minibuffer ----------
-Please answer yes or no.
-Do you really want to remove everything? (yes or no)
----------- Buffer: minibuffer ----------
address@hidden group
address@hidden smallexample
address@hidden defun
-
address@hidden Multiple Queries
address@hidden Asking Multiple Y-or-N Questions
-
-  When you have a series of similar questions to ask, such as ``Do you
-want to save this buffer'' for each buffer in turn, you should use
address@hidden to ask the collection of questions, rather than
-asking each question individually.  This gives the user certain
-convenient facilities such as the ability to answer the whole series at
-once.
-
address@hidden map-y-or-n-p prompter actor list &optional help action-alist 
no-cursor-in-echo-area
-This function asks the user a series of questions, reading a
-single-character answer in the echo area for each one.
-
-The value of @var{list} specifies the objects to ask questions about.
-It should be either a list of objects or a generator function.  If it is
-a function, it should expect no arguments, and should return either the
-next object to ask about, or @code{nil} meaning stop asking questions.
-
-The argument @var{prompter} specifies how to ask each question.  If
address@hidden is a string, the question text is computed like this:
-
address@hidden
-(format @var{prompter} @var{object})
address@hidden example
-
address@hidden
-where @var{object} is the next object to ask about (as obtained from
address@hidden).
-
-If not a string, @var{prompter} should be a function of one argument
-(the next object to ask about) and should return the question text.  If
-the value is a string, that is the question to ask the user.  The
-function can also return @code{t} meaning do act on this object (and
-don't ask the user), or @code{nil} meaning ignore this object (and don't
-ask the user).
-
-The argument @var{actor} says how to act on the answers that the user
-gives.  It should be a function of one argument, and it is called with
-each object that the user says yes for.  Its argument is always an
-object obtained from @var{list}.
-
-If the argument @var{help} is given, it should be a list of this form:
-
address@hidden
-(@var{singular} @var{plural} @var{action})
address@hidden example
-
address@hidden
-where @var{singular} is a string containing a singular noun that
-describes the objects conceptually being acted on, @var{plural} is the
-corresponding plural noun, and @var{action} is a transitive verb
-describing what @var{actor} does.
-
-If you don't specify @var{help}, the default is @code{("object"
-"objects" "act on")}.
-
-Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or
address@hidden to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip
-that object; @kbd{!} to act on all following objects; @key{ESC} or
address@hidden to exit (skip all following objects); @kbd{.} (period) to act on
-the current object and then exit; or @kbd{C-h} to get help.  These are
-the same answers that @code{query-replace} accepts.  The keymap
address@hidden defines their meaning for @code{map-y-or-n-p}
-as well as for @code{query-replace}; see @ref{Search and Replace}.
-
-You can use @var{action-alist} to specify additional possible answers
-and what they mean.  It is an alist of elements of the form
address@hidden(@var{char} @var{function} @var{help})}, each of which defines one
-additional answer.  In this element, @var{char} is a character (the
-answer); @var{function} is a function of one argument (an object from
address@hidden); @var{help} is a string.
-
-When the user responds with @var{char}, @code{map-y-or-n-p} calls
address@hidden  If it returns address@hidden, the object is considered
-``acted upon,'' and @code{map-y-or-n-p} advances to the next object in
address@hidden  If it returns @code{nil}, the prompt is repeated for the
-same object.
-
-Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while
-prompting.  But if @var{no-cursor-in-echo-area} is address@hidden, it
-does not do that.
-
-If @code{map-y-or-n-p} is called in a command that was invoked using the
-mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
-Loop Info}) is either @code{nil} or a list---then it uses a dialog box
-or pop-up menu to ask the question.  In this case, it does not use
-keyboard input or the echo area.  You can force use of the mouse or use
-of keyboard input by binding @code{last-nonmenu-event} to a suitable
-value around the call.
-
-The return value of @code{map-y-or-n-p} is the number of objects acted on.
address@hidden defun
-
address@hidden Reading a Password
address@hidden Reading a Password
address@hidden passwords, reading
-
-  To read a password to pass to another program, you can use the
-function @code{read-passwd}.
-
address@hidden 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.
-
-The optional argument @var{confirm}, if address@hidden, says to read the
-password twice and insist it must be the same both times.  If it isn't
-the same, the user has to type it over and over until the last two
-times match.
-
-The optional argument @var{default} specifies the default password to
-return if the user enters empty input.  If @var{default} is @code{nil},
-then @code{read-passwd} returns the null string in that case.
address@hidden defun
-
address@hidden Minibuffer Commands
address@hidden Minibuffer Commands
-
-  This section describes some commands meant for use in the
-minibuffer.
-
address@hidden Command exit-minibuffer
-This command exits the active minibuffer.  It is normally bound to
-keys in minibuffer local keymaps.
address@hidden deffn
-
address@hidden Command self-insert-and-exit
-This command exits the active minibuffer after inserting the last
-character typed on the keyboard (found in @code{last-command-char};
address@hidden Loop Info}).
address@hidden deffn
-
address@hidden Command previous-history-element n
-This command replaces the minibuffer contents with the value of the
address@hidden previous (older) history element.
address@hidden deffn
-
address@hidden Command next-history-element n
-This command replaces the minibuffer contents with the value of the
address@hidden more recent history element.
address@hidden deffn
-
address@hidden Command previous-matching-history-element pattern n
-This command replaces the minibuffer contents with the value of the
address@hidden previous (older) history element that matches @var{pattern} (a
-regular expression).
address@hidden deffn
-
address@hidden Command next-matching-history-element pattern n
-This command replaces the minibuffer contents with the value of the
address@hidden next (newer) history element that matches @var{pattern} (a
-regular expression).
address@hidden deffn
-
address@hidden Minibuffer Windows
address@hidden Minibuffer Windows
address@hidden minibuffer windows
-
-  These functions access and select minibuffer windows
-and test whether they are active.
-
address@hidden active-minibuffer-window
-This function returns the currently active minibuffer window, or
address@hidden if none is currently active.
address@hidden defun
-
address@hidden minibuffer-window &optional frame
address@hidden of minibuffer-window}
-This function returns the minibuffer window used for frame @var{frame}.
-If @var{frame} is @code{nil}, that stands for the current frame.  Note
-that the minibuffer window used by a frame need not be part of that
-frame---a frame that has no minibuffer of its own necessarily uses some
-other frame's minibuffer window.
address@hidden defun
-
address@hidden set-minibuffer-window window
-This function specifies @var{window} as the minibuffer window to use.
-This affects where the minibuffer is displayed if you put text in it
-without invoking the usual minibuffer commands.  It has no effect on
-the usual minibuffer input functions because they all start by
-choosing the minibuffer window according to the current frame.
address@hidden defun
-
address@hidden Emacs 19 feature
address@hidden window-minibuffer-p &optional window
-This function returns address@hidden if @var{window} is a minibuffer
-window.
address@hidden defaults to the selected window.
address@hidden defun
-
-It is not correct to determine whether a given window is a minibuffer by
-comparing it with the result of @code{(minibuffer-window)}, because
-there can be more than one minibuffer window if there is more than one
-frame.
-
address@hidden minibuffer-window-active-p window
-This function returns address@hidden if @var{window}, assumed to be
-a minibuffer window, is currently active.
address@hidden defun
-
address@hidden Minibuffer Contents
address@hidden Minibuffer Contents
-
-  These functions access the minibuffer prompt and contents.
-
address@hidden minibuffer-prompt
-This function returns the prompt string of the currently active
-minibuffer.  If no minibuffer is active, it returns @code{nil}.
address@hidden defun
-
address@hidden 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.
address@hidden defun
-
address@hidden minibuffer-prompt-width
-This function returns the current display-width of the minibuffer
-prompt, if a minibuffer is current.  Otherwise, it returns zero.
address@hidden defun
-
address@hidden 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
-entire contents of the current buffer.
address@hidden defun
-
address@hidden 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}.
address@hidden defun
-
address@hidden 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}.
address@hidden defun
-
address@hidden 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.
address@hidden defun
-
address@hidden Recursive Mini
address@hidden Recursive Minibuffers
address@hidden recursive minibuffers
-
-  These functions and variables deal with recursive minibuffers
-(@pxref{Recursive Editing}):
-
address@hidden minibuffer-depth
-This function returns the current depth of activations of the
-minibuffer, a nonnegative integer.  If no minibuffers are active, it
-returns zero.
address@hidden defun
-
address@hidden enable-recursive-minibuffers
-If this variable is address@hidden, you can invoke commands (such as
address@hidden) that use minibuffers even while the minibuffer window
-is active.  Such invocation produces a recursive editing level for a new
-minibuffer.  The outer-level minibuffer is invisible while you are
-editing the inner one.
-
-If this variable is @code{nil}, you cannot invoke minibuffer
-commands when the minibuffer window is active, not even if you switch to
-another window to do it.
address@hidden defopt
-
address@hidden Emacs 19 feature
-If a command name has a property @code{enable-recursive-minibuffers}
-that is address@hidden, then the command can use the minibuffer to read
-arguments even if it is invoked from the minibuffer.  A command can
-also achieve this by binding @code{enable-recursive-minibuffers}
-to @code{t} in the interactive declaration (@pxref{Using Interactive}).
-The minibuffer command @code{next-matching-history-element} (normally
address@hidden in the minibuffer) does the latter.
-
address@hidden Minibuffer Misc
address@hidden Minibuffer Miscellany
-
address@hidden minibufferp &optional buffer-or-name
-This function returns address@hidden if @var{buffer-or-name} is a
-minibuffer.  If @var{buffer-or-name} is omitted, it tests the current
-buffer.
address@hidden defun
-
address@hidden minibuffer-setup-hook
-This is a normal hook that is run whenever the minibuffer is entered.
address@hidden
address@hidden defvar
-
address@hidden minibuffer-exit-hook
-This is a normal hook that is run whenever the minibuffer is exited.
address@hidden
address@hidden defvar
-
address@hidden minibuffer-help-form
address@hidden of minibuffer-help-form}
-The current value of this variable is used to rebind @code{help-form}
-locally inside the minibuffer (@pxref{Help Functions}).
address@hidden defvar
-
address@hidden minibuffer-scroll-window
address@hidden of minibuffer-scroll-window}
-If the value of this variable is address@hidden, it should be a window
-object.  When the function @code{scroll-other-window} is called in the
-minibuffer, it scrolls this window.
address@hidden defvar
-
address@hidden minibuffer-selected-window
-This function returns the window which was selected when the
-minibuffer was entered.  If selected window is not a minibuffer
-window, it returns @code{nil}.
address@hidden defun
-
address@hidden max-mini-window-height
-This variable specifies the maximum height for resizing minibuffer
-windows.  If a float, it specifies a fraction of the height of the
-frame.  If an integer, it specifies a number of lines.
address@hidden defopt
-
address@hidden minibuffer-message string
-This function displays @var{string} temporarily at the end of the
-minibuffer text, for two seconds, or until the next input event
-arrives, whichever comes first.
address@hidden defun
-
address@hidden
-   arch-tag: bba7f945-9078-477f-a2ce-18818a6e1218
address@hidden ignore