vim-patch:partial 0daafaa7d99e (#20083)

Update runtime files
https://github.com/vim/vim/commit/0daafaa7d99ef500f76b1b12f5fe8153e2fcaea0

skip vim9script ftplugin
create userfunc.txt from Neovim content (skip section 3, needs 9.0.0379)

6 files changed, 451 insertions, 412 deletions

diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index 63226fe701..7a2c540ea2 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -412,6 +412,8 @@ CmdwinLeave			Before leaving the command-line window.
 				|cmdwin-char|
 							*ColorScheme*
 ColorScheme			After loading a color scheme. |:colorscheme|
+				Not triggered if the color scheme is not
+				found.
 				The pattern is matched against the
 				colorscheme name. <afile> can be used for the
 				name of the actual file where this option was
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 3ca6f04389..57b41c664b 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -6,9 +6,7 @@
 
 Builtin functions				*builtin-functions*
 
-1. Overview				|builtin-function-list|
-2. Details				|builtin-function-details|
-3. Matching a pattern in a String	|string-match|
+				      Type |gO| to see the table of contents.
 
 ==============================================================================
 1. Overview					*builtin-function-list*
@@ -1276,7 +1274,7 @@ complete_info([{what}])				*complete_info()*
 				typed text only, or the last completion after
 				no item is selected when using the <Up> or
 				<Down> keys)
-		   inserted	Inserted string. [NOT IMPLEMENT YET]
+		   inserted	Inserted string. [NOT IMPLEMENTED YET]
 
 							*complete_info_mode*
 		mode values are:
@@ -2530,18 +2528,18 @@ function({name} [, {arglist}] [, {dict}])
 		The arguments are passed to the function in front of other
 		arguments, but after any argument from |method|.  Example: >
 			func Callback(arg1, arg2, name)
-			...
+			"...
 			let Partial = function('Callback', ['one', 'two'])
-			...
+			"...
 			call Partial('name')
 <		Invokes the function as with: >
 			call Callback('one', 'two', 'name')
 
 <		With a |method|: >
 			func Callback(one, two, three)
-			...
+			"...
 			let Partial = function('Callback', ['two'])
-			...
+			"...
 			eval 'one'->Partial('three')
 <		Invokes the function as with: >
 			call Callback('one', 'two', 'three')
@@ -2550,10 +2548,10 @@ function({name} [, {arglist}] [, {dict}])
 		Funcref.  The extra arguments are appended to the list of
 		arguments.  Example: >
 			func Callback(arg1, arg2, name)
-			...
+			"...
 			let Func = function('Callback', ['one'])
 			let Func2 = function(Func, ['two'])
-			...
+			"...
 			call Func2('name')
 <		Invokes the function as with: >
 			call Callback('one', 'two', 'name')
@@ -2563,22 +2561,23 @@ function({name} [, {arglist}] [, {dict}])
 			function Callback() dict
 			   echo "called for " .. self.name
 			endfunction
-			...
+			"...
 			let context = {"name": "example"}
 			let Func = function('Callback', context)
-			...
+			"...
 			call Func()	" will echo: called for example
 <		The use of function() is not needed when there are no extra
-		arguments, these two are equivalent: >
+		arguments, these two are equivalent, if Callback() is defined
+		as context.Callback(): >
 			let Func = function('Callback', context)
 			let Func = context.Callback
 
 <		The argument list and the Dictionary can be combined: >
 			function Callback(arg1, count) dict
-			...
+			"...
 			let context = {"name": "example"}
 			let Func = function('Callback', ['one'], context)
-			...
+			"...
 			call Func(500)
 <		Invokes the function as with: >
 			call context.Callback('one', 500)
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index bce0189cfb..3e068e3b4e 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -2309,402 +2309,10 @@ help file: |builtin-functions|.
 5. Defining functions					*user-function*
 
 New functions can be defined.  These can be called just like builtin
-functions.  The function executes a sequence of Ex commands.  Normal mode
-commands can be executed with the |:normal| command.
-
-The function name must start with an uppercase letter, to avoid confusion with
-builtin functions.  To prevent from using the same name in different scripts
-avoid obvious, short names.  A good habit is to start the function name with
-the name of the script, e.g., "HTMLcolor()".
-
-It's also possible to use curly braces, see |curly-braces-names|.  And the
-|autoload| facility is useful to define a function only when it's called.
-
-							*local-function*
-A function local to a script must start with "s:".  A local script function
-can only be called from within the script and from functions, user commands
-and autocommands defined in the script.  It is also possible to call the
-function from a mapping defined in the script, but then |<SID>| must be used
-instead of "s:" when the mapping is expanded outside of the script.
-There are only script-local functions, no buffer-local or window-local
-functions.
-
-					*:fu* *:function* *E128* *E129* *E123*
-:fu[nction]		List all functions and their arguments.
-
-:fu[nction][!] {name}	List function {name}, annotated with line numbers
-			unless "!" is given.
-			{name} may be a |Dictionary| |Funcref| entry: >
-				:function dict.init
-
-:fu[nction] /{pattern}	List functions with a name matching {pattern}.
-			Example that lists all functions ending with "File": >
-				:function /File$
-<
-							*:function-verbose*
-When 'verbose' is non-zero, listing a function will also display where it was
-last defined. Example: >
-
-    :verbose function SetFileTypeSH
-	function SetFileTypeSH(name)
-	    Last set from /usr/share/vim/vim-7.0/filetype.vim
-<
-See |:verbose-cmd| for more information.
-
-						*E124* *E125* *E853* *E884*
-:fu[nction][!] {name}([arguments]) [range] [abort] [dict] [closure]
-			Define a new function by the name {name}.  The body of
-			the function follows in the next lines, until the
-			matching |:endfunction|.
-
-			The name must be made of alphanumeric characters and
-			'_', and must start with a capital or "s:" (see
-			above).  Note that using "b:" or "g:" is not allowed.
-			(since patch 7.4.260 E884 is given if the function
-			name has a colon in the name, e.g. for "foo:bar()".
-			Before that patch no error was given).
-
-			{name} can also be a |Dictionary| entry that is a
-			|Funcref|: >
-				:function dict.init(arg)
-<			"dict" must be an existing dictionary.  The entry
-			"init" is added if it didn't exist yet.  Otherwise [!]
-			is required to overwrite an existing function.  The
-			result is a |Funcref| to a numbered function.  The
-			function can only be used with a |Funcref| and will be
-			deleted if there are no more references to it.
-								*E127* *E122*
-			When a function by this name already exists and [!] is
-			not used an error message is given.  There is one
-			exception: When sourcing a script again, a function
-			that was previously defined in that script will be
-			silently replaced.
-			When [!] is used, an existing function is silently
-			replaced.  Unless it is currently being executed, that
-			is an error.
-			NOTE: Use ! wisely.  If used without care it can cause
-			an existing function to be replaced unexpectedly,
-			which is hard to debug.
-
-			For the {arguments} see |function-argument|.
-
-					*:func-range* *a:firstline* *a:lastline*
-			When the [range] argument is added, the function is
-			expected to take care of a range itself.  The range is
-			passed as "a:firstline" and "a:lastline".  If [range]
-			is excluded, ":{range}call" will call the function for
-			each line in the range, with the cursor on the start
-			of each line.  See |function-range-example|.
-			The cursor is still moved to the first line of the
-			range, as is the case with all Ex commands.
-								*:func-abort*
-			When the [abort] argument is added, the function will
-			abort as soon as an error is detected.
-								*:func-dict*
-			When the [dict] argument is added, the function must
-			be invoked through an entry in a |Dictionary|.  The
-			local variable "self" will then be set to the
-			dictionary.  See |Dictionary-function|.
-						*:func-closure* *E932*
-			When the [closure] argument is added, the function
-			can access variables and arguments from the outer
-			scope.  This is usually called a closure.  In this
-			example Bar() uses "x" from the scope of Foo().  It
-			remains referenced even after Foo() returns: >
-				:function! Foo()
-				:  let x = 0
-				:  function! Bar() closure
-				:    let x += 1
-				:    return x
-				:  endfunction
-				:  return funcref('Bar')
-				:endfunction
-
-				:let F = Foo()
-				:echo F()
-<				1 >
-				:echo F()
-<				2 >
-				:echo F()
-<				3
-
-						*function-search-undo*
-			The last used search pattern and the redo command "."
-			will not be changed by the function.  This also
-			implies that the effect of |:nohlsearch| is undone
-			when the function returns.
-
-				*:endf* *:endfunction* *E126* *E193* *W22*
-:endf[unction] [argument]
-			The end of a function definition.  Best is to put it
-			on a line by its own, without [argument].
-
-			[argument] can be:
-				| command	command to execute next
-				\n command	command to execute next
-				" comment	always ignored
-				anything else	ignored, warning given when
-						'verbose' is non-zero
-			The support for a following command was added in Vim
-			8.0.0654, before that any argument was silently
-			ignored.
-
-			To be able to define a function inside an `:execute`
-			command, use line breaks instead of |:bar|: >
-				:exe "func Foo()\necho 'foo'\nendfunc"
-<
-				*:delf* *:delfunction* *E131* *E933*
-:delf[unction][!] {name}
-			Delete function {name}.
-			{name} can also be a |Dictionary| entry that is a
-			|Funcref|: >
-				:delfunc dict.init
-<			This will remove the "init" entry from "dict".  The
-			function is deleted if there are no more references to
-			it.
-			With the ! there is no error if the function does not
-			exist.
-							*:retu* *:return* *E133*
-:retu[rn] [expr]	Return from a function.  When "[expr]" is given, it is
-			evaluated and returned as the result of the function.
-			If "[expr]" is not given, the number 0 is returned.
-			When a function ends without an explicit ":return",
-			the number 0 is returned.
-			Note that there is no check for unreachable lines,
-			thus there is no warning if commands follow ":return".
-
-			If the ":return" is used after a |:try| but before the
-			matching |:finally| (if present), the commands
-			following the ":finally" up to the matching |:endtry|
-			are executed first.  This process applies to all
-			nested ":try"s inside the function.  The function
-			returns at the outermost ":endtry".
-
-						*function-argument* *a:var*
-An argument can be defined by giving its name.  In the function this can then
-be used as "a:name" ("a:" for argument).
-					*a:0* *a:1* *a:000* *E740* *...*
-Up to 20 arguments can be given, separated by commas.  After the named
-arguments an argument "..." can be specified, which means that more arguments
-may optionally be following.  In the function the extra arguments can be used
-as "a:1", "a:2", etc.  "a:0" is set to the number of extra arguments (which
-can be 0).  "a:000" is set to a |List| that contains these arguments.  Note
-that "a:1" is the same as "a:000[0]".
-								*E742*
-The a: scope and the variables in it cannot be changed, they are fixed.
-However, if a composite type is used, such as |List| or |Dictionary| , you can
-change their contents.  Thus you can pass a |List| to a function and have the
-function add an item to it.  If you want to make sure the function cannot
-change a |List| or |Dictionary| use |:lockvar|.
-
-It is also possible to define a function without any arguments.  You must
-still supply the () then.
-
-It is allowed to define another function inside a function body.
-
-						*optional-function-argument*
-You can provide default values for positional named arguments.  This makes
-them optional for function calls.  When a positional argument is not
-specified at a call, the default expression is used to initialize it.
-This only works for functions declared with |function|, not for
-lambda expressions |expr-lambda|.
-
-Example: >
-  function Something(key, value = 10)
-     echo a:key .. ": " .. a:value
-  endfunction
-  call Something('empty')	"empty: 10"
-  call Something('key', 20)	"key: 20"
-
-The argument default expressions are evaluated at the time of the function
-call, not definition.  Thus it is possible to use an expression which is
-invalid the moment the function is defined.  The expressions are also only
-evaluated when arguments are not specified during a call.
-
-								*E989*
-Optional arguments with default expressions must occur after any mandatory
-arguments.  You can use "..." after all optional named arguments.
-
-It is possible for later argument defaults to refer to prior arguments,
-but not the other way around.  They must be prefixed with "a:", as with all
-arguments.
-
-Example that works: >
-  :function Okay(mandatory, optional = a:mandatory)
-  :endfunction
-Example that does NOT work: >
-  :function NoGood(first = a:second, second = 10)
-  :endfunction
-<
-When not using "...", the number of arguments in a function call must be at
-least equal to the number of mandatory named arguments.  When using "...", the
-number of arguments may be larger than the total of mandatory and optional
-arguments.
-
-							*local-variables*
-Inside a function local variables can be used.  These will disappear when the
-function returns. Global variables need to be accessed with "g:".
-
-Example: >
-  :function Table(title, ...)
-  :  echohl Title
-  :  echo a:title
-  :  echohl None
-  :  echo a:0 .. " items:"
-  :  for s in a:000
-  :    echon ' ' .. s
-  :  endfor
-  :endfunction
-
-This function can then be called with: >
-  call Table("Table", "line1", "line2")
-  call Table("Empty Table")
-
-To return more than one value, return a |List|: >
-  :function Compute(n1, n2)
-  :  if a:n2 == 0
-  :    return ["fail", 0]
-  :  endif
-  :  return ["ok", a:n1 / a:n2]
-  :endfunction
-
-This function can then be called with: >
-  :let [success, div] = Compute(102, 6)
-  :if success == "ok"
-  :  echo div
-  :endif
-<
-						*:cal* *:call* *E107* *E117*
-:[range]cal[l] {name}([arguments])
-		Call a function.  The name of the function and its arguments
-		are as specified with `:function`.  Up to 20 arguments can be
-		used.  The returned value is discarded.
-		Without a range and for functions that accept a range, the
-		function is called once.  When a range is given the cursor is
-		positioned at the start of the first line before executing the
-		function.
-		When a range is given and the function doesn't handle it
-		itself, the function is executed for each line in the range,
-		with the cursor in the first column of that line.  The cursor
-		is left at the last line (possibly moved by the last function
-		call).  The arguments are re-evaluated for each line.  Thus
-		this works:
-						*function-range-example*  >
-	:function Mynumber(arg)
-	:  echo line(".") .. " " .. a:arg
-	:endfunction
-	:1,5call Mynumber(getline("."))
-<
-		The "a:firstline" and "a:lastline" are defined anyway, they
-		can be used to do something different at the start or end of
-		the range.
-
-		Example of a function that handles the range itself: >
-
-	:function Cont() range
-	:  execute (a:firstline + 1) .. "," .. a:lastline .. 's/^/\t\\ '
-	:endfunction
-	:4,8call Cont()
-<
-		This function inserts the continuation character "\" in front
-		of all the lines in the range, except the first one.
-
-		When the function returns a composite value it can be further
-		dereferenced, but the range will not be used then.  Example: >
-	:4,8call GetDict().method()
-<		Here GetDict() gets the range but method() does not.
-
-								*E132*
-The recursiveness of user functions is restricted with the |'maxfuncdepth'|
-option.
-
-It is also possible to use `:eval`.  It does not support a range, but does
-allow for method chaining, e.g.: >
-	eval GetList()->Filter()->append('$')
-
-A function can also be called as part of evaluating an expression or when it
-is used as a method: >
-	let x = GetList()
-	let y = GetList()->Filter()
-
-
-AUTOMATICALLY LOADING FUNCTIONS ~
-							*autoload-functions*
-When using many or large functions, it's possible to automatically define them
-only when they are used.  There are two methods: with an autocommand and with
-the "autoload" directory in 'runtimepath'.
-
-
-Using an autocommand ~
-
-This is introduced in the user manual, section |41.14|.
-
-The autocommand is useful if you have a plugin that is a long Vim script file.
-You can define the autocommand and quickly quit the script with `:finish`.
-That makes Vim startup faster.  The autocommand should then load the same file
-again, setting a variable to skip the `:finish` command.
-
-Use the FuncUndefined autocommand event with a pattern that matches the
-function(s) to be defined.  Example: >
-
-	:au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
-
-The file "~/vim/bufnetfuncs.vim" should then define functions that start with
-"BufNet".  Also see |FuncUndefined|.
-
-
-Using an autoload script ~
-							*autoload* *E746*
-This is introduced in the user manual, section |41.15|.
-
-Using a script in the "autoload" directory is simpler, but requires using
-exactly the right file name.  A function that can be autoloaded has a name
-like this: >
-
-	:call filename#funcname()
-
-When such a function is called, and it is not defined yet, Vim will search the
-"autoload" directories in 'runtimepath' for a script file called
-"filename.vim".  For example "~/.config/nvim/autoload/filename.vim".  That
-file should then define the function like this: >
-
-	function filename#funcname()
-	   echo "Done!"
-	endfunction
-
-The file name and the name used before the # in the function must match
-exactly, and the defined function must have the name exactly as it will be
-called.
-
-It is possible to use subdirectories.  Every # in the function name works like
-a path separator.  Thus when calling a function: >
-
-	:call foo#bar#func()
-
-Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
-
-This also works when reading a variable that has not been set yet: >
-
-	:let l = foo#bar#lvar
-
-However, when the autoload script was already loaded it won't be loaded again
-for an unknown variable.
-
-When assigning a value to such a variable nothing special happens.  This can
-be used to pass settings to the autoload script before it's loaded: >
-
-	:let foo#bar#toggle = 1
-	:call foo#bar#func()
-
-Note that when you make a mistake and call a function that is supposed to be
-defined in an autoload script, but the script doesn't actually define the
-function, you will get an error message for the missing function.  If you fix
-the autoload script it won't be automatically loaded again.  Either restart
-Vim or manually source the script.
+functions.  The function takes arguments, executes a sequence of Ex commands
+and can return a value.
 
-Also note that if you have two script files, and one calls a function in the
-other and vice versa, before the used function is defined, it won't work.
-Avoid using the autoload functionality at the toplevel.
+You can find most information about defining functions in |userfunc.txt|.
 
 ==============================================================================
 6. Curly braces names					*curly-braces-names*
diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt
index 04e31e0680..34213f7512 100644
--- a/runtime/doc/help.txt
+++ b/runtime/doc/help.txt
@@ -131,6 +131,7 @@ Advanced editing ~
 |autocmd.txt|	automatically executing commands on an event
 |eval.txt|	expression evaluation, conditional commands
 |builtin.txt|	builtin functions
+|userfunc.txt|	defining user functions
 |fold.txt|	hide (fold) ranges of lines
 |lua.txt|	Lua API
 |api.txt|	Nvim API via RPC, Lua and VimL
diff --git a/runtime/doc/userfunc.txt b/runtime/doc/userfunc.txt
new file mode 100644
index 0000000000..39c246e21d
--- /dev/null
+++ b/runtime/doc/userfunc.txt
@@ -0,0 +1,429 @@
+*userfunc.txt*	Nvim
+
+
+		  VIM REFERENCE MANUAL	  by Bram Moolenaar
+
+
+Defining and using functions.
+
+This is introduced in section |41.7| of the user manual.
+
+				      Type |gO| to see the table of contents.
+
+==============================================================================
+
+1. Defining a fuction ~
+						*define-function*
+New functions can be defined.  These can be called just like builtin
+functions.  The function executes a sequence of Ex commands.  Normal mode
+commands can be executed with the |:normal| command.
+
+The function name must start with an uppercase letter, to avoid confusion with
+builtin functions.  To prevent from using the same name in different scripts
+make them script-local.  If you do use a global function the avoid obvious,
+short names.  A good habit is to start the function name with the name of the
+script, e.g., "HTMLcolor()".
+
+It is also possible to use curly braces, see |curly-braces-names|.
+
+The |autoload| facility is useful to define a function only when it's called.
+
+							*local-function*
+A function local to a script must start with "s:".  A local script function
+can only be called from within the script and from functions, user commands
+and autocommands defined in the script.  It is also possible to call the
+function from a mapping defined in the script, but then |<SID>| must be used
+instead of "s:" when the mapping is expanded outside of the script.
+There are only script-local functions, no buffer-local or window-local
+functions.
+
+					*:fu* *:function* *E128* *E129* *E123*
+:fu[nction]		List all functions and their arguments.
+
+:fu[nction][!] {name}	List function {name}, annotated with line numbers
+			unless "!" is given.
+			{name} may be a |Dictionary| |Funcref| entry: >
+				:function dict.init
+
+:fu[nction] /{pattern}	List functions with a name matching {pattern}.
+			Example that lists all functions ending with "File": >
+				:function /File$
+<
+							*:function-verbose*
+When 'verbose' is non-zero, listing a function will also display where it was
+last defined. Example: >
+
+    :verbose function SetFileTypeSH
+	function SetFileTypeSH(name)
+	    Last set from /usr/share/vim/vim-7.0/filetype.vim
+<
+See |:verbose-cmd| for more information.
+
+						*E124* *E125* *E853* *E884*
+:fu[nction][!] {name}([arguments]) [range] [abort] [dict] [closure]
+			Define a new function by the name {name}.  The body of
+			the function follows in the next lines, until the
+			matching |:endfunction|.
+
+			The name must be made of alphanumeric characters and
+			'_', and must start with a capital or "s:" (see
+			above).  Note that using "b:" or "g:" is not allowed.
+			(since patch 7.4.260 E884 is given if the function
+			name has a colon in the name, e.g. for "foo:bar()".
+			Before that patch no error was given).
+
+			{name} can also be a |Dictionary| entry that is a
+			|Funcref|: >
+				:function dict.init(arg)
+<			"dict" must be an existing dictionary.  The entry
+			"init" is added if it didn't exist yet.  Otherwise [!]
+			is required to overwrite an existing function.  The
+			result is a |Funcref| to a numbered function.  The
+			function can only be used with a |Funcref| and will be
+			deleted if there are no more references to it.
+								*E127* *E122*
+			When a function by this name already exists and [!] is
+			not used an error message is given.  There is one
+			exception: When sourcing a script again, a function
+			that was previously defined in that script will be
+			silently replaced.
+			When [!] is used, an existing function is silently
+			replaced.  Unless it is currently being executed, that
+			is an error.
+			NOTE: Use ! wisely.  If used without care it can cause
+			an existing function to be replaced unexpectedly,
+			which is hard to debug.
+
+			For the {arguments} see |function-argument|.
+
+					*:func-range* *a:firstline* *a:lastline*
+			When the [range] argument is added, the function is
+			expected to take care of a range itself.  The range is
+			passed as "a:firstline" and "a:lastline".  If [range]
+			is excluded, ":{range}call" will call the function for
+			each line in the range, with the cursor on the start
+			of each line.  See |function-range-example|.
+			The cursor is still moved to the first line of the
+			range, as is the case with all Ex commands.
+								*:func-abort*
+			When the [abort] argument is added, the function will
+			abort as soon as an error is detected.
+								*:func-dict*
+			When the [dict] argument is added, the function must
+			be invoked through an entry in a |Dictionary|.  The
+			local variable "self" will then be set to the
+			dictionary.  See |Dictionary-function|.
+						*:func-closure* *E932*
+			When the [closure] argument is added, the function
+			can access variables and arguments from the outer
+			scope.  This is usually called a closure.  In this
+			example Bar() uses "x" from the scope of Foo().  It
+			remains referenced even after Foo() returns: >
+				:function! Foo()
+				:  let x = 0
+				:  function! Bar() closure
+				:    let x += 1
+				:    return x
+				:  endfunction
+				:  return funcref('Bar')
+				:endfunction
+
+				:let F = Foo()
+				:echo F()
+<				1 >
+				:echo F()
+<				2 >
+				:echo F()
+<				3
+
+						*function-search-undo*
+			The last used search pattern and the redo command "."
+			will not be changed by the function.  This also
+			implies that the effect of |:nohlsearch| is undone
+			when the function returns.
+
+				*:endf* *:endfunction* *E126* *E193* *W22*
+:endf[unction] [argument]
+			The end of a function definition.  Best is to put it
+			on a line by its own, without [argument].
+
+			[argument] can be:
+				| command	command to execute next
+				\n command	command to execute next
+				" comment	always ignored
+				anything else	ignored, warning given when
+						'verbose' is non-zero
+			The support for a following command was added in Vim
+			8.0.0654, before that any argument was silently
+			ignored.
+
+			To be able to define a function inside an `:execute`
+			command, use line breaks instead of |:bar|: >
+				:exe "func Foo()\necho 'foo'\nendfunc"
+<
+				*:delf* *:delfunction* *E131* *E933*
+:delf[unction][!] {name}
+			Delete function {name}.
+			{name} can also be a |Dictionary| entry that is a
+			|Funcref|: >
+				:delfunc dict.init
+<			This will remove the "init" entry from "dict".  The
+			function is deleted if there are no more references to
+			it.
+			With the ! there is no error if the function does not
+			exist.
+							*:retu* *:return* *E133*
+:retu[rn] [expr]	Return from a function.  When "[expr]" is given, it is
+			evaluated and returned as the result of the function.
+			If "[expr]" is not given, the number 0 is returned.
+			When a function ends without an explicit ":return",
+			the number 0 is returned.
+			Note that there is no check for unreachable lines,
+			thus there is no warning if commands follow ":return".
+
+			If the ":return" is used after a |:try| but before the
+			matching |:finally| (if present), the commands
+			following the ":finally" up to the matching |:endtry|
+			are executed first.  This process applies to all
+			nested ":try"s inside the function.  The function
+			returns at the outermost ":endtry".
+
+						*function-argument* *a:var*
+An argument can be defined by giving its name.  In the function this can then
+be used as "a:name" ("a:" for argument).
+					*a:0* *a:1* *a:000* *E740* *...*
+Up to 20 arguments can be given, separated by commas.  After the named
+arguments an argument "..." can be specified, which means that more arguments
+may optionally be following.  In the function the extra arguments can be used
+as "a:1", "a:2", etc.  "a:0" is set to the number of extra arguments (which
+can be 0).  "a:000" is set to a |List| that contains these arguments.  Note
+that "a:1" is the same as "a:000[0]".
+								*E742*
+The a: scope and the variables in it cannot be changed, they are fixed.
+However, if a composite type is used, such as |List| or |Dictionary| , you can
+change their contents.  Thus you can pass a |List| to a function and have the
+function add an item to it.  If you want to make sure the function cannot
+change a |List| or |Dictionary| use |:lockvar|.
+
+It is also possible to define a function without any arguments.  You must
+still supply the () then.
+
+It is allowed to define another function inside a function body.
+
+						*optional-function-argument*
+You can provide default values for positional named arguments.  This makes
+them optional for function calls.  When a positional argument is not
+specified at a call, the default expression is used to initialize it.
+This only works for functions declared with |function|, not for
+lambda expressions |expr-lambda|.
+
+Example: >
+  function Something(key, value = 10)
+     echo a:key .. ": " .. a:value
+  endfunction
+  call Something('empty')	"empty: 10"
+  call Something('key', 20)	"key: 20"
+
+The argument default expressions are evaluated at the time of the function
+call, not definition.  Thus it is possible to use an expression which is
+invalid the moment the function is defined.  The expressions are also only
+evaluated when arguments are not specified during a call.
+
+								*E989*
+Optional arguments with default expressions must occur after any mandatory
+arguments.  You can use "..." after all optional named arguments.
+
+It is possible for later argument defaults to refer to prior arguments,
+but not the other way around.  They must be prefixed with "a:", as with all
+arguments.
+
+Example that works: >
+  :function Okay(mandatory, optional = a:mandatory)
+  :endfunction
+Example that does NOT work: >
+  :function NoGood(first = a:second, second = 10)
+  :endfunction
+<
+When not using "...", the number of arguments in a function call must be at
+least equal to the number of mandatory named arguments.  When using "...", the
+number of arguments may be larger than the total of mandatory and optional
+arguments.
+
+							*local-variables*
+Inside a function local variables can be used.  These will disappear when the
+function returns. Global variables need to be accessed with "g:". Inside
+functions local variables are accessed without prepending anything. But you
+can also prepend "l:" if you like.  This is required for some reserved names,
+such as "version".
+
+Example: >
+  :function Table(title, ...)
+  :  echohl Title
+  :  echo a:title
+  :  echohl None
+  :  echo a:0 .. " items:"
+  :  for s in a:000
+  :    echon ' ' .. s
+  :  endfor
+  :endfunction
+
+This function can then be called with: >
+  call Table("Table", "line1", "line2")
+  call Table("Empty Table")
+
+To return more than one value, return a |List|: >
+  :function Compute(n1, n2)
+  :  if a:n2 == 0
+  :    return ["fail", 0]
+  :  endif
+  :  return ["ok", a:n1 / a:n2]
+  :endfunction
+
+This function can then be called with: >
+  :let [success, div] = Compute(102, 6)
+  :if success == "ok"
+  :  echo div
+  :endif
+<
+==============================================================================
+
+2. Calling a fuction ~
+						*:cal* *:call* *E107* *E117*
+:[range]cal[l] {name}([arguments])
+		Call a function.  The name of the function and its arguments
+		are as specified with `:function`.  Up to 20 arguments can be
+		used.  The returned value is discarded.
+		Without a range and for functions that accept a range, the
+		function is called once.  When a range is given the cursor is
+		positioned at the start of the first line before executing the
+		function.
+		When a range is given and the function doesn't handle it
+		itself, the function is executed for each line in the range,
+		with the cursor in the first column of that line.  The cursor
+		is left at the last line (possibly moved by the last function
+		call).  The arguments are re-evaluated for each line.  Thus
+		this works:
+						*function-range-example*  >
+	:function Mynumber(arg)
+	:  echo line(".") .. " " .. a:arg
+	:endfunction
+	:1,5call Mynumber(getline("."))
+<
+		The "a:firstline" and "a:lastline" are defined anyway, they
+		can be used to do something different at the start or end of
+		the range.
+
+		Example of a function that handles the range itself: >
+
+	:function Cont() range
+	:  execute (a:firstline + 1) .. "," .. a:lastline .. 's/^/\t\\ '
+	:endfunction
+	:4,8call Cont()
+<
+		This function inserts the continuation character "\" in front
+		of all the lines in the range, except the first one.
+
+		When the function returns a composite value it can be further
+		dereferenced, but the range will not be used then.  Example: >
+	:4,8call GetDict().method()
+<		Here GetDict() gets the range but method() does not.
+
+								*E132*
+The recursiveness of user functions is restricted with the |'maxfuncdepth'|
+option.
+
+It is also possible to use `:eval`.  It does not support a range, but does
+allow for method chaining, e.g.: >
+	eval GetList()->Filter()->append('$')
+
+A function can also be called as part of evaluating an expression or when it
+is used as a method: >
+	let x = GetList()
+	let y = GetList()->Filter()
+
+
+==============================================================================
+
+3. Automatically loading functions ~
+							*autoload-functions*
+When using many or large functions, it's possible to automatically define them
+only when they are used.  There are two methods: with an autocommand and with
+the "autoload" directory in 'runtimepath'.
+
+
+Using an autocommand ~
+
+This is introduced in the user manual, section |41.14|.
+
+The autocommand is useful if you have a plugin that is a long Vim script file.
+You can define the autocommand and quickly quit the script with `:finish`.
+That makes Vim startup faster.  The autocommand should then load the same file
+again, setting a variable to skip the `:finish` command.
+
+Use the FuncUndefined autocommand event with a pattern that matches the
+function(s) to be defined.  Example: >
+
+	:au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
+
+The file "~/vim/bufnetfuncs.vim" should then define functions that start with
+"BufNet".  Also see |FuncUndefined|.
+
+
+Using an autoload script ~
+							*autoload* *E746*
+This is introduced in the user manual, section |41.15|.
+
+Using a script in the "autoload" directory is simpler, but requires using
+exactly the right file name.  A function that can be autoloaded has a name
+like this: >
+
+	:call filename#funcname()
+
+When such a function is called, and it is not defined yet, Vim will search the
+"autoload" directories in 'runtimepath' for a script file called
+"filename.vim".  For example "~/.config/nvim/autoload/filename.vim".  That
+file should then define the function like this: >
+
+	function filename#funcname()
+	   echo "Done!"
+	endfunction
+
+The file name and the name used before the # in the function must match
+exactly, and the defined function must have the name exactly as it will be
+called.
+
+It is possible to use subdirectories.  Every # in the function name works like
+a path separator.  Thus when calling a function: >
+
+	:call foo#bar#func()
+
+Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
+
+This also works when reading a variable that has not been set yet: >
+
+	:let l = foo#bar#lvar
+
+However, when the autoload script was already loaded it won't be loaded again
+for an unknown variable.
+
+When assigning a value to such a variable nothing special happens.  This can
+be used to pass settings to the autoload script before it's loaded: >
+
+	:let foo#bar#toggle = 1
+	:call foo#bar#func()
+
+Note that when you make a mistake and call a function that is supposed to be
+defined in an autoload script, but the script doesn't actually define the
+function, you will get an error message for the missing function.  If you fix
+the autoload script it won't be automatically loaded again.  Either restart
+Vim or manually source the script.
+
+Also note that if you have two script files, and one calls a function in the
+other and vice versa, before the used function is defined, it won't work.
+Avoid using the autoload functionality at the toplevel.
+
+Hint: If you distribute a bunch of scripts you can pack them together with the
+|vimball| utility.  Also read the user manual |distribute-script|.
+
+
+ vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt
index ddf4d09e92..6386e4ace1 100644
--- a/runtime/doc/windows.txt
+++ b/runtime/doc/windows.txt
@@ -236,13 +236,13 @@ and 'winminwidth' are relevant.
 :vert[ical] {cmd}
 		Execute {cmd}.  If it contains a command that splits a window,
 		it will be split vertically.  For `vertical wincmd =` windows
-		will be equialized only vertically.
+		will be equalized only vertically.
 		Doesn't work for |:execute| and |:normal|.
 
 						*:hor* *:horizontal*
 :hor[izontal] {cmd}
 		Execute {cmd}.  Currently only makes a difference for
-		`horizontal wincmd =`, which will equal windows only
+		`horizontal wincmd =`, which will equalize windows only
 		horizontally.
 
 :lefta[bove] {cmd}				*:lefta* *:leftabove*