Update runtime files

1 files changed, 25 insertions, 64 deletions

diff --git a/runtime/doc/vim9.txt b/runtime/doc/vim9.txt
index 3eec280364..9a74b3ae7b 100644
--- a/runtime/doc/vim9.txt
+++ b/runtime/doc/vim9.txt
@@ -1,4 +1,4 @@
-*vim9.txt*	For Vim version 8.2.  Last change: 2020 May 09
+*vim9.txt*	For Vim version 8.2.  Last change: 2020 May 25
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -41,9 +41,10 @@ A secondary goal is to avoid Vim-specific constructs and get closer to
 commonly used programming languages, such as JavaScript, TypeScript and Java.
 
 The performance improvements can only be achieved by not being 100% backwards
-compatible.  For example, in a function the arguments are not available in the
-"a:" dictionary, because creating that dictionary adds quite a lot of
-overhead.  Other differences are more subtle, such as how errors are handled.
+compatible.  For example, making function arguments available in the
+"a:" dictionary adds quite a lot of overhead.  In a Vim9 function this
+dictionary is not available.  Other differences are more subtle, such as how
+errors are handled.
 
 The Vim9 script syntax and semantics are used in:
 - a function defined with the `:def` command
@@ -79,12 +80,16 @@ Vim9 functions ~
 A function defined with `:def` is compiled.  Execution is many times faster,
 often 10x to 100x times.
 
-Many errors are already found when compiling, before the function is called.
+Many errors are already found when compiling, before the function is executed.
 The syntax is strict, to enforce code that is easy to read and understand.
 
-`:def` has no extra arguments like `:function` does: "range", "abort", "dict"
-or "closure".  A `:def` function always aborts on an error, does not get a
-range passed and cannot be a "dict" function.
+Compilation is done when the function is first called, or when the
+`:defcompile` command is encountered in the script where the function was
+defined.
+
+`:def` has no options like `:function` does: "range", "abort", "dict" or
+"closure".  A `:def` function always aborts on an error, does not get a range
+passed and cannot be a "dict" function.
 
 The argument types and return type need to be specified.  The "any" type can
 be used, type checking will then be done at runtime, like with legacy
@@ -118,8 +123,8 @@ search for the function in this order:
 - Local to the current scope and outer scopes up to the function scope.
 - Local to the current script file.
 - Imported functions, see `:import`.
-In all cases the function must be defined before used.  To make a call cycle a
-global function needs to be used. (TODO: can we fix this?)
+In all cases the function must be defined before used.  That is when it is
+first called or when `:defcompile` causes the call to be compiled.
 
 The result is that functions and variables without a namespace can always be
 found in the script, either defined there or imported.  Global functions and
@@ -127,57 +132,7 @@ variables could be defined anywhere (good luck finding where!).
 
 Global functions can be still be defined and deleted at nearly any time.  In
 Vim9 script script-local functions are defined once when the script is sourced
-and cannot be deleted.
-
-
-Four phases when loading a Vim9 script ~
-
-In legacy script the functions are created when encountered, but parsed only
-when used.  This allows for defining functions in any order and having them
-call each other, so long as the function is defined when it is called: >
-	func One()
-	   call Two()
-	endfunc
-	func Two()
-	   if cond
-	      call One()  " recursive call
-	   endif
-	endfunc
-	call One()
-
-In Vim9 script the functions are compiled.  When using the same functions as
-the above example it is not possible to compile function One without knowing
-that function Two exists. Or this would require a runtime check, which is slow
-and does not allow for compile time type checking.
-
-When sourcing a Vim9 script this happens in four phases:
-1. Cleanup: If the script was sourced before all script-local variables,
-   imports and functions are deleted.
-2. Discovery: The script is read and declarations of functions, imports and
-   variables are recognized and the type is parsed.  Variable initializers
-   that are a constant are evaluated, this can also give the type of the
-   variable.
-3. Compilation: Functions are compiled.  The script-local functions, imports
-   and variables from the discovery phase are found and types are checked.
-4. Execution: the commands in the script are executed, top to bottom.
-   Functions are skipped over, they do do not need to be processed again.
-   Variable initializers are evaluated when encountered.  Note that if a
-   function called earlier has set the value this will be over-written. It is
-   best to declare variables before where they are used to avoid confusion.
-
-The result is that items defined at the script level can be used anywhere in
-the script. This allows for putting the main function at the top: >
-	def Main()
-	  SubOne()
-	  SubTwo()
-	enddef
-	def SubOne()
-	  ...
-	def SubTwo()
-	  ...
-
-Note that script-local variables should either have a type defined or have a
-constant initializer.  Otherwise an error is given for the type being unknown.
+and cannot be deleted or replaced.
 
 
 Variable declarations with :let and :const ~
@@ -212,8 +167,8 @@ The declaration must be done earlier: >
 	endif
 	echo inner
 
-To intentionally use a variable that won't be available later, a block can be
-used: >
+To intentionally avoid a variable being available later, a block can be used:
+>
 	{
 	   let temp = 'temp'
 	   ...
@@ -437,7 +392,9 @@ THIS IS STILL UNDER DEVELOPMENT - ANYTHING CAN BREAK - ANYTHING CAN CHANGE
 			`:def`, but it is not possible to nest `:def` inside
 			`:function`, for backwards compatibility.
 
-			[!] is used as with `:function`.
+			[!] is used as with `:function`.  Note that in Vim9
+			script script-local functions cannot be deleted or
+			redefined.
 
 							*:enddef*
 :enddef			End of a function defined with `:def`.
@@ -448,6 +405,10 @@ variables can be accessed without the "s:" prefix.  They must be defined
 before the function.  If the script the function is defined in is legacy
 script, then script-local variables must be accessed with the "s:" prefix.
 
+						*:defc* *:defcompile*
+:defc[ompile]		Compile functions defined in the current script that
+			were not compiled yet.
+			This will report errors found during the compilation.
 
 						*:disa* *:disassemble*
 :disa[ssemble] {func}	Show the instructions generated for {func}.