Runtime file updates
diff --git a/runtime/doc/vim9.txt b/runtime/doc/vim9.txt
index 21bc542..b14ff0b 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 Jun 22
+*vim9.txt* For Vim version 8.2. Last change: 2020 Jun 24
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -378,6 +378,49 @@
In Vim9 script one can use "true" for v:true and "false" for v:false.
+What to watch out for ~
+ *vim9-gotchas*
+Vim9 was designed to be closer to often used programming languages, but at the
+same time tries to support the legacy Vim commands. Some compromises had to
+be made. Here is a summary of what might be unexpected.
+
+Ex command ranges need to be prefixed with a colon. >
+ -> " legacy Vim: shifts the previous line to the right
+ ->func() " Vim9: method call
+ :-> " Vim9: shifts the previous line to the right
+
+ %s/a/b " legacy Vim: substitute on all lines
+ x = alongname
+ % another " Vim9: line continuation without a backslash
+ :%s/a/b " Vim9: substitute on all lines
+
+Functions defined with `:def` compile the whole function. Legacy functions
+can bail out, and the following lines are not parsed: >
+ func Maybe()
+ if !has('feature')
+ return
+ endif
+ use-feature
+ endfunc
+Vim9 functions are compiled as a whole: >
+ def Maybe()
+ if !has('feature')
+ return
+ endif
+ use-feature " May give compilation error
+ enddef
+For a workaround, split it in two functions: >
+ func Maybe()
+ if has('feature')
+ call MaybyInner()
+ endif
+ endfunc
+ if has('feature')
+ def MaybeInner()
+ use-feature
+ enddef
+ endif
+
==============================================================================
3. New style functions *fast-functions*