X-Git-Url: https://jxself.org/git/?p=substrate.git;a=blobdiff_plain;f=documentation%2Fzil.md;h=6b1e88551db1407147b032b99073f1176b001c37;hp=c2caf8f94844b82e7fc35b106ecad0b825c1ba20;hb=HEAD;hpb=40a14659f5cd8f005592280afa2249dc249eda6d

diff --git a/documentation/zil.md b/documentation/zil.md
index c2caf8f..6b1e885 100644
--- a/documentation/zil.md
+++ b/documentation/zil.md
@@ -1,6 +1,9 @@
-# Zork Implentation Language
-This document covers the Zork Implementation Language, as originally 
-developed and used by Infocom for their games.
+# Introduction
+This document covers the Zork Implementation Language, or ZIL for 
+short, as originally developed and used by Infocom for their games.
+
+ZIL is a subset of the MIT Design Language, or MDL for short, and 
+pronounced as "Muddle". MDL is itself based on classic LISP.
 
 ## Format
 This document is written using CommonMark, a markup language. More 
@@ -17,17 +20,63 @@ License along with this document. If not see
 <https://gnu.org/licenses/>.
 
 ## Definitions
-
 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.
+
+## Parser
+The purpose of the parser is to receive and process the player's 
+input. Its primary responsibility is to determine the player's 
+intended action along with any objects that may be referred to.
+
+The player's action is referred to internally as the PRSA (think "A" 
+for action like "EAT", the direct object as PRSO (think "O" for 
+"object") and the indirect object as PRSI (think "I" for indirect.)
+
+For an example, the command "KILL TROLL WITH SWORD" would set the PRSA 
+to KILL and the PRSO to TROLL and PRSI to SWORD. It is important to 
+note that not all instructions from the player will necessarily have 
+all three things, but a PRSA is required in all cases and you can't 
+have a PRSI without also having a PRSO. In cases where there is no 
+PRSI or PRSO, they are set to false.
+
+Note that the PRSA isn't simply the word that the player entered. The 
+PRSA from a given sentence is determined by the syntax definitions in 
+the game. An example being: The player might type "CONSUME APPLE" but 
+in the game's syntax definitions, the PRSA associated with "consume" 
+might be EAT.
 
 ## Syntax Definitions
 Syntax definitions are used by the parser to determine valid sentence 
-structures.
+structures. Each entry must correspond to this format:
 
 A simple example might be:
 
@@ -36,3 +85,5 @@ A simple example might be:
 Using this example, should the parser match the player's input to 
 "xyzzy" then the PRSA is set to magic. PRSI and PRSO would be set to 
 false.
+
+## Syntax Tokens