diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt
index cf799a9..59004af 100644
--- a/runtime/doc/change.txt
+++ b/runtime/doc/change.txt
@@ -1,4 +1,4 @@
-*change.txt*    For Vim version 8.2.  Last change: 2020 Apr 11
+*change.txt*    For Vim version 8.2.  Last change: 2020 Apr 26
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -996,9 +996,9 @@
 5. Copying and moving text				*copy-move*
 
 							*quote*
-"{a-zA-Z0-9.%#:-"}	Use register {a-zA-Z0-9.%#:-"} for next delete, yank
-			or put (use uppercase character to append with
-			delete and yank) ({.%#:} only work with put).
+"{register}		Use {register} for next delete, yank or put.  Use
+			an uppercase character to append with delete and yank.
+			Registers ".", "%", "#" and ":" only work with put.
 
 							*:reg* *:registers*
 :reg[isters]		Display the type and contents of all numbered and
diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt
index a01d4b9..ecaa73e 100644
--- a/runtime/doc/cmdline.txt
+++ b/runtime/doc/cmdline.txt
@@ -1,4 +1,4 @@
-*cmdline.txt*   For Vim version 8.2.  Last change: 2020 Feb 29
+*cmdline.txt*   For Vim version 8.2.  Last change: 2020 Apr 23
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -615,6 +615,7 @@
     :tcl
     :tcldo
     :tclfile
+    :terminal
     :vglobal
     :windo
     :write !
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 02ed78b..8086bd5 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -2646,7 +2646,7 @@
 				none	remove all text properties
 prop_find({props} [, {direction}])
 				Dict	search for a text property
-prop_list({lnum} [, {props})	List	text properties in {lnum}
+prop_list({lnum} [, {props}])	List	text properties in {lnum}
 prop_remove({props} [, {lnum} [, {lnum-end}]])
 				Number	remove a text property
 prop_type_add({name}, {props})	none	define a new property type
@@ -2654,7 +2654,7 @@
 				none	change an existing property type
 prop_type_delete({name} [, {props}])
 				none	delete a property type
-prop_type_get([{name} [, {props}])
+prop_type_get([{name} [, {props}]])
 				Dict	get property type values
 prop_type_list([{props}])	List	get list of property types
 pum_getpos()			Dict	position and size of pum if visible
@@ -3050,7 +3050,7 @@
 		{winnr} can be the window number or the |window-ID|.
 
 							*argv()*
-argv([{nr} [, {winid}])
+argv([{nr} [, {winid}]])
 		The result is the {nr}th file in the argument list.  See
 		|arglist|.  "argv(0)" is the first one.  Example: >
 	:let i = 0
@@ -5854,7 +5854,7 @@
 
 		Note that to skip code that has a syntax error when the
 		feature is not available, Vim may skip the rest of the line
-		and miss a following `endif`.  Therfore put the `endif` on a
+		and miss a following `endif`.  Therefore put the `endif` on a
 		separate line: >
 			if has('feature')
 			  let x = this->breaks->without->the->feature
diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt
index d858be1..7de6fb6 100644
--- a/runtime/doc/help.txt
+++ b/runtime/doc/help.txt
@@ -198,13 +198,13 @@
 |os_amiga.txt|	Amiga
 |os_beos.txt|	BeOS and BeBox
 |os_dos.txt|	MS-DOS and MS-Windows common items
+|os_haiku.txt|	Haiku
 |os_mac.txt|	Macintosh
 |os_mint.txt|	Atari MiNT
 |os_msdos.txt|	MS-DOS (plain DOS and DOS box under Windows)
 |os_os2.txt|	OS/2
 |os_qnx.txt|	QNX
 |os_risc.txt|	RISC-OS
-|os_haiku.txt|	Haiku
 |os_unix.txt|	Unix
 |os_vms.txt|	VMS
 |os_win32.txt|	MS-Windows
diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt
index e5a3bd6..315a5f3 100644
--- a/runtime/doc/index.txt
+++ b/runtime/doc/index.txt
@@ -1,4 +1,4 @@
-*index.txt*     For Vim version 8.2.  Last change: 2020 Mar 27
+*index.txt*     For Vim version 8.2.  Last change: 2020 Apr 26
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -246,8 +246,7 @@
 				2  filter Nmove text through the {filter}
 				   command
 |!!|		!!{filter}	2  filter N lines through the {filter} command
-|quote|		"{a-zA-Z0-9.%#:-"}  use register {a-zA-Z0-9.%#:-"} for next
-				   delete, yank or put (uppercase to append)
+|quote|		"{register}  	   use {register} for next delete, yank or put
 				   ({.%#:} only work with put)
 |#|		#		1  search backward for the Nth occurrence of
 				   the ident under the cursor
@@ -1115,7 +1114,7 @@
 |t_CTRL-W_:|	CTRL-W :	enter an Ex command
 |t_CTRL-W_.|	CTRL-W .	type CTRL-W in the terminal
 		CTRL-W CTRL-\	send a CTRL-\ to the job in the terminal
-|t_CTRL-W_quote|  CTRL-W " {0-9a-z"%#*:=}
+|t_CTRL-W_quote|  CTRL-W " {register}
 				paste register in the terminal
 |t_CTRL-W_CTRL-C| CTRL-W CTRL-C	forcefully ends the job
 |t_CTRL-W_CTRL-W| CTRL-W CTRL-W	move focus to the next window
diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt
index ff74d62..fed81e5 100644
--- a/runtime/doc/insert.txt
+++ b/runtime/doc/insert.txt
@@ -1,4 +1,4 @@
-*insert.txt*    For Vim version 8.2.  Last change: 2020 Mar 25
+*insert.txt*    For Vim version 8.2.  Last change: 2020 Apr 30
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -666,7 +666,7 @@
 ends CTRL-X mode (any key that is not a valid CTRL-X mode command) is mapped.
 Also, when doing completion with 'complete' mappings apply as usual.
 
-							*E565*
+							*E578* *E565*
 Note: While completion is active Insert mode can't be used recursively and
 buffer text cannot be changed.  Mappings that somehow invoke ":normal i.."
 will generate an E565 error.
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index bf643c0..c142f23 100644
--- a/runtime/doc/map.txt
+++ b/runtime/doc/map.txt
@@ -1,4 +1,4 @@
-*map.txt*       For Vim version 8.2.  Last change: 2019 Dec 19
+*map.txt*       For Vim version 8.2.  Last change: 2020 Apr 23
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -1492,7 +1492,7 @@
 	<bang>	(See the '-bang' attribute) Expands to a ! if the
 		command was executed with a ! modifier, otherwise
 		expands to nothing.
-						*<mods>*
+						*<mods>* *:command-modifiers*
 	<mods>  The command modifiers, if specified. Otherwise, expands to
 		nothing. Supported modifiers are |:aboveleft|, |:belowright|,
 		|:botright|, |:browse|, |:confirm|, |:hide|, |:keepalt|,
diff --git a/runtime/doc/os_haiku.txt b/runtime/doc/os_haiku.txt
index 1ca3384..6eff91c 100644
--- a/runtime/doc/os_haiku.txt
+++ b/runtime/doc/os_haiku.txt
@@ -25,8 +25,9 @@
  9. The meta key modifier	|haiku-meta|
 10. Mouse key mappings		|haiku-mouse|
 11. Color names			|haiku-colors|
-12. Credits			|haiku-support-credits|
-13. Bugs & to-do		|haiku-bugs|
+12. GUI Toolbar Images		|haiku-toolbar-images|
+13. Credits			|haiku-support-credits|
+14. Bugs & to-do		|haiku-bugs|
 
 
 1. General						*haiku-general*
@@ -223,7 +224,7 @@
 Thank you, all!
 
 
-13. Bugs & to-do					*haiku-bugs*
+14. Bugs & to-do					*haiku-bugs*
  
 The port is under development now and far away from the perfect state. For bug
 reports, patches and wishes, please use the Vim mailing list or Vim Github
diff --git a/runtime/doc/os_win32.txt b/runtime/doc/os_win32.txt
index 7f37845..1017d4d 100644
--- a/runtime/doc/os_win32.txt
+++ b/runtime/doc/os_win32.txt
@@ -230,7 +230,7 @@
    SCO declares this behavior required for backwards compatibility with 16bit
    DOS/Windows environments.  The two commands below demonstrate the behavior:
 >
-	echo Hello > file.bat~ 
+	echo Hello > file.bat~
 	dir > file.bat
 <
    The result is that the "dir" command updates the "file.bat~" file, instead
diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt
index 04e09d3..365f6da 100644
--- a/runtime/doc/repeat.txt
+++ b/runtime/doc/repeat.txt
@@ -1,4 +1,4 @@
-*repeat.txt*    For Vim version 8.2.  Last change: 2019 Dec 07
+*repeat.txt*    For Vim version 8.2.  Last change: 2020 Apr 26
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -166,7 +166,7 @@
 			[addr] (default is current line).
 
 :[addr]@							*:@@*
-:[addr]@@		Repeat the previous :@{0-9a-z"}.  First set cursor at
+:[addr]@@		Repeat the previous :@{register}.  First set cursor at
 			line [addr] (default is current line).
 
 ==============================================================================
diff --git a/runtime/doc/tags b/runtime/doc/tags
index 301336c..e8d7d25 100644
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -2272,6 +2272,7 @@
 :command-completion-custom	map.txt	/*:command-completion-custom*
 :command-completion-customlist	map.txt	/*:command-completion-customlist*
 :command-count	map.txt	/*:command-count*
+:command-modifiers	map.txt	/*:command-modifiers*
 :command-nargs	map.txt	/*:command-nargs*
 :command-range	map.txt	/*:command-range*
 :command-register	map.txt	/*:command-register*
@@ -4363,6 +4364,7 @@
 E562	if_cscop.txt	/*E562*
 E563	if_cscop.txt	/*E563*
 E564	if_cscop.txt	/*E564*
+E565	insert.txt	/*E565*
 E566	if_cscop.txt	/*E566*
 E567	if_cscop.txt	/*E567*
 E568	if_cscop.txt	/*E568*
@@ -4374,6 +4376,7 @@
 E575	starting.txt	/*E575*
 E576	starting.txt	/*E576*
 E577	starting.txt	/*E577*
+E578	insert.txt	/*E578*
 E579	eval.txt	/*E579*
 E580	eval.txt	/*E580*
 E581	eval.txt	/*E581*
@@ -9959,6 +9962,7 @@
 vim.vim	syntax.txt	/*vim.vim*
 vim7	version7.txt	/*vim7*
 vim8	version8.txt	/*vim8*
+vim9	vim9.txt	/*vim9*
 vim9-differences	vim9.txt	/*vim9-differences*
 vim9-export	vim9.txt	/*vim9-export*
 vim9-import	vim9.txt	/*vim9-import*
diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt
index 8105b07..ddc0906 100644
--- a/runtime/doc/terminal.txt
+++ b/runtime/doc/terminal.txt
@@ -1,4 +1,4 @@
-*terminal.txt*	For Vim version 8.2.  Last change: 2020 Mar 26
+*terminal.txt*	For Vim version 8.2.  Last change: 2020 Apr 23
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -120,7 +120,7 @@
 You can also create menus similar to terminal mode mappings, but you have to
 use |:tlmenu| instead of |:tmenu|.
 
-<							*options-in-terminal*
+							*options-in-terminal*
 After opening the terminal window and setting 'buftype' to "terminal" the
 TerminalOpen autocommand event is triggered.  This makes it possible to set
 options specifically for the window and buffer.  Example: >
@@ -183,6 +183,10 @@
 			keep the terminal open in Terminal-Normal mode.  This
 			can be changed with the ++close argument.
 
+			No Vim command can follow, any | is included in
+			[command].  Use `:execute` if you must have a Vim
+			command following in the same line.
+
 			A new buffer will be created, using [command] or
 			'shell' as the name, prefixed with a "!".  If a buffer
 			by this name already exists a number is added in
diff --git a/runtime/doc/textprop.txt b/runtime/doc/textprop.txt
index 5d55952..0793940 100644
--- a/runtime/doc/textprop.txt
+++ b/runtime/doc/textprop.txt
@@ -101,7 +101,7 @@
 prop_type_add({name}, {props})		define a new property type
 prop_type_change({name}, {props})	change an existing property type
 prop_type_delete({name} [, {props}])	delete a property type
-prop_type_get([{name} [, {props}])	get property type values
+prop_type_get([{name} [, {props}]])	get property type values
 prop_type_list([{props}])		get list of property types
 
 
@@ -111,7 +111,7 @@
 prop_clear({lnum} [, {lnum-end} [, {bufnr}]])
 					remove all text properties
 prop_find({props} [, {direction}])	search for a text property
-prop_list({lnum} [, {props})  		text properties in {lnum}
+prop_list({lnum} [, {props}])  		text properties in {lnum}
 prop_remove({props} [, {lnum} [, {lnum-end}]])
 					remove a text property
 
@@ -291,7 +291,7 @@
 		Can also be used as a |method|: >
 			GetPropName()->prop_type_delete()
 
-prop_type_get([{name} [, {props}])			*prop_type_get()*
+prop_type_get([{name} [, {props}]])			*prop_type_get()*
 		Returns the properties of property type {name}.  This is a
 		dictionary with the same fields as was given to
 		prop_type_add().
diff --git a/runtime/doc/todo.txt b/runtime/doc/todo.txt
index 14756f0..fe41907 100644
--- a/runtime/doc/todo.txt
+++ b/runtime/doc/todo.txt
@@ -1,4 +1,4 @@
-*todo.txt*      For Vim version 8.2.  Last change: 2020 Apr 20
+*todo.txt*      For Vim version 8.2.  Last change: 2020 Apr 30
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -39,38 +39,59 @@
 -------------------- Known bugs and current work -----------------------
 
 Vim9 script:
-more tests for # comments:
-  check all calls to ends_excmd() and test that space before # is needed.
-  next: ex_findpat()
-func and partial types:
-- Calling unknown user function does not give proper error message:
-      assert_equal('123text', RefDef2Arg())  typo for "RetDef2Arg"
-- "func" inside "vim9script" doesn't work?  (Ben Jackson, #5670)
-- :func inside vim9script must still use a:arg
-- define function and create funcref in one step:
-	let ref = def(arg: type): rettype
-	    body
-	enddef
+Big changes, need design:
+- Make closures work:
+  Grab the part of the stack that has the arguments and local vars.
+  Pass a pointer and offset to the closure where this stack fragment is (frame
+  pointer).
+  When a closure disappears at end of the function - nothing to do.
+  When a closure remains at end of the function: copy frame, attach to closure.
+- At the vim9 script level: Allow using a function that is defined later.
+  Requires compiling functions only when the whole script has been sourced.
+  Like Javascript "hoisting", but only at the script level:
+  1. Discovery phase: Read the file to find all functions, variable
+     declarations and imports If a variable has a constant expression we get
+     the type, otherwise it will be "any".  Follow imports recursively.
+  2. Compilation phase: compile :def function bodies, using declared types
+  3. Execution phase: Execute imports when encountered. (skip over functions)
+- When sourcing a script again, also delete script-local variables.
+Making everything work:
 - Test that a script-local function in Vim9 script cannot be deleted.
 - Test that a function defined inside a :def function is local to that
   function, g: functions can be defined and script-local functions cannot be
   defined.
-Also:
-- When wildcards are expanded, find `=expr` and evaluate it before invoking
-  the command. For example:  :edit `=filename`
+- Check that when using a user function name without prefix, it does not find
+  a global function.  Prefixing g: is required.
+- Compile let [var, var] = expr
+- Compile replacement of :s command: s/pat/\=expr/
+- Compile redir to local variable: var_redir_start().
+- Compile builtin functions that access local variables:
+    islocked()
+- Expand `=expr` in :next, :argedit, :argadd, :argdelete, :drop
+- Expand `=expr` in :vimgrep, :vimgrepadd, :lvimgrep, :lvimgrepadd
+- Expand `=expr` in :mkspell
+- Support type for ":let"/":const" at script level for Vim9 script.
+    (Ben Jackson, #5671)
+    Can we share the code from ex_let_const() between direct execution and
+    compiling?
+- Disallow unlet for local/script/imported vars
+- Make "++nr" work.
+- expandcmd() with `=expr` in filename uses legacy expression.
+- eval_expr() in ex_cexpr()
+- eval_expr() call in dbg_parsearg() and debuggy_find()
+New syntax and functionality:
+- define function and create funcref in one step:
+	let ref = def(arg: type): rettype
+	    body
+	enddef
+Improve error checking:
 - "echo Func()" is an error if Func() does not return anything.
-- Check all Ex commands, give error if they use an expression and should be
-  compiled.
+Also:
 - For range: make table of first ASCII character with flag to quickly check if
   it can be a Vim9 command. E.g. "+" can, but "." can't.
 - better implementation for partial and tests for that.
 - Make "g:imported = Export.exported" work in Vim9 script.
 - Make Foo.Bar() work to call the dict function. (#5676)
-- Support type for ":let"/":const" at script level for Vim9 script.
-    (Ben Jackson, #5671)
-    Can we share the code for :let between direct execution and compiling?
-- Disallow unlet for local/script/imported vars
-- Make "++nr" work.
 - Check that import in legacy script works and puts item in s:
 - Error in any command in "vim9script" aborts sourcing.
 - Find a way to test expressions in legacy and Vim9 script without duplication
@@ -93,6 +114,13 @@
 - Make accessing varargs faster: arg[expr]
 	EVAL expr
 	LOADVARARG (varags idx)
+Further improvements:
+- compile options that are an expression, e.g. "expr:" in 'spellsuggest',
+  'foldexpr', 'foldtext', 'printexpr', 'diffexpr', 'patchexpr', 'charconvert',
+  'balloonexpr', 'includeexpr', 'indentexpr', 'formatexpr'.
+- compile get_lambda_tv() in popup_add_timeout()
+- compile "skip" argument of searchpair()
+- compile "expr" and "call" expression of a channel in channel_exe_cmd()?
 
 Popup windows:
 - With some sequence get get hidden finished terminal buffer. (#5768)
@@ -198,7 +226,7 @@
   conversions.
 
 Error numbers available:
-E453, E454, E460, E489, E491, E565, E578, E610, E611, E653,
+E453, E454, E460, E489, E491, E610, E611, E653,
 E856, E857, E861, E900
 
 Buffer autocommands are a bit inconsistent.  Add a separate set of
@@ -222,8 +250,13 @@
 
 Patch to add "-d" to xxd. (#5616)
 
+Patch for the Haiku port: #5961
+
 Patch to add Turkish manual. (Emir Sarı, #5641)
 
+Patch to support different color for undercurl in cterm.
+(Timur Celik, #6011)
+
 Patch to support cindent option to handle pragmas differently.
 (Max Rumpf, #5468)
 
@@ -234,6 +267,9 @@
 Athena is OK.
 Motif: Build on Ubuntu can't enter any text in dialog text fields.
 
+:map output does not clear the reset of the command line.
+(#5623, also see #5962)
+
 Patch to properly break CJK lines: Anton Kochkov, #3875
 Flag in 'formatoptions' is not used in the tests.
 
@@ -248,7 +284,10 @@
 When 'lazyredraw' is set sometimes the title is not updated.
 (Jason Franklin, 2020 Feb 3)  Looks like a race condition.
 
-Patch to delete BeOS code. (#5817)
+Patch to delete BeOS code. (#5817)  Anyone who wants to keep it?
+
+With bash ":make" does not set v:shell_error.  Possible solution: set
+'shellpipe' to "2>&1| tee %s; exit ${PIPESTATUS[0]}"  #5994
 
 Strange sequence of BufWipeout and BufNew events while doing omni-complete.
 (Paul Jolly, #5656)
@@ -317,6 +356,8 @@
 
 Patch to include reduce() function. (#5481)
 
+When SIGTSTP is ignored, don't let CTRL-Z suspend Vim? (Kurtis Rader, #5990)
+
 Statusline highlighting error, off by one. (#5599)
 
 Enable 'termbidi' if $VTE_VERSION >= 5703 ?
@@ -331,11 +372,6 @@
 The :syntax cchar value can only be a single character.  It would be useful to
 support combining characters. (Charles Campbell)  Also #4687
 
-Include Haiku port. (Adrien Destugues, Siarzhuk Zharski, 2013 Oct 24)
-It can replace the BeOS code, which is likely not used anymore.
-Now on github: #1856.  Updated Oct 2017
-Got permission to include this under the Vim license.
-
 "--cleanFOO" does not result in an error. (#5537)
 
 Add "t" action to settagstack(): truncate and add new entries. (#5405)
diff --git a/runtime/doc/usr_08.txt b/runtime/doc/usr_08.txt
index a5e21f3..57287d0 100644
--- a/runtime/doc/usr_08.txt
+++ b/runtime/doc/usr_08.txt
@@ -402,7 +402,7 @@
 "main.c" file, then make a split and show the differences: >
 
 	:edit main.c
-	:vertical diffsplit main.c~ 
+	:vertical diffsplit main.c~
 
 The ":vertical" command is used to make the window split vertically.  If you
 omit this, you will get a horizontal split.
diff --git a/runtime/doc/usr_10.txt b/runtime/doc/usr_10.txt
index d579919..7898618 100644
--- a/runtime/doc/usr_10.txt
+++ b/runtime/doc/usr_10.txt
@@ -687,7 +687,7 @@
 lowercase.  This can be shortened to "guu".  "gUgU" is shortened to "gUU" and
 "g~g~" to "g~~".  Example: >
 
-				g~~ 
+				g~~
 <	Some GIRLS have Fun    ---->   sOME girls HAVE fUN ~
 
 ==============================================================================
diff --git a/runtime/doc/vim9.txt b/runtime/doc/vim9.txt
index 704e801..525393d 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 Apr 19
+*vim9.txt*	For Vim version 8.2.  Last change: 2020 Apr 30
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -6,7 +6,7 @@
 
 THIS IS STILL UNDER DEVELOPMENT - ANYTHING CAN BREAK - ANYTHING CAN CHANGE
 
-Vim9 script commands and expressions.
+Vim9 script commands and expressions.			*vim9*
 
 Most expression help is in |eval.txt|.  This file is about the new syntax and
 features in Vim9 script.
@@ -28,29 +28,32 @@
 
 THIS IS STILL UNDER DEVELOPMENT - ANYTHING CAN BREAK - ANYTHING CAN CHANGE
 
-Vim script has been growing over time, while keeping backwards compatibility.
-That means bad choices from the past often can't be changed.  Execution is
-quite slow, every line is parsed every time it is executed.
+Vim script has been growing over time, while preserving backwards
+compatibility.  That means bad choices from the past often can't be changed
+and compability with Vi restricts possible solutions.  Execution is quite
+slow, each line is parsed every time it is executed.
 
-The main goal of Vim9 script is to drastically improve performance.  An
-increase in execution speed of 10 to 100 times can be expected.  A secondary
-goal is to avoid Vim-specific constructs and get closer to commonly used
-programming languages, such as JavaScript, TypeScript and Java.
+The main goal of Vim9 script is to drastically improve performance.  This is
+accomplished by compiling commands into instructions that can be efficiently
+executed.  An increase in execution speed of 10 to 100 times can be expected.
+
+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, as creating that dictionary adds quite a lot of overhead.
-Other differences are more subtle, such as how errors are handled.
+"a:" dictionary, because creating that dictionary adds quite a lot of
+overhead.  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
 - a script file where the first command is `vim9script`
 
 When using `:function` in a Vim9 script file the legacy syntax is used.
-However, this is discouraged.
+However, this can be confusing and is therefore discouraged.
 
-Vim9 script and legacy Vim script can be mixed.  There is no need to rewrite
-old scripts, they keep working as before.
+Vim9 script and legacy Vim script can be mixed.  There is no requirement to
+rewrite old scripts, they keep working as before.
 
 ==============================================================================
 
@@ -62,9 +65,9 @@
 
 In Vim script comments normally start with double quote.  That can also be the
 start of a string, thus in many places it cannot be used.  In Vim9 script a
-comment can also start with #.  Normally this is a command to list text with
+comment can also start with #.  In Vi this is a command to list text with
 numbers, but you can also use `:number` for that. >
-	let count = 0  # number of occurences of Ni!
+	let count = 0  # number of occurences
 
 To improve readability there must be a space between the command and the #
 that starts a comment.  Note that #{ is the start of a dictionary, therefore
@@ -73,40 +76,59 @@
 
 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.
+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.
 
-In the function body:
-- Arguments are accessed by name, without "a:".
-- There is no "a:" dictionary or "a:000" list.  Variable arguments are defined
-  with a name and have a list type: >
-  	def MyFunc(...itemlist: list<type>)
+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
+functions.
+
+Arguments are accessed by name, without "a:".  There is no "a:" dictionary or
+"a:000" list.
+
+Variable arguments are defined as the last argument, with a name and have a
+list type, similar to Typescript.  For example, a list of numbers: >
+  	def MyFunc(...itemlist: list<number>)
 	   for item in itemlist
 	     ...
 
 
-Functions are script-local by default ~
+Functions and variables are script-local by default ~
 
 When using `:function` or `:def` to specify a new function at the script level
 in a Vim9 script, the function is local to the script, as if "s:" was
-prefixed.  To define a global function the "g:" prefix must be used.
+prefixed.  Using the "s:" prefix is optional.
+
+To define or use a global function or variable the "g:" prefix must be used.
 
 When using `:function` or `:def` to specify a new function inside a function,
 the function is local to the function.  It is not possible to define a
-script-local function inside a function. To define a global function the "g:"
-prefix must be used.
+script-local function inside a function. It is possible to define a global
+function, using the "g:" prefix.
 
 When referring to a function and no "s:" or "g:" prefix is used, Vim will
 search for the function in this order:
-- Local to the current function scope.
+- Local to the current scope and outer scopes up to the function scope.
 - Local to the current script file.
 - Imported functions, see `:import`.
-- Global.
+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?)
+
+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
+variables could be defined anywhere (good luck finding where!).
 
 Global functions can 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.
+cannot be deleted.  Except that when the same script is sourced again all
+existing script-local functions and variables are deleted.
 
 
 Variable declarations with :let and :const ~
@@ -156,12 +178,12 @@
 Variables cannot shadow previously defined variables.
 Variables may shadow Ex commands, rename the variable if needed.
 
-Global variables must be prefixed with "g:", also at the script level.
-However, global user defined functions are used without "g:". >
+Global variables and user defined functions must be prefixed with "g:", also
+at the script level. >
 	vim9script
 	let script_local = 'text'
 	let g:global = 'value'
-	let Funcref = ThatFunction
+	let Funcref = g:ThatFunction
 
 Since "&opt = value" is now assigning a value to option "opt", ":&" cannot be
 used to repeat a `:substitute` command.