slight improvement on scope doc, added doc example for %asminclude/%asmbinary

docs/source/index.rst

@@ -68,6 +68,16 @@ Language features
 Code example
 ------------
 
+Here is a hello world program::
+
+    %import textio
+
+    main {
+        sub start() {
+            txt.print("hello world i ♥ prog8\n")
+        }
+    }
+
 This code calculates prime numbers using the Sieve of Eratosthenes algorithm::
 
     %import textio

docs/source/programming.rst

@@ -39,7 +39,7 @@ Variable declarations
     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.
+    Variable declarations tend to appear at the top of the code block that uses them, but this is not mandatory.
     They define the name and type of the variable, and its initial value.
     Prog8 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.
@@ -62,6 +62,7 @@ Subroutine
     Their contents is scoped accordingly.
     Nested subroutines can access the variables from outer scopes.
     This removes the need and overhead to pass everything via parameters.
+    Subroutines do not have to be declared before they can be called.
 
 Label
     This is a named position in your code where you can jump to from another place.
@@ -69,17 +70,20 @@ Label
     subroutine call to a label (but without parameters and return value).
 
 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 Prog8:
+    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 scope levels in Prog8:
 
-	- global (no prefix)
-	- code block
-	- subroutine
+    - global (no prefix)
+    - code block
+    - subroutine
 
-	Modules are *not* a scope! Everything defined in a module is merged into the global scope.
+    While Modules are separate files, they are *not* separate scopes!
+    Everything defined in a module is merged into the global scope.
+    This is different from most other languages that have modules.
+    The global scope can only contain blocks and some directives, while the others can contain variables and subroutines too.
 
 
 .. _blocks:

docs/source/syntaxreference.rst

@@ -141,6 +141,8 @@ Directives
     The assembler will include the file as binary bytes at this point, prog8 will not process this at all.
     The optional offset and length can be used to select a particular piece of the file.
     The file is located relative to the current working directory!
+    To reference the contents of the included binary data, you can put a label in your prog8 code
+    just before the %asmbinary. An example program for this can be found below at the description of %asminclude.
 
 .. data:: %asminclude "<filename>"
 
@@ -149,10 +151,47 @@ Directives
     The assembler will include the file as raw assembly source text at this point,
     prog8 will not process this at all. Symbols defined in the included assembly can not be referenced
     from prog8 code. However they can be referenced from other assembly code if properly prefixed.
+    You can ofcourse use a label in your prog8 code just before the %asminclude directive, and reference
+    that particular label to get to (the start of) the included assembly.
     Be careful: you risk symbol redefinitions or duplications if you include a piece of
     assembly into a prog8 block that already defines symbols itself.
     The compiler first looks for the file relative to the same directory as the module containing this statement is in,
     if the file can't be found there it is searched relative to the current directory.
+    Here is a small example program to show how to use labels to reference the included contents from prog8 code::
+
+        %import textio
+        %zeropage basicsafe
+
+        main {
+
+            sub start() {
+                txt.print("first three bytes of included asm:\n")
+                uword included_addr = &included_asm
+                txt.print_ub(@(included_addr))
+                txt.spc()
+                txt.print_ub(@(included_addr+1))
+                txt.spc()
+                txt.print_ub(@(included_addr+2))
+
+                txt.print("\nfirst three bytes of included binary:\n")
+                included_addr = &included_bin
+                txt.print_ub(@(included_addr))
+                txt.spc()
+                txt.print_ub(@(included_addr+1))
+                txt.spc()
+                txt.print_ub(@(included_addr+2))
+                txt.nl()
+                return
+
+        included_asm:
+                %asminclude "inc.asm"
+
+        included_bin:
+                %asmbinary "inc.bin"
+
+            }
+        }
+
 
 .. data:: %breakpoint
 

docs/source/todo.rst

@@ -2,7 +2,9 @@
 TODO
 ====
 
-- add example in documentation for %asminclude and %asmbinary on how to refer to its contents via label or w/e
+- fix scope compilation errors for sub with same name as block (kefrenbars example, 'irq')
+
+- add example in documentation for %asminclude and %asmbinary on how to refer to its contents via label or whatever
 
 - test all examples (including imgviewer, assembler and petaxian) before release of the new version