Documentation improvements

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Current version
 
+* Preliminary BBC Micro support.
+
 * Added array initialization syntax with `for` (not yet finalized).
 
 * Added multiple new text codecs.

README.md

@@ -30,6 +30,8 @@ For binary releases, see: https://github.com/KarolS/millfork/releases (latest: 0
     
     * Atari 8-bit computers
     
+    * BBC Micro
+    
     * Apple II+/IIe/Enhanced IIe
 
 * inline assembly
@@ -46,10 +48,10 @@ For binary releases, see: https://github.com/KarolS/millfork/releases (latest: 0
 
 * [Documentation](docs/index.md)
 
-* [Example programs](examples/index.md)
+* [Example programs](examples/README.md)
 
 ## Planned features
 
-* more targets: BBC Micro/Electron, Oric computers, PC-Engine/Turbografx-16, Atari Lynx
+* more targets: Oric computers, PC-Engine/Turbografx-16, Atari Lynx
  
 * support for 65816, SuperFamicom/SNES and Apple IIgs 

docs/README.md

@@ -0,0 +1,37 @@
+# Documentation
+
+ **★ WORK IN PROGRESS ★**
+
+
+## Compiler usage
+
+* [Getting started](api/getting-started.md)
+
+* [Command-line option reference](api/command-line.md)
+
+* [Target platform reference](api/target-platforms.md)
+
+## Language reference
+
+* [Syntax](lang/syntax.md)
+
+* [Types](lang/types.md)
+
+* [Operators reference](lang/operators.md)
+
+* [Functions](lang/functions.md)
+
+* [Inline assembly syntax](lang/assembly.md)
+
+* [Important guidelines regarding reentrancy](lang/reentrancy.md)
+
+
+## Implementation details
+
+* [Variable storage](abi/variable-storage.md)
+
+* [Undefined behaviour](abi/undefined-behaviour.md)
+
+* [Undocumented instruction support](abi/undocumented.md)
+
+* [Reference for labels in generated assembly code](abi/generated-labels.md)

docs/abi/generated-labels.md

@@ -1,3 +1,5 @@
+[< back to index](../index.md)
+
 # Guide to generated label names
 
 Many Millfork constructs generate labels. 

docs/abi/inlining.md

@@ -1,3 +1,5 @@
+[< back to index](../index.md)
+
 # Macros and inlining
 
 ## Macros

docs/abi/undefined-behaviour.md

@@ -1,3 +1,5 @@
+[< back to index](../index.md)
+
 # Undefined behaviour
 
 Since Millfork is only a middle-level programming language and attempts to eschew runtime checks in favour of performance, 

docs/abi/undocumented.md

@@ -1,3 +1,5 @@
+[< back to index](../index.md)
+
 # Undocumented opcodes
 
 Original 6502 processors accidentally supported a bunch of extra undocumented instructions.

docs/abi/variable-storage.md

@@ -1,3 +1,5 @@
+[< back to index](../index.md)
+
 # Variable storage
 
 Variables in Millfork can belong to one of the following storage classes:

docs/api/command-line.md

@@ -1,3 +1,5 @@
+[< back to index](../index.md)
+
 # Command-line options
 
 ## General options

docs/api/famicom-programming-guide.md

@@ -1,3 +1,5 @@
+[< back to index](../index.md)
+
 # Famicom/NES programming guide
 
 ## Program lifecycle

docs/api/getting-started.md

@@ -1,3 +1,5 @@
+[< back to index](../index.md)
+
 # Getting started
 
 ## Hello world example

docs/api/target-platforms.md

@@ -1,3 +1,5 @@
+[< back to index](../index.md)
+                                                      
 # Target platforms
 
 Currently, Millfork supports creating disk- or tape-based programs for Commodore, Apple and Atari 8-bit computers, 
@@ -167,4 +169,6 @@ Default: `after_code`.
     
     * `<segment>:<addr>:<addr>` - inclusive range of bytes in a given segment
     
-* `extension` – target file extension, with or without the dot
+* `extension` – target file extension, with or without the dot
+
+* `bbc_inf` – should the `.inf` file with file metadata for BBC Micro be created

docs/lang/assembly.md

@@ -1,3 +1,5 @@
+[< back to index](../index.md)
+
 # Using assembly within Millfork programs
 
 There are two ways to include raw assembly code in your Millfork programs:

docs/lang/functions.md

@@ -1,3 +1,5 @@
+[< back to index](../index.md)
+
 # Function definitions
 
 Syntax:

docs/lang/interfacing.md

@@ -1,3 +1,5 @@
+[< back to index](../index.md)
+
 # Interfacing with external code 
 
 ## Calling external functions at a static address

docs/lang/literals.md

@@ -1,3 +1,5 @@
+[< back to index](../index.md)
+
 # Literals and initializers
 
 ## Numeric literals
@@ -56,11 +58,29 @@ From the type system point of view, they are constants of type byte.
 
 ## Array initialisers 
 
-An array is initialized with either a string literal,
-or a list of byte literals and strings, surrounded by brackets:
+An array is initialized with either:
+
+* a string literal
+
+* a `file` expression
+
+* a `for`-style expression
+
+* a list of byte literals and/or other array initializers, surrounded by brackets:
+
 
     array a = [1, 2]
     array b = "----" scr
     array c = ["hello world!" ascii, 13]
+    array d = file("d.bin")
+    array e = file("d.bin", 128, 256)
+    array f = for x,0,until,8 [x * 3 + 5]  // equivalent to [5, 8, 11, 14, 17, 20, 23, 26]
 
-Trailing commas (`[1, 2,]`) are not allowed.
+Trailing commas (`[1, 2,]`) are not allowed.
+
+The parameters for `file` are: file path, optional start offset, optional length
+(start offset and length have to be either both present or both absent).
+
+The `for`-style expression has a variable, a starting index, a direction, a final index, 
+and a parametrizable array initializer.
+The initializer is repeated for every value of the variable in the given range.

docs/lang/operators.md

@@ -1,3 +1,5 @@
+[< back to index](../index.md)
+
 # Operators
 
 Unlike in high-level languages, operators in Millfork have limited applicability. 
@@ -198,4 +200,9 @@ Those expressions are of type `byte`. If `a` is any other kind of expression, `a
 `nonet(byte <<' constant byte)`  
 Other kinds of expressions than the above (even `nonet(byte + byte + byte)`) will not work as expected.
 
+* `hi`, `lo`: most/least significant byte of a word  
+`hi(word)`
+
+
+
 

docs/lang/reentrancy.md

@@ -1,3 +1,5 @@
+[< back to index](../index.md)
+
 # Reentrancy
 
 A function is called reentrant, 

docs/lang/syntax.md

@@ -1,3 +1,5 @@
+[< back to index](../index.md)
+
 # Syntax
 
 For information about types, see [Types](./types.md).  
@@ -86,6 +88,16 @@ if <expression> {
 }
 ```
 
+```
+if <expression> {
+    <body>
+} else if <expression> {
+    <body>
+} else {
+    <body>
+}
+```
+
 ### `return` statement
 
 Syntax:

docs/lang/types.md

@@ -1,3 +1,5 @@
+[< back to index](../index.md)
+
 # Types
 
 Millfork puts extra limitations on which types can be used in which contexts.

examples/README.md

@@ -2,7 +2,7 @@
 
 ## Cross-platform examples
 
-* [Hello world](hello_world/hello_world.mfk) (C64/C16/PET/VIC-20/Atari/Apple II) – simple text output
+* [Hello world](hello_world/hello_world.mfk) (C64/C16/PET/VIC-20/Atari/Apple II/BBC Micro) – simple text output
 
 ## Commodore 64 examples