--- a/runtime/doc/vim9.txt
+++ b/runtime/doc/vim9.txt
@@ -1,4 +1,4 @@
-*vim9.txt*	For Vim version 8.2.  Last change: 2021 Dec 27
+*vim9.txt*	For Vim version 8.2.  Last change: 2022 Jan 07
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -120,7 +120,7 @@ is the same as in shell scripts and Pyth
 
 In Vi # is a command to list text with numbers.  In Vim9 script you can use
 `:number` for that. >
-	101 number
+	:101 number
 
 To improve readability there must be a space between a command and the #
 that starts a comment: >
@@ -1358,8 +1358,14 @@ 5. Namespace, Import and Export
 					*vim9script* *vim9-export* *vim9-import*
 
 A Vim9 script can be written to be imported.  This means that everything in
-the script is local, unless exported.  Those exported items, and only those
-items, can then be imported in another script.
+the script is local, except for items that are exported.  Those exported
+items, and only those items, can then be imported in another script.
+
+This mechanism exists for writing a script that can be sourced (imported) by
+other scripts, while making sure these other scripts only have access to what
+you want them to.  This also avoids using the global namespace, which has a
+risc of name collisions.  For example when you have two plugins with similar
+functionality.
 
 You can cheat by using the global namespace explicitly.  We will assume here
 that you don't do that.
@@ -1438,21 +1444,23 @@ The exported items can be imported in an
 This makes each item available as "myscript.item".
 
 In case the name is long or ambiguous, another name can be specified: >
-	import "thatscript.vim" as That
+	import "thatscript.vim" as that
 
-Then you can use "That.EXPORTED_CONST", "That.someValue", etc.  You are free
-to choose the name "That".  Use something that will be recognized as referring
-to the imported script.  Avoid command names, because the name will shadow
-them.
+Then you can use "that.EXPORTED_CONST", "that.someValue", etc.  You are free
+to choose the name "that".  Use something that will be recognized as referring
+to the imported script.  Avoid command names and builtin function names,
+because the name will shadow them.
 
-In case the dot in the name is unwanted, a local reference can be made: >
-	var ThatFunc = That.LongFuncName
+In case the dot in the name is undesired, a local reference can be made for a
+function: >
+	var LongFunc = that.LongFuncName
 
 This also works for constants: >
-	cost MAXLEN = That.MAX_LEN_OF_NAME
+	const MAXLEN = that.MAX_LEN_OF_NAME
 
-This does not work for variables, you could use a setter function and make a
-local reference for it.
+This does not work for variables, since the value would be copied once and
+when changing the variable the copy will change, not the original variable.
+You will need to use the full name, with the dot.
 
 `:import` can also be used in legacy Vim script.  The imported items still
 become script-local, even when the "s:" prefix is not given.
@@ -1471,12 +1479,21 @@ The script name after `import` can be:
   longer and unique, to avoid loading the wrong file.
   Note that "after/import" is not used.
 
+If the name does not end in ".vim" then the use of "as name" is required.
+
 Once a vim9 script file has been imported, the result is cached and used the
 next time the same script is imported.  It will not be read again.
 
 It is not allowed to import the same script twice, also when using two
 different "as" names.
-							*:import-cycle*
+
+When using the imported name the dot and the item name must be in the same
+line, there can be no line break: >
+	echo that.
+		name   # Error!
+	echo that
+		.name  # Error!
+<							*:import-cycle*
 The `import` commands are executed when encountered.  If that script (directly
 or indirectly) imports the current script, then items defined after the
 `import` won't be processed yet.  Therefore cyclic imports can exist, but may