[Emacs-diffs] emacs/doc/lispref minibuf.texi

[Chong Yidong]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Chong Yidong <cyd>      09/03/18 04:01:06

Modified files:
        doc/lispref    : minibuf.texi 

Log message:
        (Completion Styles): New node.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/minibuf.texi?cvsroot=emacs&r1=1.18&r2=1.19

Patches:
Index: minibuf.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/minibuf.texi,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -b -r1.18 -r1.19
--- minibuf.texi        17 Mar 2009 04:54:14 -0000      1.18
+++ minibuf.texi        18 Mar 2009 04:01:05 -0000      1.19
@@ -634,6 +634,7 @@
                              (reading buffer name, file name, etc.)
 * Reading File Names::     Using completion to read file names and
                              shell commands.
+* Completion Styles::      Specifying rules for performing completion.
 * Programmed Completion::  Writing your own completion-function.
 @end menu
 
@@ -1532,6 +1533,58 @@
 command and file names that are part of a shell command.
 @end defvar
 
address@hidden Completion Styles
address@hidden Completion Styles
address@hidden completion styles
+
+  A @dfn{completion style} is a set of rules for generating
+completions.  The user option @code{completion-styles} stores a list
+of completion styles, which are represented by symbols.
+
address@hidden completion-styles
+This is a list of completion style symbols to use for performing
+completion.  Each completion style in this list must be defined in
address@hidden
address@hidden defopt
+
address@hidden completion-styles-alist
+This variable stores a list of available completion styles.  Each
+element in the list must have the form @samp{(@var{name}
address@hidden @var{all-completions})}.  Here, @var{name} is the
+name of the completion style (a symbol), which may be used in
address@hidden to refer to this style.
+
address@hidden is the function that does the completion, and
address@hidden is the function that lists the completions.
+These functions should accept four arguments: @var{string},
address@hidden, @var{predicate}, and @var{point}.  The @var{string},
address@hidden, and @var{predicate} arguments have the same meanings
+as in @code{try-completion} (@pxref{Basic Completion}), and the
address@hidden argument is the position of point within @var{string}.
+Each function should return a address@hidden value if it performed its
+job, and @code{nil} if it did not (e.g., if there is no way to
+complete @var{string} according to the completion style).
+
+When the user calls a completion command, such as
address@hidden (@pxref{Completion Commands}), Emacs looks
+for the first style listed in @code{completion-styles} and calls its
address@hidden function.  If this function returns @code{nil},
+Emacs moves to the next completion style listed in
address@hidden and calls its @var{try-completion} function,
+and so on until one of the @var{try-completion} functions successfully
+performs completion and returns a address@hidden value.  A similar
+procedure is used for listing completions, via the
address@hidden functions.
address@hidden defvar
+
+  By default, @code{completion-styles-alist} contains four pre-defined
+completion styles: @code{basic}, a basic completion style;
address@hidden, which does partial completion (completing
+each word in the input separately); @code{emacs22}, which performs
+completion according to the rules used in Emacs 22; and
address@hidden, which performs completion according to the rules used
+in Emacs 21.
+
 @node Programmed Completion
 @subsection Programmed Completion
 @cindex programmed completion