Update runtime files

1 files changed, 764 insertions, 795 deletions

diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index 89bd542825..a9abe59be1 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -1,4 +1,4 @@
-*usr_41.txt*	For Vim version 8.2.  Last change: 2021 Sep 10
+*usr_41.txt*	For Vim version 8.2.  Last change: 2021 Dec 30
 
 		     VIM USER MANUAL - by Bram Moolenaar
 
@@ -37,7 +37,8 @@ Your first experience with Vim scripts is the vimrc file.  Vim reads it when
 it starts up and executes the commands.  You can set options to values you
 prefer.  And you can use any colon command in it (commands that start with a
 ":"; these are sometimes referred to as Ex commands or command-line commands).
-   Syntax files are also Vim scripts.  As are files that set options for a
+
+Syntax files are also Vim scripts.  As are files that set options for a
 specific file type.  A complicated macro can be defined by a separate Vim
 script file.  You can think of other uses yourself.
 
@@ -47,23 +48,25 @@ script file.  You can think of other uses yourself.
 	And if you are familiar with JavaScript:
 	   https://w0rp.com/blog/post/vim-script-for-the-javascripter/
 
+Vim script comes in two flavors: legacy and |Vim9|.  Since this help file is
+for new users, we'll teach you the newer and more convenient |Vim9| syntax.
+
+To try out Vim script the best way is to edit a script file and source it.
+Basically: >
+	:edit test.vim
+	[insert the script lines you want]
+	:w
+	:source %
+
 Let's start with a simple example: >
 
-	:let i = 1
-	:while i < 5
-	:  echo "count is" i
-	:  let i += 1
-	:endwhile
+	vim9script
+	var i = 1
+	while i < 5
+	  echo "count is" i
+	  i += 1
+	endwhile
 <
-	Note:
-	The ":" characters are not really needed here.  You only need to use
-	them when you type a command.  In a Vim script file they can be left
-	out.  We will use them here anyway to make clear these are colon
-	commands and make them stand out from Normal mode commands.
-	Note:
-	You can try out the examples by yanking the lines from the text here
-	and executing them with :@"
-
 The output of the example code is:
 
 	count is 1 ~
@@ -71,45 +74,46 @@ The output of the example code is:
 	count is 3 ~
 	count is 4 ~
 
-In the first line the ":let" command assigns a value to a variable.  The
+In the first line the `vim9script` command makes clear this is a new, |Vim9|
+script file.  That matters for how the rest of the file is used.
+
+The `var i = 1` command declares the "i" variable and initializes it.  The
 generic form is: >
 
-	:let {variable} = {expression}
+	var {name} = {expression}
 
 In this case the variable name is "i" and the expression is a simple value,
 the number one.
-   The ":while" command starts a loop.  The generic form is: >
 
-	:while {condition}
-	:  {statements}
-	:endwhile
+The `while` command starts a loop.  The generic form is: >
+
+	while {condition}
+	  {statements}
+	endwhile
 
-The statements until the matching ":endwhile" are executed for as long as the
+The statements until the matching `endwhile` are executed for as long as the
 condition is true.  The condition used here is the expression "i < 5".  This
 is true when the variable i is smaller than five.
 	Note:
 	If you happen to write a while loop that keeps on running, you can
 	interrupt it by pressing CTRL-C (CTRL-Break on MS-Windows).
 
-The ":echo" command prints its arguments.  In this case the string "count is"
+The `echo` command prints its arguments.  In this case the string "count is"
 and the value of the variable i.  Since i is one, this will print:
 
 	count is 1 ~
 
-Then there is the ":let i += 1" command.  This does the same thing as
-":let i = i + 1".  This adds one to the variable i and assigns the new value
-to the same variable.
-Note: this is how it works in legacy Vim script, which is what we discuss in
-this file.  In Vim9 script it's a bit different, see |usr_46.txt|.
+Then there is the `i += 1` command.  This does the same thing as "i = i + 1",
+it adds one to the variable i and assigns the new value to the same variable.
 
 The example was given to explain the commands, but would you really want to
 make such a loop, it can be written much more compact: >
 
-	:for i in range(1, 4)
-	:  echo "count is" i
-	:endfor
+	for i in range(1, 4)
+	  echo "count is" i
+	endfor
 
-We won't explain how |:for| and |range()| work until later.  Follow the links
+We won't explain how `for` and `range()` work until later.  Follow the links
 if you are impatient.
 
 
@@ -120,32 +124,47 @@ Numbers can be decimal, hexadecimal, octal or binary.
 A hexadecimal number starts with "0x" or "0X".  For example "0x1f" is decimal
 31.
 
-An octal number starts with "0o", "0O" or a zero and another digit.  "0o17" is
-decimal 15.  Using just a zero prefix is not supported in Vim9 script.
+An octal number starts with "0o", "0O".  "0o17" is decimal 15.
 
 A binary number starts with "0b" or "0B".  For example "0b101" is decimal 5.
 
-A decimal number is just digits.  Careful: don't put a zero before a decimal
-number, it will be interpreted as an octal number in legacy script!
+A decimal number is just digits.  Careful: In legacy script don't put a zero
+before a decimal number, it will be interpreted as an octal number!
 
-The ":echo" command always prints decimal numbers.  Example: >
+The `echo` command evaluates its argument and always prints decimal numbers.
+Example: >
 
-	:echo 0x7f 0o36
+	echo 0x7f 0o36
 <	127 30 ~
 
 A number is made negative with a minus sign.  This also works for hexadecimal,
-octal and binary numbers.  A minus sign is also used for subtraction.  Compare
-this with the previous example: >
+octal and binary numbers: >
+
+	echo -0x7f
+<	-127 ~
 
-	:echo 0x7f -0o36
-<	97 ~
+A minus sign is also used for subtraction.  This can sometimes lead to
+confusion.  If we put a minus sign before both numbers we get an error: >
 
-White space in an expression is ignored.  However, it's recommended to use it
-for separating items, to make the expression easier to read.  For example, to
-avoid the confusion with a negative number above, put a space between the
-minus sign and the following number: >
+	echo -0x7f -0o36
+<	E1004: White space required before and after '-' at "-0o36" ~
 
-	:echo 0x7f - 0o36
+Note: if you are not using a |Vim9| script to try out these commands but type
+them directly, they will be executed as legacy script.  Then the echo command
+sees the second minus sign as subtraction.  To get the error, prefix the
+command with `vim9cmd`: >
+
+	vim9cmd echo -0x7f -0o36
+<	E1004: White space required before and after '-' at "-0o36" ~
+
+White space in an expression is often required to make sure it is easy to read
+and avoid errors.  Such as thinking that the "-0o36" above makes the number
+negative, while it is actually seen as a subtraction.
+
+To actually have the minus sign be used for negation, you can put the second
+expression in parenthesis: >
+
+	echo -0x7f (-0o36)
 
 ==============================================================================
 *41.2*	Variables
@@ -160,27 +179,45 @@ cannot start with a digit.  Valid variable names are:
 	LENGTH
 
 Invalid names are "foo+bar" and "6var".
-   These variables are global.  To see a list of currently defined variables
-use this command: >
+
+Some variables are global.  To see a list of currently defined global
+variables type this command: >
 
 	:let
 
-You can use global variables everywhere.  This also means that when the
-variable "count" is used in one script file, it might also be used in another
-file.  This leads to confusion at least, and real problems at worst.  To avoid
-this, you can use a variable local to a script file by prepending "s:".  For
-example, one script contains this code: >
+You can use global variables everywhere.  However, it is easy to use the same
+name in two unrelated scripts.  Therefore variables declared in a script are
+local to that script.  For example, if you have this in "script1.vim": >
+
+	vim9script
+	var counter = 5
+	echo counter
+<	5 ~
+
+And you try to use the variable in "script2.vim": >
+
+	vim9script
+	echo counter
+<	E121: Undefined variable: counter ~
+
+Using a script-local variable means you can be sure that it is only changed in
+that script and not elsewhere.
 
-	:let s:count = 1
-	:while s:count < 5
-	:  source other.vim
-	:  let s:count += 1
-	:endwhile
+If you do want to share variables between scripts, use the "g:" prefix and
+assign the value directly, do not use `var`.  Thus in "script1.vim": >
 
-Since "s:count" is local to this script, you can be sure that sourcing the
-"other.vim" script will not change this variable.  If "other.vim" also uses an
-"s:count" variable, it will be a different copy, local to that script.  More
-about script-local variables here: |script-variable|.
+	vim9script
+	g:counter = 5
+	echo g:counter
+<	5 ~
+
+And then in "script2.vim": >
+
+	vim9script
+	echo g:counter
+<	5 ~
+
+More about script-local variables here: |script-variable|.
 
 There are more kinds of variables, see |internal-variables|.  The most often
 used ones are:
@@ -193,79 +230,99 @@ used ones are:
 
 DELETING VARIABLES
 
-Variables take up memory and show up in the output of the ":let" command.  To
-delete a variable use the ":unlet" command.  Example: >
+Variables take up memory and show up in the output of the `let` command.  To
+delete a global variable use the `unlet` command.  Example: >
 
-	:unlet s:count
+	unlet g:counter
 
-This deletes the script-local variable "s:count" to free up the memory it
-uses.  If you are not sure if the variable exists, and don't want an error
-message when it doesn't, append !: >
+This deletes the global variable "g:counter" to free up the memory it uses.
+If you are not sure if the variable exists, and don't want an error message
+when it doesn't, append !: >
 
-	:unlet! s:count
+	unlet! g:counter
 
-When a script finishes, the local variables used there will not be
-automatically freed.  The next time the script executes, it can still use the
-old value.  Example: >
+You cannot `unlet` script-local variables in |Vim9| script.  You can in legacy
+script.
 
-	:if !exists("s:call_count")
-	:  let s:call_count = 0
-	:endif
-	:let s:call_count = s:call_count + 1
-	:echo "called" s:call_count "times"
+When a script finishes, the local variables declared there will not be
+deleted.  Functions defined in the script can use them.  Example:
+>
+	vim9script
+	var counter = 0
+	def g:GetCount(): number
+	  s:counter += 1
+	  return s:counter
+	enddef
 
-The "exists()" function checks if a variable has already been defined.  Its
-argument is the name of the variable you want to check.  Not the variable
-itself!  If you would do this: >
+Every time you call the function it will return the next count: >
+	:echo g:GetCount()
+<	1 ~
+>
+	:echo g:GetCount()
+<	2 ~
 
-	:if !exists(s:call_count)
+If you are worried a script-local variable is consuming too much
+memory, set it to an empty value after you no longer need it.
 
-Then the value of s:call_count will be used as the name of the variable that
-exists() checks.  That's not what you want.
-   The exclamation mark ! negates a value.  When the value was true, it
-becomes false.  When it was false, it becomes true.  You can read it as "not".
-Thus "if !exists()" can be read as "if not exists()".
-   What Vim calls true is anything that is not zero.  Zero is false.
-	Note:
-	Vim automatically converts a string to a number when it is looking for
-	a number.  When using a string that doesn't start with a digit the
-	resulting number is zero.  Thus look out for this: >
-		:if "true"
-<	The "true" will be interpreted as a zero, thus as false!
+Note: below we'll leave out the `vim9script` line, so we can concentrate on
+the relevant commands, but you'll still need to put it at the top of your
+script file.
 
 
 STRING VARIABLES AND CONSTANTS
 
 So far only numbers were used for the variable value.  Strings can be used as
 well.  Numbers and strings are the basic types of variables that Vim supports.
-The type is dynamic, it is set each time when assigning a value to the
-variable with ":let".  More about types in |41.8|.
-   To assign a string value to a variable, you need to use a string constant.
-There are two types of these.  First the string in double quotes: >
+Example: >
 
-	:let name = "peter"
-	:echo name
+	var name = "Peter"
+	echo name
 <	peter ~
 
-If you want to include a double quote inside the string, put a backslash in
-front of it: >
+Every variable has a type.  Very often, as in this example, the type is
+defined by assigning a value.  This is called type inference.  If you do not
+want to give the variable a value yet, you need to specify the type: >
+
+	var name: string
+	var age: number
+	...
+	name = "Peter"
+	age = 42
+
+If you make a mistake and try to assign the wrong type of value you'll get an
+error: >
+	
+	age = "Peter"
+<	E1012: Type mismatch; expected number but got string ~
+
+More about types in |41.8|.
+
+To assign a string value to a variable, you need to use a string constant.
+There are two types of these.  First the string in double quotes, as we used
+already.  If you want to include a double quote inside the string, put a
+backslash in front of it: >
 
-	:let name = "\"peter\""
-	:echo name
-<	"peter" ~
+	var name = "he is \"Peter\""
+	echo name
+<	he is "Peter" ~
 
 To avoid the need for a backslash, you can use a string in single quotes: >
 
-	:let name = '"peter"'
-	:echo name
-<	"peter" ~
+	var name = 'he is "Peter"'
+	echo name
+<	he is "Peter" ~
 
 Inside a single-quote string all the characters are as they are.  Only the
 single quote itself is special: you need to use two to get one.  A backslash
 is taken literally, thus you can't use it to change the meaning of the
-character after it.
-   In double-quote strings it is possible to use special characters.  Here are
-a few useful ones:
+character after it: >
+
+	var name = 'P\e''ter'''
+	echo name
+<	P\e'ter' ~
+
+In double-quote strings it is possible to use special characters.  Here are a
+few useful ones:
 
 	\t		<Tab>
 	\n		<NL>, line break
@@ -279,15 +336,17 @@ a few useful ones:
 
 The last two are just examples.  The  "\<name>" form can be used to include
 the special key "name".
-   See |expr-quote| for the full list of special items in a string.
+
+See |expr-quote| for the full list of special items in a string.
 
 ==============================================================================
 *41.3*	Expressions
 
-Vim has a rich, yet simple way to handle expressions.  You can read the
+Vim has a fairly standard way to handle expressions.  You can read the
 definition here: |expression-syntax|.  Here we will show the most common
 items.
-   The numbers, strings and variables mentioned above are expressions by
+
+The numbers, strings and variables mentioned above are expressions by
 themselves.  Thus everywhere an expression is expected, you can use a number,
 string or variable.  Other basic items in an expression are:
 
@@ -297,17 +356,17 @@ string or variable.  Other basic items in an expression are:
 
 Examples: >
 
-	:echo "The value of 'tabstop' is" &ts
-	:echo "Your home directory is" $HOME
-	:if @a > 5
+	echo "The value of 'tabstop' is" &ts
+	echo "Your home directory is" $HOME
+	if @a == 'text'
 
-The &name form can be used to save an option value, set it to a new value,
-do something and restore the old value.  Example: >
+The &name form can also be used to set an option value, do something and
+restore the old value.  Example: >
 
-	:let save_ic = &ic
-	:set noic
-	:/The Start/,$delete
-	:let &ic = save_ic
+	var save_ic = &ic
+	set noic
+	s/The Start/The Beginning/
+	&ic = save_ic
 
 This makes sure the "The Start" pattern is used with the 'ignorecase' option
 off.  Still, it keeps the value that the user had set.  (Another way to do
@@ -327,80 +386,86 @@ mathematics on numbers:
 
 The usual precedence is used.  Example: >
 
-	:echo 10 + 5 * 2
+	echo 10 + 5 * 2
 <	20 ~
 
 Grouping is done with parentheses.  No surprises here.  Example: >
 
-	:echo (10 + 5) * 2
+	echo (10 + 5) * 2
 <	30 ~
 
 Strings can be concatenated with ".." (see |expr6|).  Example: >
 
-	:echo "foo" .. "bar"
+	echo "foo" .. "bar"
 <	foobar ~
 
-When the ":echo" command gets multiple arguments, it separates them with a
+When the "echo" command gets multiple arguments, it separates them with a
 space.  In the example the argument is a single expression, thus no space is
 inserted.
 
-Borrowed from the C language is the conditional expression:
+Borrowed from the C language is the conditional expression: >
 
 	a ? b : c
 
 If "a" evaluates to true "b" is used, otherwise "c" is used.  Example: >
 
-	:let i = 4
-	:echo i > 5 ? "i is big" : "i is small"
-<	i is small ~
+	var nr = 4
+	echo nr > 5 ? "nr is big" : "nr is small"
+<	nr is small ~
 
 The three parts of the constructs are always evaluated first, thus you could
-see it work as:
+see it works as: >
 
 	(a) ? (b) : (c)
 
 ==============================================================================
 *41.4*	Conditionals
 
-The ":if" commands executes the following statements, until the matching
-":endif", only when a condition is met.  The generic form is:
+The `if` commands executes the following statements, until the matching
+`endif`, only when a condition is met.  The generic form is:
 
-	:if {condition}
+	if {condition}
 	   {statements}
-	:endif
+	endif
 
-Only when the expression {condition} evaluates to true (non-zero) will the
-{statements} be executed.  These must still be valid commands.  If they
-contain garbage, Vim won't be able to find the ":endif".
-   You can also use ":else".  The generic form for this is:
+Only when the expression {condition} evaluates to true or one will the
+{statements} be executed.  If they are not executed they must still be valid
+commands.  If they contain garbage, Vim won't be able to find the matching
+`endif`.
 
-	:if {condition}
+You can also use `else`.  The generic form for this is:
+
+	if {condition}
 	   {statements}
-	:else
+	else
 	   {statements}
-	:endif
+	endif
 
-The second {statements} is only executed if the first one isn't.
-   Finally, there is ":elseif":
+The second {statements} block is only executed if the first one isn't.
 
-	:if {condition}
+Finally, there is `elseif`
+
+	if {condition}
 	   {statements}
-	:elseif {condition}
+	elseif {condition}
 	   {statements}
-	:endif
+	endif
 
-This works just like using ":else" and then "if", but without the need for an
-extra ":endif".
-   A useful example for your vimrc file is checking the 'term' option and
-doing something depending upon its value: >
+This works just like using `else` and then `if`, but without the need for an
+extra `endif`.
 
-	:if &term == "xterm"
-	:  " Do stuff for xterm
-	:elseif &term == "vt100"
-	:  " Do stuff for a vt100 terminal
-	:else
-	:  " Do something for other terminals
-	:endif
+A useful example for your vimrc file is checking the 'term' option and doing
+something depending upon its value: >
+
+	if &term == "xterm"
+	  # Do stuff for xterm
+	elseif &term == "vt100"
+	  # Do stuff for a vt100 terminal
+	else
+	  # Do something for other terminals
+	endif
+
+This uses "#" to start a comment, more about that later.
 
 
 LOGIC OPERATIONS
@@ -415,168 +480,186 @@ ones:
 	a <  b		less than
 	a <= b		less than or equal to
 
-The result is one if the condition is met and zero otherwise.  An example: >
+The result is true if the condition is met and false otherwise.  An example: >
 
-	:if v:version >= 700
-	:  echo "congratulations"
-	:else
-	:  echo "you are using an old version, upgrade!"
-	:endif
+	if v:version >= 700
+	  echo "congratulations"
+	else
+	  echo "you are using an old version, upgrade!"
+	endif
 
 Here "v:version" is a variable defined by Vim, which has the value of the Vim
-version.  600 is for version 6.0.  Version 6.1 has the value 601.  This is
+version.  600 is for version 6.0, version 6.1 has the value 601.  This is
 very useful to write a script that works with multiple versions of Vim.
 |v:version|
 
 The logic operators work both for numbers and strings.  When comparing two
 strings, the mathematical difference is used.  This compares byte values,
 which may not be right for some languages.
-   When comparing a string with a number, the string is first converted to a
-number.  This is a bit tricky, because when a string doesn't look like a
-number, the number zero is used.  Example: >
-
-	:if 0 == "one"
-	:  echo "yes"
-	:endif
 
-This will echo "yes", because "one" doesn't look like a number, thus it is
-converted to the number zero.
+If you try to compare a string with a number you will get an error.
 
-For strings there are two more items:
+For strings there are two more useful items:
 
-	a =~ b		matches with
-	a !~ b		does not match with
+	str =~ pat		matches with
+	str !~ pat		does not match with
 
-The left item "a" is used as a string.  The right item "b" is used as a
+The left item "str" is used as a string.  The right item "pat" is used as a
 pattern, like what's used for searching.  Example: >
 
-	:if str =~ " "
-	:  echo "str contains a space"
-	:endif
-	:if str !~ '\.$'
-	:  echo "str does not end in a full stop"
-	:endif
+	if str =~ " "
+	  echo "str contains a space"
+	endif
+	if str !~ '\.$'
+	  echo "str does not end in a full stop"
+	endif
 
 Notice the use of a single-quote string for the pattern.  This is useful,
 because backslashes would need to be doubled in a double-quote string and
 patterns tend to contain many backslashes.
 
-The 'ignorecase' option is used when comparing strings.  When you don't want
-that, append "#" to match case and "?" to ignore case.  Thus "==?" compares
-two strings to be equal while ignoring case.  And "!~#" checks if a pattern
-doesn't match, also checking the case of letters.  For the full table see
-|expr-==|.
+The match is not anchored, if you want to match the whole string start with
+"^" and end with "$".
+
+The 'ignorecase' option is not used when comparing strings.  When you do want
+to ignore case append "?".  Thus "==?" compares two strings to be equal while
+ignoring case.  For the full table see |expr-==|.
 
 
 MORE LOOPING
 
-The ":while" command was already mentioned.  Two more statements can be used
-in between the ":while" and the ":endwhile":
+The `while` command was already mentioned.  Two more statements can be used in
+between the `while` and the `endwhile`:
 
-	:continue		Jump back to the start of the while loop; the
+	continue		Jump back to the start of the while loop; the
 				loop continues.
-	:break			Jump forward to the ":endwhile"; the loop is
+	break			Jump forward to the `endwhile`; the loop is
 				discontinued.
 
 Example: >
 
-	:while counter < 40
-	:  call do_something()
-	:  if skip_flag
-	:    continue
-	:  endif
-	:  if finished_flag
-	:    break
-	:  endif
-	:  sleep 50m
-	:endwhile
+	while counter < 40
+	  do_something()
+	  if skip_flag
+	    continue
+	  endif
+	  if finished_flag
+	    break
+	  endif
+	  sleep 50m
+	  --counter
+	endwhile
 
-The ":sleep" command makes Vim take a nap.  The "50m" specifies fifty
-milliseconds.  Another example is ":sleep 4", which sleeps for four seconds.
+The `sleep` command makes Vim take a nap.  The "50m" specifies fifty
+milliseconds.  Another example is `sleep 4`, which sleeps for four seconds.
 
-Even more looping can be done with the ":for" command, see below in |41.8|.
+Even more looping can be done with the `for` command, see below in |41.8|.
 
 ==============================================================================
 *41.5*	Executing an expression
 
 So far the commands in the script were executed by Vim directly.  The
-":execute" command allows executing the result of an expression.  This is a
+`execute` command allows executing the result of an expression.  This is a
 very powerful way to build commands and execute them.
-   An example is to jump to a tag, which is contained in a variable: >
 
-	:execute "tag " .. tag_name
+An example is to jump to a tag, which is contained in a variable: >
+
+	execute "tag " .. tag_name
 
 The ".." is used to concatenate the string "tag " with the value of variable
 "tag_name".  Suppose "tag_name" has the value "get_cmd", then the command that
 will be executed is: >
 
-	:tag get_cmd
+	tag get_cmd
 
-The ":execute" command can only execute colon commands.  The ":normal" command
+The `execute` command can only execute Ex commands.  The `normal` command
 executes Normal mode commands.  However, its argument is not an expression but
 the literal command characters.  Example: >
 
-	:normal gg=G
+	normal gg=G
+
+This jumps to the first line with "gg" and formats all lines with the "="
+operator and the "G" movement.
 
-This jumps to the first line and formats all lines with the "=" operator.
-   To make ":normal" work with an expression, combine ":execute" with it.
+To make `normal` work with an expression, combine `execute` with it.
 Example: >
 
-	:execute "normal " .. normal_commands
+	execute "normal " .. count .. "j"
+
+This will move the cursor "count" lines down.
 
-The variable "normal_commands" must contain the Normal mode commands.
-   Make sure that the argument for ":normal" is a complete command.  Otherwise
+Make sure that the argument for `normal` is a complete command.  Otherwise
 Vim will run into the end of the argument and abort the command.  For example,
-if you start Insert mode, you must leave Insert mode as well.  This works: >
+if you start the delete operator, you must give the movement command also.
+This works: >
+	
+	normal d$
 
-	:execute "normal Inew text \<Esc>"
+This does nothing: >
 
-This inserts "new text " in the current line.  Notice the use of the special
-key "\<Esc>".  This avoids having to enter a real <Esc> character in your
-script.
+	normal d
+
+If you start Insert mode and do not end it with Esc, it will end anyway.  This
+works to insert "new text": >
+
+	execute "normal inew text"
+
+If you want to do something after inserting text you do need to end Insert
+mode: >
+
+	execute "normal inew text\<Esc>b"
+
+This inserts "new text" and puts the cursor on the first letter of "text".
+Notice the use of the special key "\<Esc>".  This avoids having to enter a
+real <Esc> character in your script.  That is where `execute` with a
+double-quote string comes in handy.
 
 If you don't want to execute a string but evaluate it to get its expression
 value, you can use the eval() function: >
 
-	:let optname = "path"
-	:let optval = eval('&' .. optname)
+	var optname = "path"
+	var optvalue = eval('&' .. optname)
 
 A "&" character is prepended to "path", thus the argument to eval() is
 "&path".  The result will then be the value of the 'path' option.
-   The same thing can be done with: >
-	:exe 'let optval = &' .. optname
 
 ==============================================================================
 *41.6*	Using functions
 
 Vim defines many functions and provides a large amount of functionality that
 way.  A few examples will be given in this section.  You can find the whole
-list here: |functions|.
+list below: |function-list|.
 
-A function is called with the ":call" command.  The parameters are passed in
+A function is called with the `call` command.  The parameters are passed in
 between parentheses separated by commas.  Example: >
 
-	:call search("Date: ", "W")
+	call search("Date: ", "W")
 
 This calls the search() function, with arguments "Date: " and "W".  The
 search() function uses its first argument as a search pattern and the second
 one as flags.  The "W" flag means the search doesn't wrap around the end of
 the file.
 
+Using `call` is optional in |Vim9| script, this works the same way: >
+
+	search("Date: ", "W")
+
 A function can be called in an expression.  Example: >
 
-	:let line = getline(".")
-	:let repl = substitute(line, '\a', "*", "g")
-	:call setline(".", repl)
+	var line = getline(".")
+	var repl = substitute(line, '\a', "*", "g")
+	setline(".", repl)
 
 The getline() function obtains a line from the current buffer.  Its argument
 is a specification of the line number.  In this case "." is used, which means
 the line where the cursor is.
-   The substitute() function does something similar to the ":substitute"
-command.  The first argument is the string on which to perform the
-substitution.  The second argument is the pattern, the third the replacement
-string.  Finally, the last arguments are the flags.
-   The setline() function sets the line, specified by the first argument, to a
+
+The substitute() function does something similar to the `substitute` command.
+The first argument is the string on which to perform the substitution.  The
+second argument is the pattern, the third the replacement string.  Finally,
+the last arguments are the flags.
+
+The setline() function sets the line, specified by the first argument, to a
 new string, the second argument.  In this example the line under the cursor is
 replaced with the result of the substitute().  Thus the effect of the three
 statements is equal to: >
@@ -590,8 +673,8 @@ after the substitute() call.
 FUNCTIONS						*function-list*
 
 There are many functions.  We will mention them here, grouped by what they are
-used for.  You can find an alphabetical list here: |functions|.  Use CTRL-] on
-the function name to jump to detailed help on it.
+used for.  You can find an alphabetical list here: |builtin-function-list|.
+Use CTRL-] on the function name to jump to detailed help on it.
 
 String manipulation:					*string-functions*
 	nr2char()		get a character by its number value
@@ -1234,9 +1317,9 @@ Various:					*various-functions*
 Vim enables you to define your own functions.  The basic function declaration
 begins as follows: >
 
-	:function {name}({var1}, {var2}, ...)
-	:  {body}
-	:endfunction
+	def {name}({var1}, {var2}, ...): return-type
+	  {body}
+	enddef
 <
 	Note:
 	Function names must begin with a capital letter.
@@ -1244,115 +1327,107 @@ begins as follows: >
 Let's define a short function to return the smaller of two numbers.  It starts
 with this line: >
 
-	:function Min(num1, num2)
+	def Min(num1: number, num2: number): number
+
+This tells Vim that the function is named "Min", it takes two arguments that
+are numbers: "num1" and "num2" and returns a number.
 
-This tells Vim that the function is named "Min" and it takes two arguments:
-"num1" and "num2".
-   The first thing you need to do is to check to see which number is smaller:
+The first thing you need to do is to check to see which number is smaller:
    >
-	:  if a:num1 < a:num2
+	if num1 < num2
 
-The special prefix "a:" tells Vim that the variable is a function argument.
 Let's assign the variable "smaller" the value of the smallest number: >
 
-	:  if a:num1 < a:num2
-	:    let smaller = a:num1
-	:  else
-	:    let smaller = a:num2
-	:  endif
+	var smaller: number
+	if num1 < num2
+	  smaller = num1
+	else
+	  smaller = num2
+	endif
 
 The variable "smaller" is a local variable.  Variables used inside a function
-are local unless prefixed by something like "g:", "a:", or "s:".
+are local unless prefixed by something like "g:", "w:", or "s:".
 
 	Note:
 	To access a global variable from inside a function you must prepend
 	"g:" to it.  Thus "g:today" inside a function is used for the global
 	variable "today", and "today" is another variable, local to the
-	function.
+	function or the script.
 
-You now use the ":return" statement to return the smallest number to the user.
+You now use the `return` statement to return the smallest number to the user.
 Finally, you end the function: >
 
-	:  return smaller
-	:endfunction
+	  return smaller
+	enddef
 
 The complete function definition is as follows: >
 
-	:function Min(num1, num2)
-	:  if a:num1 < a:num2
-	:    let smaller = a:num1
-	:  else
-	:    let smaller = a:num2
-	:  endif
-	:  return smaller
-	:endfunction
+	def Min(num1: number, num2: number): number
+	  var smaller: number
+	  if num1 < num2
+	    smaller = num1
+	  else
+	    smaller = num2
+	  endif
+	  return smaller
+	enddef
+
+Obviously this is a verbose example.  You can make it shorter by using two
+return commands: >
+
+	def Min(num1: number, num2: number): number
+	  if num1 < num2
+	    return num1
+	  endif
+	  return num2
+	enddef
 
-For people who like short functions, this does the same thing: >
+And if you remember the conditional expression, you need only one line: >
 
-	:function Min(num1, num2)
-	:  if a:num1 < a:num2
-	:    return a:num1
-	:  endif
-	:  return a:num2
-	:endfunction
+	def Min(num1: number, num2: number): number
+	  return num1 < num2 ? num1 : num2
+	enddef
 
 A user defined function is called in exactly the same way as a built-in
 function.  Only the name is different.  The Min function can be used like
 this: >
 
-	:echo Min(5, 8)
+	echo Min(5, 8)
 
-Only now will the function be executed and the lines be interpreted by Vim.
+Only now will the function be executed and the lines be parsed by Vim.
 If there are mistakes, like using an undefined variable or function, you will
 now get an error message.  When defining the function these errors are not
-detected.
+detected.  To get the errors sooner you can tell Vim to compile all the
+functions in the script: >
 
-When a function reaches ":endfunction" or ":return" is used without an
-argument, the function returns zero.
+	defcompile
 
-To redefine a function that already exists, use the ! for the ":function"
-command: >
-
-	:function!  Min(num1, num2, num3)
+For a function that does not return anything leave out the return type: >
 
+	def SayIt(text: string)
+	  echo text
+	enddef
 
-USING A RANGE
-
-The ":call" command can be given a line range.  This can have one of two
-meanings.  When a function has been defined with the "range" keyword, it will
-take care of the line range itself.
-  The function will be passed the variables "a:firstline" and "a:lastline".
-These will have the line numbers from the range the function was called with.
-Example: >
+It is also possible to define a legacy function with `function` and
+`endfunction`.  These do not have types and are not compiled.  They execute
+much slower.
 
-	:function Count_words() range
-	:  let lnum = a:firstline
-	:  let n = 0
-	:  while lnum <= a:lastline
-	:    let n = n + len(split(getline(lnum)))
-	:    let lnum = lnum + 1
-	:  endwhile
-	:  echo "found " .. n .. " words"
-	:endfunction
 
-You can call this function with: >
-
-	:10,30call Count_words()
+USING A RANGE
 
-It will be executed once and echo the number of words.
-   The other way to use a line range is by defining a function without the
-"range" keyword.  The function will be called once for every line in the
-range, with the cursor in that line.  Example: >
+A line range can be used with a function call.  The function will be called
+once for every line in the range, with the cursor in that line.  Example: >
 
-	:function  Number()
-	:  echo "line " .. line(".") .. " contains: " .. getline(".")
-	:endfunction
+	def Number()
+	  echo "line " .. line(".") .. " contains: " .. getline(".")
+	enddef
 
 If you call this function with: >
 
 	:10,15call Number()
 
-The function will be called six times.
+The function will be called six times, starting on line 10 and ending on line
+15.