More doc updates

[substrate.git] / documentation / zil.md

diff --git a/documentation/zil.md b/documentation/zil.md
index 4d30b87d24c9b04d1a1b512a501c68d20b42e1fe..6b1e88551db1407147b032b99073f1176b001c37 100644 (file)
--- a/documentation/zil.md
+++ b/documentation/zil.md
@@ -23,17 +23,34 @@ License along with this document. If not see
 A "definition" is used to describe a room, object, routine, etc. in or 
 used by the game. Each definition consists of a number of properties, 
 flags, and/or instructions. A program written in ZIL can be thought of 
-as consisting of one or more of these definitions. Definitions, 
-properties, flags, and instructions include brackets which must be 
-correctly paired and nested.
+as consisting of two or more of these definitions. At a minimum, a 
+program must define which version it is to be compiled for and contain 
+at least one routine named GO from which execution begins. 
+Definitions, properties, flags, and instructions include brackets 
+which must be correctly paired and nested.
+
+## Z-machine versions
+Infocom made 6 versions of the Z-machine. The community made 2 more, 
+for a total of 8, mostly to support larger story files. To define 
+which version of the Z-machine a program is to be compiled for, it 
+must contain a VERSION definition at the top level, outside any other 
+definitions, in the following format, using this BNF-style syntax:
+
+    <version-definition> ::= "<" "VERSION" <version-number> ">"
+
+    <version-number> ::= "ZIP" | "EZIP" | "XZIP" | "YZIP" | "1" | "2"
+    | "3" | "4" | "5" | "6" | "7" | "8"
+
+ZIP is equivalent to version 3, EZIP to version 4, XZIP to version 5, 
+and YZIP to version 6.
 
 ## Comments
 Comments are ignored by the compiler. A comment begins with a 
 semicolon (;) and continues until the end of the line. A multiline 
-comment also begins with a semicolon but is enclosed in double 
-quotes. However, single line comments may also be enclosed in double 
-quotes. While comments may be placed anywhere in a source code file, a 
-comment may not be placed inside an atom.
+comment also begins with a semicolon but is enclosed in double quotes. 
+However, single line comments may also be enclosed in double quotes. 
+While comments may be placed anywhere in a source code file, a comment 
+may not be placed inside an atom.
 
 ## Parser
 The purpose of the parser is to receive and process the player's