docs

docs/source/building.rst

@@ -35,20 +35,19 @@ The most interesting gradle commands to run are probably:
         Creates a zipfile with the above in it, for easy distribution.
         This file can be found in ``./compiler/build/distributions/``
 
-For normal use, the ``installDist`` target should suffice and after succesful completion, you can start the compiler with:
+For normal use, the ``installDist`` task should suffice and after succesful completion, you can start the compiler with:
 
     ``./compiler/build/install/p8compile/bin/p8compile <options> <sourcefile>``
 
-(You should probably make an alias...)
+(You should probably make an alias or link...)
 
 .. hint::
     Development and testing is done on Linux using the IntelliJ IDEA IDE,
-    but the compiler should run on most operating systems that provide a fairly modern
-    java runtime (11 or newer). If you do have trouble building or running the compiler on your
-    operating system, please let me know!
+    but the compiler should run on all operating systems that provide a java runtime (version 11 or newer).
+    If you do have trouble building or running the compiler on your operating system, please let me know!
 
-    To successfully build and debug in IDEA, you have to manually generate the Antlr-parser classes
-    first. The easiest way to do this is the following:
+    To successfully build and debug in IDEA, you have to manually generate the Antlr-parser classes first.
+    The easiest way to do this is the following:
 
     1. make sure you have the Antlr4 plugin installed in IDEA
     2. right click the grammar file Prog8ANTLR.g4 in the parser project, and choose "Generate Antlr Recognizer" from the menu.
@@ -110,9 +109,10 @@ One or more .p8 module files
     Prints short command line usage information.
 
 ``-target <compilation target>``
-    Sets the target output of the compiler, currently 'c64' and 'cx16' are valid targets.
-    c64 = Commodore 64, c128 = Commodore 128, cx16 = Commander X16, atari = Atari 800 XL
-    Default = c64
+    Sets the target output of the compiler.
+    ``c64`` = Commodore 64, ``c128`` = Commodore 128, ``cx16`` = Commander X16, ``atari`` = Atari 800 XL,
+    ``virtual`` = builtin virtual machine.
+    Default = ``c64``.
 
 ``-srcdirs <pathlist>``
     Specify a list of extra paths (separated with ':'), to search in for imported modules.

docs/source/programming.rst

@@ -236,7 +236,7 @@ Unsigned integers are in the range 0-255 for unsigned byte types, and 0-65535 fo
 The signed integers integers are in the range -128..127 for bytes,
 and -32768..32767 for words.
 
-.. caution::
+.. attention::
     Doing math on signed integers can result in code that is a lot larger and slower than
     when using unsigned integers. Make sure you really need the signed numbers, otherwise
     stick to unsigned integers for efficiency.
@@ -419,8 +419,8 @@ address you specified, and setting the varible will directly modify that memory
 
 .. _pointervars_programming:
 
-Direct access to memory locations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Direct access to memory locations ('peek' and 'poke')
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Normally memory locations are accessed by a *memory mapped* name, such as ``c64.BGCOL0`` that is defined
 as the memory mapped address $d021.
 
@@ -483,7 +483,7 @@ Iterating with a floating point variable is not supported. If you want to loop o
 The *while*-loop is used to repeat a piece of code while a certain condition is still true.
 The *do--until* loop is used to repeat a piece of code until a certain condition is true.
 The *repeat* loop is used as a short notation of a for loop where the loop variable doesn't matter and you're only interested in the number of iterations.
-(without iteration count specified it simply loops forever).
+(without iteration count specified it simply loops forever). A repeat loop will result in the most efficient code generated so use this if possible.
 
 You can also create loops by using the ``goto`` statement, but this should usually be avoided.
 

docs/source/syntaxreference.rst

@@ -374,8 +374,8 @@ should be the *memory address* where the value is located::
 
 .. _pointervars:
 
-Direct access to memory locations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Direct access to memory locations ('peek' and 'poke')
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Instead of defining a memory mapped name for a specific memory location, you can also
 directly access the memory. Enclose a numeric expression or literal with ``@(...)`` to do that::
 

docs/source/targetsystem.rst

@@ -15,12 +15,14 @@ Currently these machines can be selected as a compilation target (via the ``-tar
 - 'cx16': the `Commander X16 <https://www.commanderx16.com/>`_
 - 'c128': the Commodore 128  (*limited support*)
 - 'atari': the Atari 800 XL  (*experimental support*)
+- 'virtual': a builtin virtual machine
 
 This chapter explains some relevant system details of the c64 and cx16 machines.
 
 .. hint::
     If you only use standard kernal and prog8 library routines,
-    it is possible to compile the *exact same program* for both machines (just change the compilation target flag)!
+    it is often possible to compile the *exact same program* for
+    different machines (just change the compilation target flag)!
 
 
 Memory Model

docs/source/technical.rst

@@ -26,6 +26,7 @@ The software stack is implemented as follows:
 - 2 pages of memory are allocated for this, exact locations vary per machine target.
   For the C-64 they are set at $ce00 and $cf00 (so $ce00-$cfff is reserved).
   For the Commander X16 they are set at $0400 and $0500 (so $0400-$05ff are reserved).
+  This default location can be overridden using the `-esa` command line option.
 - these are the high and low bytes of the values on the stack (it's a 'split 16 bit word stack')
 - for byte values just the lsb page is used, for word values both pages
 - float values (5 bytes) are chopped up into 2 words and 1 byte on this stack.

docs/source/todo.rst

@@ -23,6 +23,7 @@ Future Things and Ideas
 Compiler:
 
 - vm/ir: all(), any(), reverse() and sort() still depend on a VM Syscall. Get rid of this. (maybe use a IR 'builtin' function?)
+- vm/ir: put variables and arrays in BSS section (unless -noreinit is specified)
 - vm: Jumps go to a code block rather than a specific address(label) -> also helps future dead code elimination?
 - vm: the above means that every label introduces a new code block. This eliminates the use of actual labels altogether.
 - vm: add more optimizations in IRPeepholeOptimizer