updated for version 7.0189
diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt
index 0a28038..92d85e4 100644
--- a/runtime/doc/insert.txt
+++ b/runtime/doc/insert.txt
@@ -1,4 +1,4 @@
-*insert.txt* For Vim version 7.0aa. Last change: 2006 Jan 08
+*insert.txt* For Vim version 7.0aa. Last change: 2006 Jan 29
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -871,8 +871,8 @@
User defined completion *compl-function*
Completion is done by a function that can be defined by the user with the
-'completefunc' option. See the 'completefunc' help for how the function
-is called and an example.
+'completefunc' option. See below for how the function is called and an
+example |complete-functions|.
*i_CTRL-X_CTRL-U*
CTRL-X CTRL-U Guess what kind of item is in front of the cursor and
@@ -890,7 +890,7 @@
Completion is done by a function that can be defined by the user with the
'omnifunc' option. This is to be used for filetype-specific completion.
-See the 'completefunc' help for how the function is called and an example.
+See below for how the function is called and an example |complete-functions|.
For remarks about specific filetypes see |compl-omni-filetypes|.
*i_CTRL-X_CTRL-O*
@@ -952,6 +952,94 @@
other contexts unless a double CTRL-X is used.
+FUNCTIONS FOR FINDING COMPLETIONS *complete-functions*
+
+This applies to 'completefunc' and 'omnifunc'.
+
+The function will be invoked with two arguments. First the function is called
+to find the start of the text to be completed. Secondly the function is
+called to actually find the matches.
+
+On the first invocation the arguments are:
+ a:findstart 1
+ a:base empty
+
+The function must return the column of where the completion starts. It must
+be a number between zero and the cursor column "col('.')". This involves
+looking at the characters just before the cursor and including those
+characters that could be part of the completed item. The text between this
+column and the cursor column will be replaced with the matches. Return -1 if
+no completion can be done.
+
+On the second invocation the arguments are:
+ a:findstart 0
+ a:base the text with which matches should match, what was
+ located in the first call (can be empty)
+
+The function must return a List with the matching words. These matches
+usually include the "a:base" text. When there are no matches return an empty
+List. When one of the items in the list cannot be used as a string (e.g., a
+Dictionary) then an error message is given and further items in the list are
+not used.
+
+When searching for matches takes some time call |complete_add()| to add each
+match to the total list. These matches should then not appear in the returned
+list! Call |complete_check()| now and then to allow the user to press a key
+while still searching for matches. Stop searching when it returns non-zero.
+
+The function may move the cursor, it is restored afterwards. This option
+cannot be set from a |modeline| or in the |sandbox|, for security reasons.
+
+An example that completes the names of the months: >
+ fun! CompleteMonths(findstart, base)
+ if a:findstart
+ " locate the start of the word
+ let line = getline('.')
+ let start = col('.') - 1
+ while start > 0 && line[start - 1] =~ '\a'
+ let start -= 1
+ endwhile
+ return start
+ else
+ " find months matching with "a:base"
+ let res = []
+ for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec")
+ if m =~ '^' . a:base
+ call add(res, m)
+ endif
+ endfor
+ return res
+ endif
+ endfun
+ set completefunc=CompleteMonths
+<
+The same, but now pretending searching for matches is slow: >
+ fun! CompleteMonths(findstart, base)
+ if a:findstart
+ " locate the start of the word
+ let line = getline('.')
+ let start = col('.') - 1
+ while start > 0 && line[start - 1] =~ '\a'
+ let start -= 1
+ endwhile
+ return start
+ else
+ " find months matching with "a:base"
+ for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec")
+ if m =~ '^' . a:base
+ call complete_add(m)
+ endif
+ sleep 300m " simulate searching for next match
+ if complete_check()
+ break
+ endif
+ endfor
+ return []
+ endif
+ endfun
+ set completefunc=CompleteMonths
+<
+
INSERT COMPLETION POPUP MENU *ins-completion-menu*
*popupmenu-completion*
Vim can display the matches in a simplistic popup menu.