more docs. restructure project. add antlr stuff.

docs/source/building.rst

@@ -27,6 +27,10 @@ The compiler is invoked with the command:
 
 	``$ @todo``
 
+It produces an assembly source code file which in turn will (automatically) be passed to
+the `64tass <https://sourceforge.net/projects/tass64/>`_ cross assembler tool
+that assembles it into the final program.
+
 
 Module source code files
 ------------------------

docs/source/index.rst

@@ -38,7 +38,7 @@ Design principles
 - Provide a convenient edit/compile/run cycle by being able to directly launch
   the compiled program in an emulator and provide debugging information to the emulator.
 - The compiler outputs a regular 6502 assembly code file, it doesn't assemble this itself.
-  A third party cross-assembler tool is used to do this final step.
+  The '64tass' third party cross-assembler tool is used to do this final step.
 - Goto is considered harmful, but not here; arbitrary control flow jumps are allowed.
 - No complicated error handling or overflow checks that would slow things down.
 
@@ -46,8 +46,9 @@ Design principles
 Required tools
 --------------
 
+`64tass <https://sourceforge.net/projects/tass64/>`_ - cross assembler
+
 @TODO
-- 64tass cross-assembler?
 - java?
 - kotlin?
 

docs/source/programming.rst

@@ -166,7 +166,7 @@ Integers
 Integers are 8 or 16 bit numbers and can be written in normal decimal notation,
 in hexadecimal and in binary notation.
 
-@todo right now only unsinged integers are supported (>=0)
+@todo right now only unsinged integers are supported (0-255 for byte types, 0-65535 for word types)
 
 
 Strings
@@ -217,12 +217,11 @@ The resulting value is simply a 16 bit word. Example::
 	AX = #somevar
 
 
-
 **Indirect addressing:**
-@todo
+@todo ???
 
 **Indirect addressing in jumps:**
-@todo
+@todo ???
 For an indirect ``goto`` statement, the compiler will issue the 6502 CPU's special instruction
 (``jmp`` indirect).  A subroutine call (``jsr`` indirect) is emitted
 using a couple of instructions.
@@ -280,22 +279,24 @@ Expressions
 -----------
 
 In most places where a number or other value is expected, you can use just the number, or a full constant expression.
-The expression is parsed and evaluated by Python itself at compile time, and the (constant) resulting value is used in its place.
-Ofcourse the special il65 syntax for hexadecimal numbers (``$xxxx``), binary numbers (``%bbbbbbbb``),
-and the address-of (``#xxxx``) is supported. Other than that it must be valid Python syntax.
+The expression is parsed and evaluated by the compiler itself at compile time, and the (constant) resulting value is used in its place.
 Expressions can contain function calls to the math library (sin, cos, etc) and you can also use
 all builtin functions (max, avg, min, sum etc). They can also reference idendifiers defined elsewhere in your code,
 if this makes sense.
 
 
-Arithmetic
-^^^^^^^^^^
-@todo
+Arithmetic and Logical expressions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Arithmetic expressions are expressions that calculate a numeric result (integer or floating point).
+Many common arithmetic operators can be used and follow the regular precedence rules.
 
+Logical expressions are expressions that calculate a boolean result, true or false
+(which in IL65 will effectively be a 1 or 0 integer value).
 
-Logical expressions
-^^^^^^^^^^^^^^^^^^^
-@todo
+You can use parentheses to group parts of an expresion to change the precedence.
+Usually the normal precedence rules apply (``*`` goes before ``+`` etc.) but subexpressions
+within parentheses will be evaluated first. So ``(4 + 8) * 2`` is 24 and not 20,
+and ``(true or false) and false`` is false instead of true.
 
 
 Subroutines

docs/source/syntaxreference.rst

@@ -227,10 +227,10 @@ type identifier  type                     storage size       example var declara
 ``word``         unsigned word            2 bytes = 16 bits  ``word myvar = $8fee``
 ``float``        floating-point           5 bytes = 40 bits  ``float myvar = 1.2345``
                                                              stored in 5-byte cbm MFLPT format
-``byte[x]``      byte array               x bytes            ``byte[4] myvar = [1, 2, 3, 4]``
-``word[x]``      word array               2*x bytes          ``word[4] myvar = [1, 2, 3, 4]``
-``byte[x,y]``    byte matrix              x*y bytes          ``byte[40,25] myvar = @todo``
-                                                             Note: word-matrix not supported
+``byte[x]``      unsigned byte array      x bytes            ``byte[4] myvar = [1, 2, 3, 4]``
+``word[x]``      unsigned word array      2*x bytes          ``word[4] myvar = [1, 2, 3, 4]``
+``byte[x,y]``    unsigned byte matrix     x*y bytes          ``byte[40,25] myvar = @todo``
+                                                             word-matrix not supported
 ``str``          string (petscii)         varies             ``str myvar = "hello."``
                                                              implicitly terminated by a 0-byte
 ``str_p``        pascal-string (petscii)  varies             ``str_p myvar = "hello."``
@@ -243,6 +243,7 @@ type identifier  type                     storage size       example var declara
 
 
 **@todo pointers/addresses?  (as opposed to normal WORDs)**
+
 **@todo signed integers (byte and word)?**
 
 
@@ -340,9 +341,9 @@ When put after a sequence type (array, string or matrix) it means to point to th
 
 .. data::  ( ... )    (precedence grouping in expressions, or subroutine parameter list)
 
-Parentheses are used to chose the evaluation precedence in expressions.
-Usually the normal precedence rules apply (``*`` goes before ``+`` etc.) but with
-parentheses you can change this: ``4 + 8 * 2`` is 20, but ``(4 + 8) * 2`` is 24.
+Parentheses are used to group parts of an expression to change the order of evaluation.
+(the subexpression inside the parentheses will be evaluated first):
+``(4 + 8) * 2`` is 24 instead of 20.
 
 Parentheses are also used in a subroutine call, they follow the name of the subroutine and contain
 the list of arguments to pass to the subroutine:   ``big_function(1, 99)``
@@ -397,8 +398,6 @@ and not specifying a code block::
 
         comma separated list of "<parametername>:<register>" pairs specifying the input parameters.
         You can omit the parameter names as long as the arguments "line up".
-        (actually, the Python parameter passing rules apply, so you can also mix positional
-        and keyword arguments, as long as the keyword arguments come last)
 
 .. data:: proc_results
 

docs/source/todo.rst

@@ -111,11 +111,10 @@ For::
 
 ### Macros
 
-@todo macros are meta-code (written in Python syntax) that actually runs in a preprecessing step
-during the compilation, and produces output value that is then replaced on that point in the input source.
-Allows us to create pre calculated sine tables and such. Something like::
+@todo macros are meta-code that is executed by the compiler, in a preprecessing step
+during the compilation, and can produce output that is then replaced on that point in the input source.
+Allows us to create pre calculated sine tables and such.
 
-        var .array sinetable ``[sin(x) * 10 for x in range(100)]``
 
 
 Memory Block Operations