(coded-charset-entity-reference-alist): Add setting for

[chise/xemacs-chise.git-] / man / lispref / minibuf.texi

diff --git a/man/lispref/minibuf.texi b/man/lispref/minibuf.texi
index 1e1e9ed..d897a0e 100644 (file)
--- a/man/lispref/minibuf.texi
+++ b/man/lispref/minibuf.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the XEmacs Lisp Reference Manual.
 @c -*-texinfo-*-
 @c This is part of the XEmacs Lisp Reference Manual.

-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1997 Free Software Foundation, Inc. 
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1997 Free Software Foundation, Inc.

 @c See the file lispref.texi for copying conditions.
 @setfilename ../../info/minibuf.info
 @node Minibuffers, Command Loop, Read and Print, Top
 @c See the file lispref.texi for copying conditions.
 @setfilename ../../info/minibuf.info
 @node Minibuffers, Command Loop, Read and Print, Top

@@ -95,7 +95,7 @@ string; however, if @var{read} is non-@code{nil}, then it uses
 @code{read} to convert the text into a Lisp object (@pxref{Input
 Functions}).
 
 @code{read} to convert the text into a Lisp object (@pxref{Input
 Functions}).
 

-The first thing this function does is to activate a minibuffer and 
+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.
 
 display it with @var{prompt-string} as the prompt.  This value must be a
 string.
 

@@ -150,23 +150,26 @@ the minibuffer on other occasions.  However, if user is supposed to edit
 default value, @var{initial-contents} may be preferred.
 @end defun
 
 default value, @var{initial-contents} may be preferred.
 @end defun
 

-@defun read-string prompt &optional initial history
+@defun read-string prompt &optional initial history default-value

 This function reads a string from the minibuffer and returns it.  The
 arguments @var{prompt} and @var{initial} are used as in
 @code{read-from-minibuffer}.  The keymap used is
 @code{minibuffer-local-map}.
 
 This function reads a string from the minibuffer and returns it.  The
 arguments @var{prompt} and @var{initial} are used as in
 @code{read-from-minibuffer}.  The keymap used is
 @code{minibuffer-local-map}.
 

-The optional argument @var{history}, if non-nil, specifies a history
-list and optionally the initial position in the list.
+The optional argument @var{history}, if non-@code{nil}, specifies a history
+list and optionally the initial position in the list.  The optional
+argument @var{default-value} specifies a default value to return if the user
+enters null input; it should be a string.

 
 This function is a simplified interface to the
 @code{read-from-minibuffer} function:
 
 @smallexample
 @group
 
 This function is a simplified interface to the
 @code{read-from-minibuffer} function:
 
 @smallexample
 @group

-(read-string @var{prompt} @var{initial})
+(read-string @var{prompt} @var{initial} @var{history} @var{default})

 @equiv{}
 @equiv{}

-(read-from-minibuffer @var{prompt} @var{initial} nil nil nil)
+(read-from-minibuffer @var{prompt} @var{initial} nil nil
+                      @var{history} nil @var{default})))

 @end group
 @end smallexample
 @end defun
 @end group
 @end smallexample
 @end defun

@@ -205,19 +208,25 @@ default, it makes the following bindings:
   This section describes functions for reading Lisp objects with the
 minibuffer.
 
   This section describes functions for reading Lisp objects with the
 minibuffer.
 

-@defun read-minibuffer prompt &optional initial
+@defun read-expression prompt &optional initial history default-value

 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 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}.
 

+The optional argument @var{history}, if non-@code{nil}, specifies a history
+list and optionally the initial position in the list.  The optional
+argument @var{default-value} specifies a default value to return if the
+user enters null input; it should be a string.
+

 This is a simplified interface to the
 @code{read-from-minibuffer} function:
 
 @smallexample
 @group
 This is a simplified interface to the
 @code{read-from-minibuffer} function:
 
 @smallexample
 @group

-(read-minibuffer @var{prompt} @var{initial})
+(read-expression @var{prompt} @var{initial} @var{history} @var{default-value})

 @equiv{}
 @equiv{}

-(read-from-minibuffer @var{prompt} @var{initial} nil t)
+(read-from-minibuffer @var{prompt} @var{initial} nil t
+                      @var{history} nil @var{default-value})

 @end group
 @end smallexample
 
 @end group
 @end smallexample
 

@@ -226,7 +235,7 @@ initial input:
 
 @smallexample
 @group
 
 @smallexample
 @group

-(read-minibuffer
+(read-expression

  "Enter an expression: " (format "%s" '(testing)))
 
 ;; @r{Here is how the minibuffer is displayed:}
  "Enter an expression: " (format "%s" '(testing)))
 
 ;; @r{Here is how the minibuffer is displayed:}

@@ -244,24 +253,35 @@ The user can type @key{RET} immediately to use the initial input as a
 default, or can edit the input.
 @end defun
 
 default, or can edit the input.
 @end defun
 

-@defun eval-minibuffer prompt &optional initial
+@defun read-minibuffer prompt &optional initial history default-value
+
+This is a FSF Emacs compatible function.  Use @code{read-expression}
+instead.
+@end defun
+
+@defun eval-minibuffer prompt &optional initial history default-value

 This function reads a Lisp expression using the minibuffer, evaluates
 it, then returns the result.  The arguments @var{prompt} and
 @var{initial} are used as in @code{read-from-minibuffer}.
 
 This function reads a Lisp expression using the minibuffer, evaluates
 it, then returns the result.  The arguments @var{prompt} and
 @var{initial} are used as in @code{read-from-minibuffer}.
 

+The optional argument @var{history}, if non-@code{nil}, specifies a history
+list and optionally the initial position in the list.  The optional
+argument @var{default-value} specifies a default value to return if the
+user enters null input; it should be a string.
+

 This function simply evaluates the result of a call to
 This function simply evaluates the result of a call to

-@code{read-minibuffer}:
+@code{read-expression}:

 
 @smallexample
 @group
 (eval-minibuffer @var{prompt} @var{initial})
 @equiv{}
 
 @smallexample
 @group
 (eval-minibuffer @var{prompt} @var{initial})
 @equiv{}

-(eval (read-minibuffer @var{prompt} @var{initial}))
+(eval (read-expression @var{prompt} @var{initial}))

 @end group
 @end smallexample
 @end defun
 
 @end group
 @end smallexample
 @end defun
 

-@defun edit-and-eval-command prompt form
+@defun edit-and-eval-command prompt form &optional history

 This function reads a Lisp expression in the minibuffer, and then
 evaluates it.  The difference between this command and
 @code{eval-minibuffer} is that here the initial @var{form} is not
 This function reads a Lisp expression in the minibuffer, and then
 evaluates it.  The difference between this command and
 @code{eval-minibuffer} is that here the initial @var{form} is not

@@ -284,7 +304,7 @@ text which is a valid form already:
 @group
 (edit-and-eval-command "Please edit: " '(forward-word 1))
 
 @group
 (edit-and-eval-command "Please edit: " '(forward-word 1))
 

-;; @r{After evaluation of the preceding expression,} 
+;; @r{After evaluation of the preceding expression,}

 ;;   @r{the following appears in the minibuffer:}
 @end group
 
 ;;   @r{the following appears in the minibuffer:}
 @end group
 

@@ -436,7 +456,7 @@ this chapter so as to keep them near the higher-level completion
 features that do use the minibuffer.
 
 @defun try-completion string collection &optional predicate
 features that do use the minibuffer.
 
 @defun try-completion string collection &optional predicate

-This function returns the longest common substring of all possible
+This function returns the longest common prefix of all possible

 completions of @var{string} in @var{collection}.  The value of
 @var{collection} must be an alist, an obarray, or a function that
 implements a virtual set of strings (see below).
 completions of @var{string} in @var{collection}.  The value of
 @var{collection} must be an alist, an obarray, or a function that
 implements a virtual set of strings (see below).

@@ -486,7 +506,7 @@ is @code{t}.
 
 @smallexample
 @group
 
 @smallexample
 @group

-(try-completion 
+(try-completion

  "foo"
  '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
      @result{} "fooba"
  "foo"
  '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
      @result{} "fooba"

@@ -516,44 +536,40 @@ too short).  Both of those begin with the string @samp{foobar}.
 
 @smallexample
 @group
 
 @smallexample
 @group

-(defun test (s) 
+(defun test (s)

   (> (length (car s)) 6))
      @result{} test
 @end group
 @group
   (> (length (car s)) 6))
      @result{} test
 @end group
 @group

-(try-completion 
+(try-completion

  "foo"
  "foo"

- '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) 
+ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))

  'test)
      @result{} "foobar"
 @end group
 @end smallexample
 @end defun
 
  'test)
      @result{} "foobar"
 @end group
 @end smallexample
 @end defun
 

-@defun all-completions string collection &optional predicate nospace
-This function returns a list of all possible completions of
-@var{string}.  The arguments to this function are the same as those of
-@code{try-completion}.
+@defun all-completions string collection &optional predicate
+This function returns a list of all possible completions of @var{string}.
+The arguments to this function are the same as those of @code{try-completion}.

 
 If @var{collection} is a function, it is called with three arguments:
 @var{string}, @var{predicate} and @code{t}; then @code{all-completions}
 returns whatever the function returns.  @xref{Programmed Completion}.
 
 
 If @var{collection} is a function, it is called with three arguments:
 @var{string}, @var{predicate} and @code{t}; then @code{all-completions}
 returns whatever the function returns.  @xref{Programmed Completion}.
 

-If @var{nospace} is non-@code{nil}, completions that start with a space
-are ignored unless @var{string} also starts with a space.
-

 Here is an example, using the function @code{test} shown in the
 example for @code{try-completion}:
 
 @smallexample
 @group
 Here is an example, using the function @code{test} shown in the
 example for @code{try-completion}:
 
 @smallexample
 @group

-(defun test (s) 
+(defun test (s)

   (> (length (car s)) 6))
      @result{} test
 @end group
 
 @group
   (> (length (car s)) 6))
      @result{} test
 @end group
 
 @group

-(all-completions  
+(all-completions

  "foo"
  '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
  'test)
  "foo"
  '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
  'test)

@@ -563,7 +579,7 @@ example for @code{try-completion}:
 @end defun
 
 @defvar completion-ignore-case
 @end defun
 
 @defvar completion-ignore-case

-If the value of this variable is 
+If the value of this variable is

 non-@code{nil}, XEmacs does not consider case significant in completion.
 @end defvar
 
 non-@code{nil}, XEmacs does not consider case significant in completion.
 @end defvar
 

@@ -605,7 +621,7 @@ value of @var{require-match}, and regardless of whether the empty string
 is included in @var{collection}.
 
 The function @code{completing-read} works by calling
 is included in @var{collection}.
 
 The function @code{completing-read} works by calling

-@code{read-minibuffer}.  It uses @code{minibuffer-local-completion-map}
+@code{read-expression}.  It uses @code{minibuffer-local-completion-map}

 as the keymap if @var{require-match} is @code{nil}, and uses
 @code{minibuffer-local-must-match-map} if @var{require-match} is
 non-@code{nil}.  @xref{Completion Commands}.
 as the keymap if @var{require-match} is @code{nil}, and uses
 @code{minibuffer-local-must-match-map} if @var{require-match} is
 non-@code{nil}.  @xref{Completion Commands}.

@@ -629,7 +645,7 @@ Here's an example of using @code{completing-read}:
 @end group
 
 @group
 @end group
 
 @group

-;; @r{After evaluation of the preceding expression,} 
+;; @r{After evaluation of the preceding expression,}

 ;;   @r{the following appears in the minibuffer:}
 
 ---------- Buffer: Minibuffer ----------
 ;;   @r{the following appears in the minibuffer:}
 
 ---------- Buffer: Minibuffer ----------

@@ -755,7 +771,7 @@ The list of completions is displayed as text in a buffer named
 @samp{*Completions*}.
 @end deffn
 
 @samp{*Completions*}.
 @end deffn
 

-@defun display-completion-list completions
+@defun display-completion-list completions &rest cl-keys

 This function displays @var{completions} to the stream in
 @code{standard-output}, usually a buffer.  (@xref{Read and Print}, for more
 information about streams.)  The argument @var{completions} is normally
 This function displays @var{completions} to the stream in
 @code{standard-output}, usually a buffer.  (@xref{Read and Print}, for more
 information about streams.)  The argument @var{completions} is normally

@@ -814,7 +830,7 @@ only buffer name starting with the given input is
 @example
 (read-buffer "Buffer name? " "foo" t)
 @group
 @example
 (read-buffer "Buffer name? " "foo" t)
 @group

-;; @r{After evaluation of the preceding expression,} 
+;; @r{After evaluation of the preceding expression,}

 ;;   @r{the following prompt appears,}
 ;;   @r{with an empty minibuffer:}
 @end group
 ;;   @r{the following prompt appears,}
 ;;   @r{with an empty minibuffer:}
 @end group

@@ -832,24 +848,30 @@ Buffer name? (default foo) @point{}
 @end example
 @end defun
 
 @end example
 @end defun
 

-@defun read-command prompt
+@defun read-command prompt &optional default-value

 This function reads the name of a command and returns it as a Lisp
 symbol.  The argument @var{prompt} is used as in
 @code{read-from-minibuffer}.  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}.
 
 This function reads the name of a command and returns it as a Lisp
 symbol.  The argument @var{prompt} is used as in
 @code{read-from-minibuffer}.  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-value} specifies what to return if the user
+enters null input.  It can be a symbol or a string; if it is a string,
+@code{read-command} 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{nil}.
+

 @example
 (read-command "Command name? ")
 
 @group
 @example
 (read-command "Command name? ")
 
 @group

-;; @r{After evaluation of the preceding expression,} 
+;; @r{After evaluation of the preceding expression,}

 ;;   @r{the following prompt appears with an empty minibuffer:}
 @end group
 
 @group
 ;;   @r{the following prompt appears with an empty minibuffer:}
 @end group
 
 @group

----------- Buffer: Minibuffer ---------- 
-Command name?  
+---------- Buffer: Minibuffer ----------
+Command name?

 ---------- Buffer: Minibuffer ----------
 @end group
 @end example
 ---------- Buffer: Minibuffer ----------
 @end group
 @end example

@@ -868,22 +890,28 @@ as to complete in the set of extant Lisp symbols, and it uses the
 @group
 (read-command @var{prompt})
 @equiv{}
 @group
 (read-command @var{prompt})
 @equiv{}

-(intern (completing-read @var{prompt} obarray 
+(intern (completing-read @var{prompt} obarray

                          'commandp t nil))
 @end group
 @end example
 @end defun
 
                          'commandp t nil))
 @end group
 @end example
 @end defun
 

-@defun read-variable prompt
+@defun read-variable prompt &optional default-value

 This function reads the name of a user variable and returns it as a
 symbol.
 
 This function reads the name of a user variable and returns it as a
 symbol.
 

+The argument @var{default-value} specifies what to return if the user
+enters null input.  It can be a symbol or a string; if it is a string,
+@code{read-variable} interns it before returning it.  If @var{default-value}
+is @code{nil}, that means no default has been specified; then if the
+user enters null input, the return value is @code{nil}.
+

 @example
 @group
 (read-variable "Variable name? ")
 
 @example
 @group
 (read-variable "Variable name? ")
 

-;; @r{After evaluation of the preceding expression,} 
-;;   @r{the following prompt appears,} 
+;; @r{After evaluation of the preceding expression,}
+;;   @r{the following prompt appears,}

 ;;   @r{with an empty minibuffer:}
 @end group
 
 ;;   @r{with an empty minibuffer:}
 @end group
 

@@ -920,7 +948,7 @@ predicate @code{user-variable-p} instead of @code{commandp}:
 file name.  It provides special features including automatic insertion
 of the default directory.
 
 file name.  It provides special features including automatic insertion
 of the default directory.
 

-@defun read-file-name prompt &optional directory default existing initial
+@defun read-file-name prompt &optional directory default existing initial history

 This function reads a file name in the minibuffer, prompting with
 @var{prompt} and providing completion.  If @var{default} is
 non-@code{nil}, then the function returns @var{default} if the user just
 This function reads a file name in the minibuffer, prompting with
 @var{prompt} and providing completion.  If @var{default} is
 non-@code{nil}, then the function returns @var{default} if the user just

@@ -948,13 +976,13 @@ case, point goes at the beginning of @var{initial}.  The default for
 @var{initial} is @code{nil}---don't insert any file name.  To see what
 @var{initial} does, try the command @kbd{C-x C-v}.
 
 @var{initial} is @code{nil}---don't insert any file name.  To see what
 @var{initial} does, try the command @kbd{C-x C-v}.
 

-Here is an example: 
+Here is an example:

 
 @example
 @group
 (read-file-name "The file is ")
 
 
 @example
 @group
 (read-file-name "The file is ")
 

-;; @r{After evaluation of the preceding expression,} 
+;; @r{After evaluation of the preceding expression,}

 ;;   @r{the following appears in the minibuffer:}
 @end group
 
 ;;   @r{the following appears in the minibuffer:}
 @end group
 

@@ -1140,13 +1168,13 @@ invalid.  At the next prompt the user types @kbd{y}.
 @group
 (y-or-n-p "Do you need a lift? ")
 
 @group
 (y-or-n-p "Do you need a lift? ")
 

-;; @r{After evaluation of the preceding expression,} 
+;; @r{After evaluation of the preceding expression,}

 ;;   @r{the following prompt appears in the echo area:}
 @end group
 
 @group
 ---------- Echo area ----------
 ;;   @r{the following prompt appears in the echo area:}
 @end group
 
 @group
 ---------- Echo area ----------

-Do you need a lift? (y or n) 
+Do you need a lift? (y or n)

 ---------- Echo area ----------
 @end group
 
 ---------- Echo area ----------
 @end group
 

@@ -1154,7 +1182,7 @@ Do you need a lift? (y or n)
 
 @group
 ---------- Echo area ----------
 
 @group
 ---------- Echo area ----------

-Please answer y or n.  Do you need a lift? (y or n) 
+Please answer y or n.  Do you need a lift? (y or n)

 ---------- Echo area ----------
 @end group
 
 ---------- Echo area ----------
 @end group
 

@@ -1193,14 +1221,14 @@ Here is an example:
 @group
 (yes-or-no-p "Do you really want to remove everything? ")
 
 @group
 (yes-or-no-p "Do you really want to remove everything? ")
 

-;; @r{After evaluation of the preceding expression,} 
-;;   @r{the following prompt appears,} 
+;; @r{After evaluation of the preceding expression,}
+;;   @r{the following prompt appears,}

 ;;   @r{with an empty minibuffer:}
 @end group
 
 @group
 ---------- Buffer: minibuffer ----------
 ;;   @r{with an empty minibuffer:}
 @end group
 
 @group
 ---------- Buffer: minibuffer ----------

-Do you really want to remove everything? (yes or no) 
+Do you really want to remove everything? (yes or no)

 ---------- Buffer: minibuffer ----------
 @end group
 @end smallexample
 ---------- Buffer: minibuffer ----------
 @end group
 @end smallexample

@@ -1358,13 +1386,13 @@ and inserted in the minibuffer. If @var{default} is @code{nil}, then
 @end defun
 
 @defopt passwd-invert-frame-when-keyboard-grabbed
 @end defun
 
 @defopt passwd-invert-frame-when-keyboard-grabbed

-If non-nil swap the foreground and background colors of all faces while
-reading a password.  Default values is @code{t} unless feature
+If non-@code{nil}, swap the foreground and background colors of all faces while
+reading a password.  Default values is @code{t}, unless feature

 @code{infodock} is provided.
 @end defopt
 
 @defopt passwd-echo
 @code{infodock} is provided.
 @end defopt
 
 @defopt passwd-echo

-This specifies the character echoed when typing a password.  When nil,
+This specifies the character echoed when typing a password.  When @code{nil},

 nothing is echoed.
 @end defopt
 
 nothing is echoed.
 @end defopt
 

@@ -1446,7 +1474,7 @@ other frame's minibuffer window.
 @end defun
 
 @c Emacs 19 feature
 @end defun
 
 @c Emacs 19 feature

-@defun window-minibuffer-p window
+@defun window-minibuffer-p &optional window

 This function returns non-@code{nil} if @var{window} is a minibuffer window.
 @end defun
 
 This function returns non-@code{nil} if @var{window} is a minibuffer window.
 @end defun
 

@@ -1483,7 +1511,7 @@ minibuffer.  The outer-level minibuffer is invisible while you are
 editing the inner one.
 
 This variable only affects invoking the minibuffer while the
 editing the inner one.
 
 This variable only affects invoking the minibuffer while the

-minibuffer window is selected.   If you switch windows while in the 
+minibuffer window is selected.   If you switch windows while in the

 minibuffer, you can always invoke minibuffer commands while some other
 window is selected.
 @end defopt
 minibuffer, you can always invoke minibuffer commands while some other
 window is selected.
 @end defopt