Documentation updates

CHANGELOG.md

@@ -10,7 +10,15 @@
 
 * Added character literals.
 
-* Fixed several bugs, most importantly invalid offsets for branching instructions.
+* Added 24-bit `farword` type. 
+
+* Fixed invalid offsets for branching instructions.
+
+* Fixed incorrectly overlapping local variables.
+
+* Fixed broken `downto` loops.
+
+* Fixed several other bugs.
 
 * Other improvements.
 

docs/abi/undefined-behaviour.md

@@ -24,7 +24,7 @@ even up to hardware damage.
 
 * on ROM-based platforms: writing to arrays
 
-* on ROM-based platforms: using global variables with an initial value
+* on ROM-based platforms: using global variables with an initial value (they will not be initialized!)
 
 * violating the [safe assembly rules](../lang/assembly.md)
 

docs/api/command-line.md

@@ -83,7 +83,7 @@ This may cause problems if the parameter table is stored next to a hardware regi
 
 * `-O0` – Disable all optimizations.
 
-* `-O`, `-O2`, `-O3` – Optimize code, various levels.
+* `-O`, `-O2` ... `-O8` – Optimize code, various levels. For most code, anything above `-O4` doesn't improve it anymore. 
 
 * `-O9` – Optimize code using superoptimizer (experimental). Computationally expensive, decent results.
 

docs/api/getting-started.md

@@ -33,7 +33,7 @@ x64 hello_world.prg
 
 The following options are crucial when compiling your sources:
 
-* `-o FILENAME` – specifies the base name for your output file, an appropriate file extension will be appended (`prg` for Commodore, `xex` for Atari, `a2` for Apple, `asm` for assembly output, `lbl` for label file)
+* `-o FILENAME` – specifies the base name for your output file, an appropriate file extension will be appended (`prg` for Commodore, `xex` for Atari, `a2` for Apple, `asm` for assembly output, `lbl` for label file, `inf` for BBC file metadata)
 
 * `-I DIR;DIR;DIR;...` – specifies the paths to directories with modules to include.  
 
@@ -41,7 +41,7 @@ The following options are crucial when compiling your sources:
 
 You may be also interested in the following:
 
-* `-O`, `-O2`, `-O3` – enable optimization (various levels)
+* `-O`, `-O2`, `-O3`, `-O4` – enable optimization (various levels)
 
 * `--inline` – automatically inline functions for better optimization
 

docs/lang/assembly.md

@@ -31,9 +31,6 @@ Label names have to start with a letter and can contain digits, underscores and
 This means than they cannot start with a period like in many other assemblers.
 Similarly, anonymous labels designated with `+` or `-` are also not supported
 
-Labels are global, 
-which means that they live in the same namespace as functions, types and global variables.
-
 Assembly can refer to variables and constants defined in Millfork,
 but you need to be careful with using absolute vs immediate addressing:
 
@@ -173,7 +170,7 @@ it should abide to the following rules:
     
     * do not change the data page register (keep an eye at the `PLD`, `MVN`, `MVP` instructions)
     
-    * explicitly use 16-bit immediate operands when appropriate; the assembler doesn't track flags and assumes 8-bit immediates by default
+    * explicitly use 16-bit immediate operands when appropriate; the assembler doesn't track flags and assumes 8-bit immediates by default (TODO: actually implement the 16-bit inline assembly correctly)
     
     * use far jumps unless you're sure that the called function returns with an `RTS`  
     

docs/lang/functions.md

@@ -25,13 +25,13 @@ Syntax:
     
     * `interrupt` – the function is a hardware interrupt handler.
     You are not allowed to call such functions directly.
-    The function cannot have parameters and the retrn type should be `void`.
+    The function cannot have parameters and the return type should be `void`.
     
     * `kernal_interrupt` – the function is an interrupt handler called from a generic vendor-provider hardware interrupt handler.
     The hardware instruction handler is assumed to have preserved the CPU registers,
     so this function only has to preserve the zeropage pseudoregisters.
     An example is the Commodore 64 interrupt handler that calls the function at an address read from $314/$315.
-    Unline hardware handlers with `interrupt`, you can treat functions with `kernal_interrupt` like normal functions. 
+    Unlike hardware handlers with `interrupt`, you can treat functions with `kernal_interrupt` like normal functions. 
     
 * `<return_type>` is a valid return type, see [Types](./types.md)
 

src/main/scala/millfork/Main.scala

@@ -194,7 +194,7 @@ object Main {
     parameter("-t", "--target").placeholder("<platform>").action { (p, c) =>
       assertNone(c.platform, "Platform already defined")
       c.copy(platform = Some(p))
-    }.description("Target platform, any of: c64, c16, plus4, vic20, vic20_3k, vic20_8k, pet, c128, a8.")
+    }.description("Target platform, any of: c64, c16, plus4, vic20, vic20_3k, vic20_8k, pet, c128, a8, bbc, apple2, nes_mmc4, nes_small, c64_scpu, c64_scpu16, vcs.")
 
     parameter("-I", "--include-dir").repeatable().placeholder("<dir>;<dir>;...").action { (paths, c) =>
       val n = paths.split(";")
@@ -242,11 +242,11 @@ object Main {
       c.changeFlag(CompilationFlag.EmitEmulation65816Opcodes, b = true)
       c.changeFlag(CompilationFlag.EmitNative65816Opcodes, b = false)
       c.changeFlag(CompilationFlag.ReturnWordsViaAccumulator, b = false)
-    }.description("Emit 65816 opcodes (experimental).")
+    }.description("Emit 65816 opcodes in emulation mode (experimental).")
     flag("-fnative-65816-ops").action { c =>
       c.changeFlag(CompilationFlag.EmitEmulation65816Opcodes, b = true)
       c.changeFlag(CompilationFlag.EmitNative65816Opcodes, b = true)
-    }.description("Emit 65816 opcodes (experimental).")
+    }.description("Emit 65816 opcodes in native mode (very experimental and buggy).")
     boolean("-flarge-code", "-fsmall-code").action { (c, v) =>
       c.changeFlag(CompilationFlag.LargeCode, v)
     }.description("Whether should use 24-bit or 16-bit jumps to subroutines (not yet implemented).").hidden()