diff --git a/docs/source/building.rst b/docs/source/building.rst
new file mode 100644
index 000000000..058734881
--- /dev/null
+++ b/docs/source/building.rst
@@ -0,0 +1,73 @@
+==============================
+Writing and building a program
+==============================
+
+What is a "Program" anyway?
+---------------------------
+
+A "complete runnable program" is a compiled, assembled, and linked together single unit.
+It contains all of the program's code and data and has a certain file format that
+allows it to be loaded directly on the target system.   IL65 currently has no built-in
+support for programs that exceed 64 Kb of memory, nor for multi-part loaders.
+
+For the Commodore-64, most programs will have a tiny BASIC launcher that does a SYS into the generated machine code.
+This way the user can load it as any other program and simply RUN it to start. (This is a regular ".prg" program).
+Il65 can create those, but it is also possible to output plain binary programs
+that can be loaded into memory anywhere.
+
+
+Compiling program code
+----------------------
+
+Compilation of program code is done by telling the IL65 compiler to compile a main source code module file.
+Other modules that this code needs will be loaded and processed via imports from within that file.
+The compiler will link everything together into one output program at the end.
+
+The compiler is invoked with the command:
+
+	``$ @todo``
+
+
+Module source code files
+------------------------
+
+A module source file is a text file with the ``.ill`` suffix, containing the program's source code.
+It consists of compilation options and other directives, imports of other modules,
+and source code for one or more code blocks.
+
+IL65 has a couple of *LIBRARY* modules that are defined in special internal files provided by the compiler:
+``c64lib``, ``il65lib``, ``mathlib``.
+You should not overwrite these or reuse their names.
+
+
+.. _debugging:
+
+Debugging (with Vice)
+---------------------
+
+There's support for using the monitor and debugging capabilities of the rather excellent
+`Vice emulator <http://vice-emu.sourceforge.net/>`_.
+
+The ``%breakpoint`` directive (see :ref:`directives`) in the source code instructs the compiler to put
+a *breakpoint* at that position. Some systems use a BRK instruction for this, but
+this will usually halt the machine altogether instead of just suspending execution.
+IL65 issues a NOP instruction instead and creates a 'virtual' breakpoint at this position.
+All breakpoints are then written to a file called "programname.vice-mon-list",
+which is meant to be used by the Vice emulator.
+It contains a series of commands for Vice's monitor, including source labels and the breakpoint settings.
+If you use the vice autostart feature of the compiler, it will be processed by Vice automatically and immediately.
+If you launch Vice manually, you'll have to use a command line option to load this file:
+
+	``$ x64 -moncommands programname.vice-mon-list``
+
+Vice will then use the label names in memory disassembly, and will activate the breakpoints as well.
+If your running program hits one of the breakpoints, Vice will halt execution and drop you into the monitor.
+
+
+Troubleshooting
+---------------
+
+Getting an assembler error about undefined symbols such as ``not defined 'c64flt'``?
+This happens when your program uses floating point values, and you forgot to import the ``c64lib``.
+If you use floating points, the program will need routines from that library.
+Fix it by adding an ``%import c64lib``.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 69f358ee4..643bbf1a7 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -40,6 +40,7 @@ Design principles
 - 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.
 - 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.
 
 
 Required tools
@@ -56,8 +57,8 @@ Required tools
     :caption: Contents of this manual:
 
     targetsystem.rst
+    building.rst
     programming.rst
-    progstructure.rst
     syntaxreference.rst
     todo.rst
 
diff --git a/docs/source/programming.rst b/docs/source/programming.rst
index 058734881..f1cfc81ed 100644
--- a/docs/source/programming.rst
+++ b/docs/source/programming.rst
@@ -1,73 +1,335 @@
-==============================
-Writing and building a program
-==============================
+.. _programstructure:
 
-What is a "Program" anyway?
----------------------------
+===================
+Programming in IL65
+===================
 
-A "complete runnable program" is a compiled, assembled, and linked together single unit.
-It contains all of the program's code and data and has a certain file format that
-allows it to be loaded directly on the target system.   IL65 currently has no built-in
-support for programs that exceed 64 Kb of memory, nor for multi-part loaders.
-
-For the Commodore-64, most programs will have a tiny BASIC launcher that does a SYS into the generated machine code.
-This way the user can load it as any other program and simply RUN it to start. (This is a regular ".prg" program).
-Il65 can create those, but it is also possible to output plain binary programs
-that can be loaded into memory anywhere.
+This chapter describes a high level overview of the elements that make up a program.
+Details about the syntax can be found in the :ref:`syntaxreference` chapter.
 
 
-Compiling program code
-----------------------
-
-Compilation of program code is done by telling the IL65 compiler to compile a main source code module file.
-Other modules that this code needs will be loaded and processed via imports from within that file.
-The compiler will link everything together into one output program at the end.
-
-The compiler is invoked with the command:
-
-	``$ @todo``
-
-
-Module source code files
-------------------------
-
-A module source file is a text file with the ``.ill`` suffix, containing the program's source code.
-It consists of compilation options and other directives, imports of other modules,
-and source code for one or more code blocks.
-
-IL65 has a couple of *LIBRARY* modules that are defined in special internal files provided by the compiler:
-``c64lib``, ``il65lib``, ``mathlib``.
-You should not overwrite these or reuse their names.
-
-
-.. _debugging:
-
-Debugging (with Vice)
+Elements of a program
 ---------------------
 
-There's support for using the monitor and debugging capabilities of the rather excellent
-`Vice emulator <http://vice-emu.sourceforge.net/>`_.
+Program
+	Consists of one or more *modules*.
 
-The ``%breakpoint`` directive (see :ref:`directives`) in the source code instructs the compiler to put
-a *breakpoint* at that position. Some systems use a BRK instruction for this, but
-this will usually halt the machine altogether instead of just suspending execution.
-IL65 issues a NOP instruction instead and creates a 'virtual' breakpoint at this position.
-All breakpoints are then written to a file called "programname.vice-mon-list",
-which is meant to be used by the Vice emulator.
-It contains a series of commands for Vice's monitor, including source labels and the breakpoint settings.
-If you use the vice autostart feature of the compiler, it will be processed by Vice automatically and immediately.
-If you launch Vice manually, you'll have to use a command line option to load this file:
+Module
+	A file on disk with the ``.ill`` suffix. It contains *directives* and *code blocks*.
+	Whitespace and indentation in the source code are arbitrary and can be tabs or spaces or both.
+	You can also add *comments* to the source code.
+	One moudule file can *import* others, and also import *library modules*.
 
-	``$ x64 -moncommands programname.vice-mon-list``
+Comments
+	Everything after a semicolon ``;`` is a comment and is ignored by the compiler.
+	If the whole line is just a comment, it will be copied into the resulting assembly source code.
+	This makes it easier to understand and relate the generated code. Examples::
 
-Vice will then use the label names in memory disassembly, and will activate the breakpoints as well.
-If your running program hits one of the breakpoints, Vice will halt execution and drop you into the monitor.
+		A = 42    ; set the initial value to 42
+		; next is the code that...
+
+Directive
+	These are special instructions for the compiler, to change how it processes the code
+	and what kind of program it creates. A directive is on its own line in the file, and
+	starts with ``%``, optionally followed by some arguments.
+
+Code block
+	A block of actual program code. It defines a *scope* (also known as 'namespace') and
+	can contain IL65 *code*, *variable declarations* and *subroutines*.
+	More details about this below: :ref:`blocks`.
+
+Variable declarations
+	The data that the code works on is stored in variables ('named values that can change').
+	The compiler allocates the required memory for them.
+	There is *no dynamic memory allocation*. The storage size of all variables
+	is fixed and is determined at compile time.
+	Variable declarations tend to appear at the top of the code block that uses them.
+	They define the name and type of the variable, and its initial value.
+	IL65 supports a small list of data types, including special 'memory mapped' types
+	that don't allocate storage but instead point to a fixed location in the address space.
+
+Code
+	These are the instructions that make up the program's logic. There are different kinds of instructions
+	('statements' is a better name):
+
+	- value assignment
+	- looping  (for, while, repeat, unconditional jumps)
+	- conditional execution (if - then - else, and conditional jumps)
+	- subroutine calls
+	- label definition
+
+Subroutine
+	Defines a piece of code that can be called by its name from different locations in your code.
+	It accepts parameters and can return result values.
+	It can define its own variables but it's not possible to define subroutines nested in other subroutines.
+	To keep things simple, you can only define subroutines inside code blocks from a module.
+
+Label
+	This is a named position in your code where you can jump to from another place.
+	You can jump to it with a jump statement elsewhere. It is also possible to use a
+	subroutine call to a label (but without parameters and return value).
 
 
-Troubleshooting
----------------
+Scope
+	Also known as 'namespace', this is a named box around the symbols defined in it.
+	This prevents name collisions (or 'namespace pollution'), because the name of the scope
+	is needed as prefix to be able to access the symbols in it.
+	Anything *inside* the scope can refer to symbols in the same scope without using a prefix.
+	There are three scopes in IL65:
 
-Getting an assembler error about undefined symbols such as ``not defined 'c64flt'``?
-This happens when your program uses floating point values, and you forgot to import the ``c64lib``.
-If you use floating points, the program will need routines from that library.
-Fix it by adding an ``%import c64lib``.
+	- global (no prefix)
+	- code block
+	- subroutine
+
+	Modules are *not* a scope! Everything defined in a module is merged into the global scope.
+
+
+.. _blocks:
+
+Blocks, Scopes, and accessing Symbols
+-------------------------------------
+
+Blocks are the separate pieces of code and data of your program. They are combined
+into a single output program.  No code or data can occur outside a block. Here's an example::
+
+	~ main $c000 {
+		; this is code inside the block...
+	}
+
+
+The name of a block must be unique in your entire program.
+Also be careful when importing other modules; blocks in your own code cannot have
+the same name as a block defined in an imported module or library.
+
+It's possible to omit this name, but then you can only refer to the contents of the block via its absolute address,
+which is required in this case. If you omit *both* name and address, the block is *ignored* by the compiler (and a warning is displayed).
+This is a way to quickly "comment out" a piece of code that is unfinshed or may contain errors that you
+want to work on later, because the contents of the ignored block are not fully parsed either.
+
+The address can be used to place a block at a specific location in memory.
+Usually it is omitted, and the compiler will automatically choose the location (usually immediately after
+the previous block in memory).
+The address must be >= ``$0200`` (because ``$00``--``$ff`` is the ZP and ``$100``--``$200`` is the cpu stack).
+
+A block is also a *scope* in your program so the symbols in the block don't clash with
+symbols of the same name defined elsewhere in the same file or in another file.
+You can refer to the symbols in a particular block by using a *dotted name*: ``blockname.symbolname``.
+Labels inside a subroutine are appended again to that; ``blockname.subroutinename.label``.
+
+Every symbol is 'public' and can be accessed from elsewhere given its dotted name.
+
+
+**The special "ZP" ZeroPage block**
+
+Blocks named "ZP" are treated a bit differently: they refer to the ZeroPage.
+The contents of every block with that name (this one may occur multiple times) are merged into one.
+Its start address is always set to ``$04``, because ``$00 - $01`` are used by the hardware
+and ``$02 - $03`` are reserved as general purpose scratch registers.
+
+
+Program Start and Entry Point
+-----------------------------
+
+Your program must have a single entry point where code execution begins.
+The compiler expects a ``start`` subroutine in the ``main`` block for this,
+taking no parameters and having no return value.
+As any subroutine, it has to end with a ``return`` statement (or a ``goto`` call)::
+
+    ~ main {
+        sub start () -> ()  {
+            ; program entrypoint code here
+            return
+        }
+    }
+
+The ``main`` module is always relocated to the start of your programs
+address space, and the ``start`` subroutine (the entrypoint) will be on the
+first address. This will also be the address that the BASIC loader program (if generated)
+calls with the SYS statement.
+
+
+Variables and data
+------------------
+
+::
+
+	12345			; integer number
+	"Hi, I am a string"	; text string
+	-33.456e52		; floating point number
+
+	byte  counter  = 42	; variable of size 8 bits, with initial value 42
+
+
+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)
+
+
+Strings
+^^^^^^^
+
+Strings are a sequence of characters enclosed in ``"`` quotes.
+They're stored and treated much the same as a byte array,
+but they have some special properties because they are considered to be *text*.
+Strings in your source code files will be encoded (translated from ASCII/UTF-8) into either CBM PETSCII or C-64 screencodes.
+PETSCII is the default choice. If you need screencodes (also called 'poke' codes) instead,
+you have to use the ``str_s`` variants of the string type identifier.
+If you assign a string literal of length 1 to a non-string variable, it is treated as a *byte* value instead
+with has the PETSCII value of that single character,
+
+
+Floating point numbers
+^^^^^^^^^^^^^^^^^^^^^^
+
+Floats are stored in the 5-byte 'MFLPT' format that is used on CBM machines,
+and also most float operations are specific to the Commodore-64.
+This is because routines in the C-64 BASIC and KERNAL ROMs are used for that.
+So floating point operations will only work if the C-64 BASIC ROM (and KERNAL ROM)
+are banked in (and your code imports the ``c64lib.ill``)
+
+The largest 5-byte MFLPT float that can be stored is: **1.7014118345e+38**   (negative: **-1.7014118345e+38**)
+
+
+Initial values across multiple runs of the program
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The initial values of your variables will be restored automatically when the program is (re)started,
+*except for string variables*. It is assumed these are left unchanged by the program.
+If you do modify them in-place, you should take care yourself that they work as
+expected when the program is restarted.
+
+
+
+Indirect addressing and address-of
+----------------------------------
+
+The ``#`` operator is used to take the address of the symbol following it.
+It can be used for example to work with the *address* of a memory mapped variable rather than
+the value it holds.  You could take the address of a string as well, but that is redundant:
+the compiler already treats those as a value that you manipulate via its address.
+For most other types this prefix is not supported and will result in a compilation error.
+The resulting value is simply a 16 bit word. Example::
+
+	AX = #somevar
+
+
+
+**Indirect addressing:**
+@todo
+
+**Indirect addressing in jumps:**
+@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.
+
+
+Loops
+-----
+
+The *for*-loop is used to iterate over a range of values. Iteration steps by 1,
+but you can set it to something else as well.
+The *while*-loop is used to repeat a piece of code while a certain condition is still true.
+The *repeat--until* loop is used to repeat a piece of code until a certain condition is true.
+
+You can also create loops by using the ``goto`` statement, but this should be avoided.
+
+
+Conditional Execution
+---------------------
+
+@todo
+
+Conditional execution means that the flow of execution changes based on certiain conditions,
+rather than having fixed gotos or subroutine calls. IL65 has a *conditional goto* statement for this,
+that is translated into a comparison (if needed) and then a conditional branch instruction::
+
+	if[_XX] [<expression>] goto <label>
+
+
+The if-status XX is one of: [cc, cs, vc, vs, eq, ne, true, not, zero, pos, neg, lt, gt, le, ge]
+It defaults to 'true' (=='ne', not-zero) if omitted. ('pos' will translate into 'pl', 'neg' into 'mi')
+@todo signed: lts==neg?, gts==eq+pos?, les==neg+eq?, ges==pos?
+
+The <expression> is optional. If it is provided, it will be evaluated first. Only the [true] and [not] and [zero]
+if-statuses can be used when such a *comparison expression* is used. An example is::
+
+        if_not  A > 55  goto  more_iterations
+
+
+Conditional jumps are compiled into 6502's branching instructions (such as ``bne`` and ``bcc``) so
+the rather strict limit on how *far* it can jump applies. The compiler itself can't figure this
+out unfortunately, so it is entirely possible to create code that cannot be assembled successfully.
+You'll have to restructure your gotos in the code (place target labels closer to the branch)
+if you run into this type of assembler error.
+
+
+Assignments
+-----------
+
+Assignment statements assign a single value to a target variable or memory location.
+Augmented assignments (such as ``A += X``) are also available, but these are just shorthands
+for normal assignments (``A = A + X``).
+
+
+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.
+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
+
+
+Logical expressions
+^^^^^^^^^^^^^^^^^^^
+@todo
+
+
+Subroutines
+-----------
+
+Defining a subroutine
+^^^^^^^^^^^^^^^^^^^^^
+
+Subroutines are parts of the code that can be repeatedly invoked using a subroutine call from elsewhere.
+Their definition, using the sub statement, includes the specification of the required input- and output parameters.
+For now, only register based parameters are supported (A, X, Y and paired registers,
+the carry status bit SC and the interrupt disable bit SI as specials).
+For subroutine return values, the special SZ register is also available, it means the zero status bit.
+
+
+Calling a subroutine
+^^^^^^^^^^^^^^^^^^^^
+
+The output variables must occur in the correct sequence of return registers as specified
+in the subroutine's definiton. It is possible to not specify any of them but the compiler
+will issue a warning then if the result values of a subroutine call are discarded.
+If you don't have a variable to store the output register in, it's then required
+to list the register itself instead as output variable.
+
+Arguments should match the subroutine definition. You are allowed to omit the parameter names.
+If no definition is available (because you're directly calling memory or a label or something else),
+you can freely add arguments (but in this case they all have to be named).
+
+To jump to a subroutine (without returning), prefix the subroutine call with the word 'goto'.
+Unlike gotos in other languages, here it take arguments as well, because it
+essentially is the same as calling a subroutine and only doing something different when it's finished.
+
+**Register preserving calls:** use the ``!`` followed by a combination of A, X and Y (or followed
+by nothing, which is the same as AXY) to tell the compiler you want to preserve the origial
+value of the given registers after the subroutine call.  Otherwise, the subroutine may just
+as well clobber all three registers. Preserving the original values does result in some
+stack manipulation code to be inserted for every call like this, which can be quite slow.
diff --git a/docs/source/progstructure.rst b/docs/source/progstructure.rst
deleted file mode 100644
index 76d4107fc..000000000
--- a/docs/source/progstructure.rst
+++ /dev/null
@@ -1,164 +0,0 @@
-.. _programstructure:
-
-=================
-Program Structure
-=================
-
-This chapter describes a high level overview of the elements that make up a program.
-Details about each of them, and the syntax, are discussed in the :ref:`syntaxreference` chapter.
-
-
-Elements of a program
----------------------
-
-.. data:: Program
-
-	Consists of one or more *modules*.
-
-.. data:: Module
-
-	A file on disk with the ``.ill`` suffix. It contains *directives* and *code blocks*.
-	Whitespace and indentation in the source code are arbitrary and can be tabs or spaces or both.
-	You can also add *comments* to the source code.
-	One moudule file can *import* others, and also import *library modules*.
-
-.. data:: Comments
-
-	Everything after a semicolon ``;`` is a comment and is ignored by the compiler.
-	If the whole line is just a comment, it will be copied into the resulting assembly source code.
-	This makes it easier to understand and relate the generated code. Examples::
-
-		A = 42    ; set the initial value to 42
-		; next is the code that...
-
-.. data:: Directive
-
-	These are special instructions for the compiler, to change how it processes the code
-	and what kind of program it creates. A directive is on its own line in the file, and
-	starts with ``%``, optionally followed by some arguments.
-
-.. data:: Code block
-
-	A block of actual program code. It defines a *scope* (also known as 'namespace') and
-	can contain IL65 *code*, *variable declarations* and *subroutines*.
-	More details about this below: :ref:`blocks`.
-
-.. data:: Variable declarations
-
-	The data that the code works on is stored in variables ('named values that can change').
-	The compiler allocates the required memory for them.
-	There is *no dynamic memory allocation*. The storage size of all variables
-	is fixed and is determined at compile time.
-	Variable declarations tend to appear at the top of the code block that uses them.
-	They define the name and type of the variable, and its initial value.
-	IL65 supports a small list of data types, including special 'memory mapped' types
-	that don't allocate storage but instead point to a fixed location in the address space.
-
-.. data:: Code
-
-	These are the instructions that make up the program's logic. There are different kinds of instructions
-	('statements' is a better name):
-
-	- value assignment
-	- looping  (for, while, repeat, unconditional jumps)
-	- conditional execution (if - then - else, and conditional jumps)
-	- subroutine calls
-	- label definition
-
-.. data:: Subroutine
-
-	Defines a piece of code that can be called by its name from different locations in your code.
-	It accepts parameters and can return result values.
-	It can define its own variables but it's not possible to define subroutines nested in other subroutines.
-	To keep things simple, you can only define subroutines inside code blocks from a module.
-
-.. data:: Label
-
-	To label a position in your code where you can jump to from another place, you use a label like this::
-
-		nice_place:
-				; code ...
-
-	It's an identifier followed by a colon ``:``. It's allowed to put the next statement on
-	the same line, after the label.
-	You can jump to it with a jump statement elsewhere. It is also possible to use a
-	subroutine call to a label (but without parameters and return value).
-
-
-.. data:: Scope
-
-	Also known as 'namespace', this is a named box around the symbols defined in it.
-	This prevents name collisions (or 'namespace pollution'), because the name of the scope
-	is needed as prefix to be able to access the symbols in it.
-	Anything *inside* the scope can refer to symbols in the same scope without using a prefix.
-	There are three scopes in IL65:
-
-	- global (no prefix)
-	- code block
-	- subroutine
-
-	Modules are *not* a scope! Everything defined in a module is merged into the global scope.
-
-
-.. _blocks:
-
-Blocks, Scopes, and accessing Symbols
--------------------------------------
-
-Blocks are the separate pieces of code and data of your program. They are combined
-into a single output program.  No code or data can occur outside a block. Here's an example::
-
-	~ main $c000 {
-		; this is code inside the block...
-	}
-
-
-The name of a block must be unique in your entire program.
-Also be careful when importing other modules; blocks in your own code cannot have
-the same name as a block defined in an imported module or library.
-
-It's possible to omit this name, but then you can only refer to the contents of the block via its absolute address,
-which is required in this case. If you omit *both* name and address, the block is *ignored* by the compiler (and a warning is displayed).
-This is a way to quickly "comment out" a piece of code that is unfinshed or may contain errors that you
-want to work on later, because the contents of the ignored block are not fully parsed either.
-
-The address can be used to place a block at a specific location in memory.
-Usually it is omitted, and the compiler will automatically choose the location (usually immediately after
-the previous block in memory).
-The address must be >= ``$0200`` (because ``$00``--``$ff`` is the ZP and ``$100``--``$200`` is the cpu stack).
-
-A block is also a *scope* in your program so the symbols in the block don't clash with
-symbols of the same name defined elsewhere in the same file or in another file.
-You can refer to the symbols in a particular block by using a *dotted name*: ``blockname.symbolname``.
-Labels inside a subroutine are appended again to that; ``blockname.subroutinename.label``.
-
-Every symbol is 'public' and can be accessed from elsewhere given its dotted name.
-
-
-**The special "ZP" ZeroPage block**
-
-Blocks named "ZP" are treated a bit differently: they refer to the ZeroPage.
-The contents of every block with that name (this one may occur multiple times) are merged into one.
-Its start address is always set to ``$04``, because ``$00 - $01`` are used by the hardware
-and ``$02 - $03`` are reserved as general purpose scratch registers.
-
-
-Program Start and Entry Point
------------------------------
-
-Your program must have a single entry point where code execution begins.
-The compiler expects a ``start`` subroutine in the ``main`` block for this,
-taking no parameters and having no return value.
-As any subroutine, it has to end with a ``return`` statement (or a ``goto`` call)::
-
-    ~ main {
-        sub start () -> ()  {
-            ; program entrypoint code here
-            return
-        }
-    }
-
-The ``main`` module is always relocated to the start of your programs
-address space, and the ``start`` subroutine (the entrypoint) will be on the
-first address. This will also be the address that the BASIC loader program (if generated)
-calls with the SYS statement.
diff --git a/docs/source/syntaxreference.rst b/docs/source/syntaxreference.rst
index e8cd426d3..cc2c4c370 100644
--- a/docs/source/syntaxreference.rst
+++ b/docs/source/syntaxreference.rst
@@ -10,20 +10,22 @@ Module file
 This is a file with the ``.ill`` suffix, containing *directives* and *code blocks*, described below.
 The file is a text file wich can also contain:
 
-.. data:: Lines, whitespace, indentation
+Lines, whitespace, indentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-	Line endings are significant because *only one* declaration, statement or other instruction can occur on every line.
-	Other whitespace and line indentation is arbitrary and ignored by the compiler.
-	You can use tabs or spaces as you wish.
+Line endings are significant because *only one* declaration, statement or other instruction can occur on every line.
+Other whitespace and line indentation is arbitrary and ignored by the compiler.
+You can use tabs or spaces as you wish.
 
-.. data:: Source code comments
+Source code comments
+^^^^^^^^^^^^^^^^^^^^
 
-	Everything after a semicolon ``;`` is a comment and is ignored.
-	If the whole line is just a comment, it will be copied into the resulting assembly source code.
-	This makes it easier to understand and relate the generated code. Examples::
+Everything after a semicolon ``;`` is a comment and is ignored.
+If the whole line is just a comment, it will be copied into the resulting assembly source code.
+This makes it easier to understand and relate the generated code. Examples::
 
-		A = 42    ; set the initial value to 42
-		; next is the code that...
+	A = 42    ; set the initial value to 42
+	; next is the code that...
 
 
 .. _directives:
@@ -168,6 +170,19 @@ Also read :ref:`blocks`.  Here is an example of a code block, to be loaded at ``
 	}
 
 
+
+Labels
+------
+
+To label a position in your code where you can jump to from another place, you use a label::
+
+	nice_place:
+			; code ...
+
+It's just an identifier followed by a colon ``:``. It's allowed to put the next statement on
+the same line, after the label.
+
+
 Variables and value literals
 ----------------------------
 
@@ -178,7 +193,23 @@ data types below you can see how they should be written.
 Variable declarations
 ^^^^^^^^^^^^^^^^^^^^^
 
-@todo
+Variables should be declared with their exact type and size so the compiler can allocate storage
+for them. You can give them an initial value as well. That value can be a simple literal value,
+but you can put a (constant) expression there as well. The syntax is::
+
+	<datatype>   <variable name>   [ = <initial value> ]
+
+Various examples::
+
+	word        thing
+	byte        counter = 0
+	byte        age     = 2018 - 1974
+	float       wallet  = 55.25
+	str	    name    = "my name is Irmen"
+	word        address = #counter
+	byte[5]     values  = [11, 22, 33, 44, 55]
+	byte[5][6]  empty_matrix
+
 
 
 Data types
@@ -211,121 +242,132 @@ type identifier  type                     storage size       example var declara
 ===============  =======================  =================  =========================================
 
 
-**String encoding:**
-Strings in your code will be encoded (translated from ASCII/UTF-8) into either CBM PETSCII or C-64 screencodes.
-PETSCII is the default, so if you need screencodes (also called 'poke' codes)
-you have to use the ``_s`` variants of the string type identifier.
-A string literal of length 1 is considered to be a *byte* instead with
-that single character's PETSCII value.  If you really need a *string* of length 1 you
-can only do so by assigning it to a variable with one of the string types.
-
-**Floating point numbers:**
-Floats are stored in the 5-byte 'MFLPT' format that is used on CBM machines,
-and also most float operations are specific to the Commodore-64.
-This is because routines in the C-64 BASIC and KERNAL ROMs are used for that.
-So floating point operations will only work if the C-64 BASIC ROM (and KERNAL ROM)
-are banked in (and your code imports the ``c64lib.ill``)
-
-The largest 5-byte MFLPT float that can be stored is: **1.7014118345e+38**   (negative: **-1.7014118345e+38**)
-
-**Initial values over multiple runs:**
-The initial values of your variables will be restored automatically when the program is (re)started,
-*except for string variables*. It is assumed these are left unchanged by the program.
-If you do modify them in-place, you should take care yourself that they work as
-expected when the program is restarted.
-
-
 **@todo pointers/addresses?  (as opposed to normal WORDs)**
 **@todo signed integers (byte and word)?**
 
 
+Reserved names
+^^^^^^^^^^^^^^
 
-Indirect addressing and address-of
-----------------------------------
+The following names are reserved, they have a special meaning::
 
-**Address-of:**
-The ``#`` prefix is used to take the address of something.
-It can be used for example to work with the *address* of a memory mapped variable rather than
-the value it holds.  You could take the address of a string as well, but that is redundant:
-the compiler already treats those as a value that you manipulate via its address.
-For most other types this prefix is not supported and will result in a compilation error.
-The resulting value is simply a 16 bit word.
-
-**Indirect addressing:**
-@todo
-
-**Indirect addressing in jumps:**
-@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.
+	A    X    Y	; 6502 hardware registers
+	AX   AY   XY	; 16-bit pseudo register pairs
+	SC   SI   SZ	; bits of the 6502 hardware status register
 
 
-Conditional Execution
----------------------
+Operators
+---------
 
-Conditional execution means that the flow of execution changes based on certiain conditions,
-rather than having fixed gotos or subroutine calls. IL65 has a *conditional goto* statement for this,
-that is translated into a comparison (if needed) and then a conditional branch instruction::
+.. data::  #  (address-of)
 
-	if[_XX] [<expression>] goto <label>
+Takes the address of the symbol following it:   ``word  address =  #somevar``
 
 
-The if-status XX is one of: [cc, cs, vc, vs, eq, ne, true, not, zero, pos, neg, lt, gt, le, ge]
-It defaults to 'true' (=='ne', not-zero) if omitted. ('pos' will translate into 'pl', 'neg' into 'mi') 
-@todo signed: lts==neg?, gts==eq+pos?, les==neg+eq?, ges==pos?
+.. data::  +  -  *  /  //  **  %   (arithmetic)
 
-The <expression> is optional. If it is provided, it will be evaluated first. Only the [true] and [not] and [zero] 
-if-statuses can be used when such a *comparison expression* is used. An example is::
+``+``, ``-``, ``*``, ``/`` are the familiar arithmetic operations.
 
-        if_not  A > 55  goto  more_iterations
+``//`` means *integer division* even when the operands are floating point values:  ``9.5 // 2.5`` is 3 (and not 3.8)
+
+``**`` is the power operator: ``3 ** 5`` is equal to 3*3*3*3*3 and is 243.
+
+``%`` is the modulo operator: ``25 % 7`` is 4.
 
 
-Conditional jumps are compiled into 6502's branching instructions (such as ``bne`` and ``bcc``) so 
-the rather strict limit on how *far* it can jump applies. The compiler itself can't figure this
-out unfortunately, so it is entirely possible to create code that cannot be assembled successfully.
-You'll have to restructure your gotos in the code (place target labels closer to the branch)
-if you run into this type of assembler error.
+.. data::  <<  >>   <<@  >>@   &  |  ^  ~  (bitwise arithmetic)
+
+``<<`` and ``>>`` are bitwise shifts (left and right), ``<<@`` and ``@>>`` are bitwise rotations (left and right)
+
+``&`` is bitwise and, ``|`` is bitwise or, ``^`` is bitwise xor, ``~`` is bitwise invert (this one is an unary operator)
 
 
-Assignments
------------
+.. data::  =   (assignment)
 
-Assignment statements assign a single value to a target variable or memory location.::
-
-        target = value-expression
+Sets the target on the LHS (left hand side) of the operator to the value of the expression on the RHS (right hand side).
 
 
-Augmented Assignments
----------------------
+.. data::  +=  -=  *=  /=  //=  **=  <<=  >>=  <<@=  >>@=  &=  |=  ^=  (augmented assignment)
 
-A special assignment is the *augmented assignment* where the value is modified in-place.
-Several assignment operators are available: ``+=``, ``-=``, ``&=``, ``|=``, ``^=``, ``<<=``, ``>>=``
+Syntactic sugar; ``A += X`` is equivalent to ``A = A + X``
 
 
-Expressions
------------
+.. data::  ++  --   (postfix increment and decrement)
 
-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.
-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.
+Syntactic sugar; ``A++`` is equivalent to ``A = A + 1``, and ``A--`` is equivalent to ``A = A - 1``.
+Because these operations are so common, we have these short forms.
 
 
-Subroutines
------------
+.. data::  ==  !=  <  >  <=  >=  (comparison)
 
-Defining a subroutine
-^^^^^^^^^^^^^^^^^^^^^
+Equality, Inequality, Less-than, Greater-than, Less-or-Equal-than, Greater-or-Equal-than comparisons.
+The result is a 'boolean' value 'true' or 'false' (which in reality is just a byte value of 1 or 0).
 
-Subroutines are parts of the code that can be repeatedly invoked using a subroutine call from elsewhere.
-Their definition, using the sub statement, includes the specification of the required input- and output parameters.
-For now, only register based parameters are supported (A, X, Y and paired registers,
-the carry status bit SC and the interrupt disable bit SI as specials).
-For subroutine return values, the special SZ register is also available, it means the zero status bit.
+
+.. data::  not  and  or  xor  (logical)
+
+These operators are the usual logical operations that are part of a logical expression to reason
+about truths (boolean values). The result of such an expression is a 'boolean' value 'true' or 'false'
+(which in reality is just a byte value of 1 or 0).
+
+
+.. data::  ..    (range creation)
+
+Creates a range of values from the LHS value to the RHS value, inclusive.
+These are mainly used in for loops to set the loop range. Example::
+
+	0 .. 7		; range of values 0, 1, 2, 3, 4, 5, 6, 7  (constant)
+
+	A = 5
+	X = 10
+	A .. X		; range of 5, 6, 7, 8, 9, 10
+
+	byte[4] array = 10 .. 13   ; sets the array to [1, 2, 3, 4]
+
+	for  i  in  0 .. 127  {
+		; i loops 0, 1, 2, ... 127
+	}
+
+
+
+.. data::  [ ... ]   (array indexing)
+
+When put after a sequence type (array, string or matrix) it means to point to the given element in that sequence::
+
+	array[2]		; the third byte in the array (index is 0-based)
+	matrix[4,2]		; the byte at the 5th column and 3rd row in the matrix
+
+
+.. 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 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)``
+
+
+Subroutine calls
+----------------
+
+You call a subroutine like this::
+
+        [ result = ]  subroutinename_or_address ( [argument...] )
+
+        ; example:
+        outputvar1, outputvar2  =  subroutine ( arg1, arg2, arg3 )
+
+Arguments are separated by commas. The argument list can also be empty if the subroutine
+takes no parameters.
+If the subroutine returns one or more result values, you must use an assignment statement
+to store those values somewhere. If the subroutine has no result values, you must
+omit the assignment.
+
+
+
+Subroutine definitions
+----------------------
 
 The syntax is::
 
@@ -333,13 +375,33 @@ The syntax is::
                 ... statements ...
         }
 
-**proc_parameters =**
+        ; example:
+        sub  triple_something (amount: X) -> A  {
+        	return  X * 3
+        }
+
+The open curly brace must immediately follow the subroutine result specification on the same line,
+and can have nothing following it. The close curly brace must be on its own line as well.
+
+Pre-defined subroutines that are available on specific memory addresses
+(in system ROM for instance) can be defined by assigning the routine's memory address to the sub,
+and not specifying a code block::
+
+	sub  <identifier>  ([proc_parameters]) -> ([proc_results])  = <address>
+
+	; example:
+	sub  CLOSE  (logical: A) -> (A?, X?, Y?)  = $FFC3
+
+
+.. data:: proc_parameters
+
         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)
 
-**proc_results =**
+.. data:: proc_results
+
         comma separated list of <register> names specifying in which register(s) the output is returned.
         If the register name ends with a '?', that means the register doesn't contain a real return value but
         is clobbered in the process so the original value it had before calling the sub is no longer valid.
@@ -349,49 +411,53 @@ The syntax is::
         what the changed registers are, assume the worst")
 
 
-Pre-defined subroutines that are available on specific memory addresses 
-(in system ROM for instance) can also be defined using the 'sub' statement.
-To do this you assign the routine's memory address to the sub::
+Loops
+-----
 
-        sub  <identifier>  ([proc_parameters]) -> ([proc_results])  = <address>
+for loop
+^^^^^^^^
+@todo::
 
-example::
-
-        sub  CLOSE  (logical: A) -> (A?, X?, Y?)  = $FFC3"
+	for  <loopvar>  in  <range>  [ step <amount> ]   {
+		; do something...
+	}
 
 
-Calling a subroutine
-^^^^^^^^^^^^^^^^^^^^
+while loop
+^^^^^^^^^^
+@todo::
 
-You call a subroutine like this::
+	while  <condition>  {
+		; do something...
+	}
 
-        subroutinename_or_address ( [arguments...] )
 
-or::
+repeat--until loop
+^^^^^^^^^^^^^^^^^^
+@todo::
 
-        subroutinename_or_address ![register(s)] ( [arguments...] )
+	repeat  {
+		; do something...
+	} until  <condition>
 
-If the subroutine returns one or more values as results, you must use an assignment statement
-to store those values somewhere::
 
-        outputvar1, outputvar2  =  subroutine ( arg1, arg2, arg3 )
+Conditional Execution
+---------------------
 
-The output variables must occur in the correct sequence of return registers as specified
-in the subroutine's definiton. It is possible to not specify any of them but the compiler
-will issue a warning then if the result values of a subroutine call are discarded.
-If you don't have a variable to store the output register in, it's then required
-to list the register itself instead as output variable.
+Must align this with the various status bits in the cpu... not only true/false....
 
-Arguments should match the subroutine definition. You are allowed to omit the parameter names.
-If no definition is available (because you're directly calling memory or a label or something else),
-you can freely add arguments (but in this case they all have to be named).
+@todo::
 
-To jump to a subroutine (without returning), prefix the subroutine call with the word 'goto'.
-Unlike gotos in other languages, here it take arguments as well, because it
-essentially is the same as calling a subroutine and only doing something different when it's finished.
+	if  <condition>   {
+		; do something....
+	}
+	[ else {
+		; do something else...
+	} ]
+
+
+
+@todo::
+
+	if  <condition>  goto  <location>
 
-**Register preserving calls:** use the ``!`` followed by a combination of A, X and Y (or followed
-by nothing, which is the same as AXY) to tell the compiler you want to preserve the origial
-value of the given registers after the subroutine call.  Otherwise, the subroutine may just
-as well clobber all three registers. Preserving the original values does result in some
-stack manipulation code to be inserted for every call like this, which can be quite slow.