Documentation fixes

docs/abi/variable-storage.md

@@ -15,7 +15,7 @@ Variables in Millfork can belong to one of the following storage classes:
 Variables can also belong to one of the following memory areas 
 (unless overridden with the `@` operator):
 
-* zeropage: all `pointer` variables and parameters with no defined memory segment (6502-like targets only)
+* zeropage: some variables and parameters with no defined memory segment, preferring pointers (6502-like targets only)
 
 * high RAM: all the other variables and parameters
 

docs/api/command-line.md

@@ -22,6 +22,7 @@ Extension will be added automatically,
 no extension for BBC micro program file,
 `.inf` for BBC Micro metadata,
 `.d88` for PC-88 disk images,
+`.com` for CP/M executables,
 `.rom` for MSX cartridge images,
 `.tap` for ZX-Spectrum tape images.
 
@@ -65,14 +66,32 @@ Choose syntax for assembly output on 8080-like targets.
 
 ## Code generation options
 
-* `-fcmos-ops`, `-fno-cmos-ops` – Whether should emit CMOS opcodes.  
-`.ini` equivalent: `emit_cmos`.
-Default: yes if targeting a 65C02-compatible architecture, no otherwise.
+#### For all targets
 
-* `-fillegals`, `-fno-illegals` – Whether should emit illegal (undocumented) NMOS opcodes.  
+* `-fvariable-overlap`, `-fno-variable-overlap` – Whether variables should overlap if their scopes do not intersect.  
+Default: yes.
+
+* `-fbounds-checking`, `-fno-bounds-checking` – Whether should insert bounds checking on array access.  
+Default: no.
+
+* `-fcompact-dispatch-params`, `-fno-compact-dispatch-params` – 
+Whether parameter values in return dispatch statements may overlap other objects. 
+This may cause problems if the parameter table is stored next to a hardware register that has side effects when reading.  
+`.ini` equivalent: `compact_dispatch_params`. Default: yes.
+
+* `-flenient-encoding`, `-fno-lenient-encoding` – 
+Whether the compiler should allow for invalid characters in string/character literals that use the default encodings and replace them with alternatives.
+`.ini` equivalent: `lenient_encoding`. Default: yes on Apple II, no otherwise.
+
+* `-fillegals`, `-fno-illegals` – Whether should emit illegal (undocumented) NMOS or Z80 opcodes.  
 `.ini` equivalent: `emit_illegals`.
 Default: no.
 
+#### 6502-related
+
+* `-fcmos-ops`, `-fno-cmos-ops` – Whether should emit CMOS opcodes.  
+`.ini` equivalent: `emit_cmos`.
+Default: yes if targeting a 65C02-compatible architecture, no otherwise.
 * `-f65ce02-ops`, `-fno-65ce02-ops` – Whether should emit 65CE02 opcodes.  
 `.ini` equivalent: `emit_65ce026`. 
 Default: yes if targeting 65CE02, no otherwise.
@@ -103,20 +122,11 @@ If disabled, a sofware decimal mode will be used.
 `.ini` equivalent: `decimal_mode`.
 Default: no if targeting Ricoh, yes otherwise.
 
-* `-fvariable-overlap`, `-fno-variable-overlap` – Whether variables should overlap if their scopes do not intersect.  
-Default: yes.
+* `-fsoftware-stack`, `-fno-software-stack` –
+Use a software stack for stack variables.
+`.ini` equivalent: `software_stack`. Default: no.
 
-* `-fbounds-checking`, `-fno-bounds-checking` – Whether should insert bounds checking on array access.  
-Default: no.
-
-* `-fcompact-dispatch-params`, `-fno-compact-dispatch-params` – 
-Whether parameter values in return dispatch statements may overlap other objects. 
-This may cause problems if the parameter table is stored next to a hardware register that has side effects when reading.  
-`.ini` equivalent: `compact_dispatch_params`. Default: yes.
-
-* `-flenient-encoding`, `-fno-lenient-encoding` – 
-Whether the compiler should allow for invalid characters in string/character literals that use the default encodings and replace them with alternatives.
-`.ini` equivalent: `lenient_encoding`. Default: yes on Apple II, no otherwise.
+#### 8080/Z80-related
 
 * `-fshadow-irq`, `-fno-shadow-irq` –
 Whether the interrupt routines should make use of Z80 shadow registers.
@@ -124,7 +134,7 @@ Whether the interrupt routines should make use of Z80 shadow registers.
 
 * `-fuse-ix-for-stack`, `-fuse-iy-for-stack`, `-fno-use-index-for-stack` –
 Which of Z80 index registers should be used for accessing stack variables, if any. 
-`.ini` equivalent: `ix_stack` and `iy_stack`. Default: IX on Z80, no otherwise.
+`.ini` equivalent: `ix_stack` and `iy_stack`. Default: IX on Z80 and 8086, no otherwise.
 
 * `-fuse-ix-for-scratch`, `-fno-use-ix-for-scratch` –
 Allow using the IX register for other purposes.
@@ -134,10 +144,6 @@ Allow using the IX register for other purposes.
 Allow using the IY register for other purposes.
 `.ini` equivalent: `iy_scratch`. Default: no.
 
-* `-fsoftware-stack`, `-fno-software-stack` –
-Use a software stack for stack variables.
-`.ini` equivalent: `software_stack`. Default: no.
-
 ## Optimization options
 
 * `-O0` – Disable all optimizations except unused global symbol removal.
@@ -181,7 +187,7 @@ Whether identical fragments of functions should be extracted into subroutines.
 Default: no. 
 
 * `-Os`, `--size` – Optimize for size, sacrificing some speed (experimental).
-Also enables `-fcode-deduplication`.
+Also enables `-fsubroutine-extraction`.
 
 * `-Of`, `--fast` – Optimize for speed, even if it increases the size a bit (experimental).
 Also enables `-finline`. 

docs/api/custom-platform.md

@@ -58,7 +58,7 @@ Default: the same as `encoding`.
     * `decimal_mode` – whether the compiler should emit decimal instructions, default is `false` on `ricoh` and `strictricoh` and `true` elsewhere;
     if disabled, a software decimal mode will be used
     
-    * `ro_arrays` – whether the compiler should warn upon array writes, default is `false`
+    * `ro_arrays` – (deprecated) whether the compiler should warn upon array writes, default is `false`
     
     * `prevent_jmp_indirect_bug` – whether the compiler should try to avoid the indirect JMP bug, 
     default is `false` on 65C02-compatible or non-6502 processors and `true` elsewhere
@@ -86,7 +86,7 @@ Default: the same as `encoding`.
     
     * `use_shadow_registers_for_irq` – use Z80 shadow registers in interrupt routines, default is `true` for Z80 and `false` otherwise
     
-    * `ix_stack` – use the IX register to access stack variables, default is `true` for Z80 and `false` otherwise
+    * `ix_stack` – use the IX register to access stack variables, default is `true` for Z80 and 8086, `false` otherwise
     
     * `iy_stack` – use the IY register to access stack variables, default is `false`
     
@@ -94,7 +94,7 @@ Default: the same as `encoding`.
     
     * `iy_scratch` – allow using the IY register for other purposes, default is `false`
     
-    * `software_stach` – use software stack for stack variables, default is `false`
+    * `software_stack` – use software stack for stack variables, default is `false`. Applicable only to 6502-based targets.
     
     * `output_intel_syntax` – use Intel syntax instead of Zilog syntax, default is `true` for Intel 8080/8085 and `false` otherwise
 
@@ -120,7 +120,7 @@ Note that the default segment for uninitialized arrays and variables is always `
 Default: `default`
 
 * `segment_NAME_start` – the first address used for automatic allocation in the segment.  
-Note that the `default` segment shouldn't start before $200, as the $0-$1FF range is reserved for the zeropage and the stack.  
+Note that on 6502-like targets, the `default` segment shouldn't start before $200, as the $0-$1FF range is reserved for the zeropage and the stack.  
 The `main` function will be placed as close to the beginning of its segment as possible, but not necessarily at `segment_NAME_start`
 
 * `segment_NAME_end` – the last address in the segment

docs/api/getting-started.md

@@ -31,9 +31,23 @@ x64 hello_world.prg
 
 The following options are obligatory 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 computers, `a2` for Apple, `asm` for assembly output, `lbl` for label file, `inf` for BBC file metadata, `dsk` for PC-88, `tap` for ZX Spectrum, `nes` for Famicom, `bin` for Atari 2600)
+* `-o FILENAME` – specifies the base name for your output file, an appropriate file extension will be appended
+(`prg` for Commodore,
+`xex` for Atari computers,
+`a2` for Apple,
+`asm` for assembly output,
+`lbl` for label file,
+`inf` for BBC file metadata,
+`dsk` for PC-88,
+`tap` for ZX Spectrum,
+`rom` for MSX cartridges,
+`com` for CP/M,
+`nes` for Famicom,
+`bin` for Atari 2600)
 
-* `-t PLATFORM` – specifies the target platform. Each platform is defined in an `.ini` file in the include directory. For the list of supported platforms, see [Supported platforms](target-platforms.md)
+* `-t PLATFORM` – specifies the target platform.
+Each platform is defined in an `.ini` file in the include directory.
+For the list of supported platforms, see [Supported platforms](target-platforms.md)
 
 You may be also interested in the following:
 

docs/faq.md

@@ -18,7 +18,7 @@ The goal of Millfork is to succeed where Atalan failed.
 Large programs in Millfork have been developed for Commodore 64.
 
 Millfork was also tested (via emulators) to run trivial programs on other 8-bit Commodore computers, 
-Atari 8-bit computers, Apple II, BBC Micro, ZX Spectrum 48k, NEC PC-88, CP/M, NES, Game Boy, Atari 2600 and MS-DOS.
+Atari 8-bit computers, Apple II, BBC Micro, ZX Spectrum 48k, NEC PC-88, MSX, CP/M, NES, Game Boy, Atari 2600 and MS-DOS.
 
 Support for other devices using supported processors can be easily added, usually without even modifying the compiler.
 

docs/lang/functions.md

@@ -35,7 +35,8 @@ Syntax:
     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.
-    Unlike 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.  
+    On non-6502-based targets, functions marked as `kernal_interrupt` don't differ from normal functions.
     
 * `<return_type>` is a valid return type, see [Types](./types.md)
 
@@ -45,7 +46,7 @@ Syntax:
     The function will be allocated at the address divisible by alignment.
     `fast` means different things depending on the target platform:
 
-    * on 6502, it means that the function will not cross a page boundary
+    * on 6502, it means that the function will not cross a page boundary if possible
     * on Z80, it is ignored   
 
 * `<address>` is a constant expression that defines where in the memory the function is or will be located.

docs/lang/operators.md

@@ -8,7 +8,7 @@ Most expressions involving single bytes compile,
 but for larger types usually you need to use in-place modification operators.  
 Further improvements to the compiler may increase the number of acceptable combinations. 
 
-Certain expressions require the commandline flag `-fzp-register` (`.ini` equivalent: `zeropage_register`) to be enabled.
+On 6502-like targets, certain expressions require the commandline flag `-fzp-register` (`.ini` equivalent: `zeropage_register`) to be enabled.
 They will be marked with (zpreg) next to them. 
 The flag is enabled by default, but you can disable it if you need to.
 

docs/lang/reentrancy.md

@@ -36,6 +36,10 @@ It is possible to make a safe nested call to a non-nesting safe function, provid
 * the non-nested parameters have to have the same values in all co-occurring calls: `f(5, f(5, 6, 7), 7)`
 
 In all other cases, the nested call may cause undefined behaviour.
+In such cases, it's recommended to introduce a temporary variable:
+
+    tmp_f11 = f(1,1)
+    f(0, tmp_f11)
 
 ## Recursion safety
 
@@ -54,6 +58,15 @@ In all other cases, the recursive call may cause undefined behaviour.
 The easiest, but suboptimal way to make a function recursion-safe is to make all local variables stack-allocated
 and assign all parameters to variables as soon as possible. This is slow though, so don't do it unless really necessary.
 
+Example:
+
+    word fibonacci(byte i) {
+       if i < 2 { return 1 }
+       stack byte j
+       j = i
+       return fibonacci(j-1) + fibonacci(j-2)
+    }
+
 ## Interrupt safety
 
 A function is interrupt-safe if it can be safely called, either directly or indirectly,

docs/lang/syntax.md

@@ -46,7 +46,7 @@ For every variable `x` larger than a byte, extra subvariables are defined:
 
     * constituent bytes, from low to high: `x.lo`, `x.hi`
 
-* if `x` is of type `farword`: 
+* if `x` is of type `int24`: 
 
     * constituent bytes, from low to high: `x.b0`, `x.b1`, `x.b2`
     

docs/lang/types.md

@@ -100,14 +100,20 @@ equal to the number of variants in the enumeration.
 
 Assigment between numeric types and enumerations is not possible without an explicit type cast:
 
-    enum E {}
+    enum E { EA, EB }
     byte b
     E e
+    e = EA      // ok
     e = b       // won't compile
     b = e       // won't compile
     b = byte(e) // ok
     e = E(b)    // ok
     
+    array a[E]  // E is plain, array has size 2
+    a[0]        // won't compile
+    a[EB]       // ok
+    
+    
 Plain enumerations have their variants equal to `byte(0)` to `byte(<name>.count - 1)`.
     
 Tip: You can use an enumeration with no variants as a strongly checked alternative byte type,