From: Stefan Monnier Date: Mon, 21 Mar 2011 15:30:01 +0000 (-0400) Subject: * doc/lispref/minibuf.texi (Basic Completion): Be a bit more precise about the X-Git-Tag: emacs-pretest-24.0.90~104^3~92 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=fd5a8ae8a3750faaae9bee1deb303d8f8d2800c4;p=emacs.git * doc/lispref/minibuf.texi (Basic Completion): Be a bit more precise about the valid kinds of completion tables. (Programmed Completion): Remove obsolete text about lambda expressions not being valid completion tables. --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 26bb5888df5..440159a9a58 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,10 @@ +2011-03-21 Stefan Monnier + + * minibuf.texi (Basic Completion): Be a bit more precise about the + valid kinds of completion tables. + (Programmed Completion): Remove obsolete text about lambda expressions + not being valid completion tables. + 2011-03-19 Chong Yidong * positions.texi (Excursions): Explain the "save-excursion diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 0d907ea6532..9b09a304bd0 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -647,9 +647,9 @@ higher-level completion features that do use the minibuffer. @defun 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 -@var{collection} must be a list of strings or symbols, an alist, an -obarray, a hash table, or a completion function (@pxref{Programmed -Completion}). +@var{collection} must be a list of strings, an alist whose keys are +strings or symbols, an obarray, a hash table, or a completion function +(@pxref{Programmed Completion}). Completion compares @var{string} against each of the permissible completions specified by @var{collection}. If no permissible @@ -660,11 +660,11 @@ to all possible matching completions. 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. +strings, 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 +list of strings is allowed, even though we usually do not think of such lists as alists. @cindex obarray in completion @@ -680,7 +680,7 @@ 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}. +You can also use a function as @var{collection}. Then the function is solely responsible for performing completion; @code{try-completion} returns whatever this function returns. The function is called with three arguments: @var{string}, @var{predicate} @@ -1634,12 +1634,12 @@ which performs completion according to the rules used in Emacs 21; and @subsection Programmed Completion @cindex 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}. Emacs uses -programmed completion when completing file names (@pxref{File Name -Completion}), among many other cases. + Sometimes it is not possible or convenient to create an alist or +an obarray containing all the intended possible completions ahead +of time. In such a case, you can supply your own function to compute +the completion of a given string. This is called @dfn{programmed +completion}. Emacs uses programmed completion when completing file +names (@pxref{File Name Completion}), among many other cases. To use this feature, pass a function as the @var{collection} argument to @code{completing-read}. The function @@ -1667,7 +1667,7 @@ specifies which method to run. @end itemize There are currently four methods, i.e. four flag values, one for - each of the four different basic operations: +each of the four different basic operations: @itemize @bullet @item @@ -1698,14 +1698,6 @@ in the string to complete, and END is the position of the end boundary in SUFFIX. @end 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. - @defun completion-table-dynamic function This function is a convenient way to write a function that can act as programmed completion function. The argument @var{function} should be