doc: add a document describing potential non-obvious syntax errors

the errors documented here include cases where the error is detected
far away from where the actual malformed syntax is in the source file,
so any error message reported by the compiler needs to include enough
information to help the user find and resolve the error.

doc/error-cases.txt

@@ -0,0 +1,29 @@
+SYNTAX ERROR CASES TO HANDLE
+============================
+
+   This document describes a range of non-obvious syntax error conditions that
+   need to be clearly conveyed in error messages.
+
+
+   1 Unterminated expression preceding a for-loop
+   ----------------------------------------------
+
+     1|  var x = "Hello, world!"
+     2|
+     3|  for i in 0 to:100 step:2 do
+     4|      cout put:'Count is {i}'
+     5|  end
+
+   The statement separator is missing from the end of line 1. However, no
+   error is detected when the for keyword is encountered due to support for
+   inline for-loops.
+
+   An error is only reported when the do keyword is encountered, as inline
+   for-loop do not use this keyword.
+
+   The compiler should alert the user that they may have forgotten a statement
+   separator at the end of the preceding expression.
+
+
+
+vim: shiftwidth=3 expandtab