Documentation overhaul

README.md

@@ -59,18 +59,7 @@ Therefore, no attribution is needed if you are developing and distributing Millf
 
 ## More info
 
-* [Documentation](docs/index.md)
+* [Documentation](docs/README.md) (external version: [https://millfork.readthedocs.io](https://millfork.readthedocs.io))
 
 * [Example programs](examples/README.md)
 
-## Planned features
-
-* stdlib improvements
-
-* more 6502 targets: Oric computers, PC-Engine/Turbografx-16, Atari Lynx
-
-* more Z80 targets: TI-83, Sega Master System
- 
-* better support for 65816, Sharp LR35902 and eZ80
-
-* support for SuperFamicom/SNES and Apple IIgs

docs/README.md

@@ -1,7 +1,6 @@
-# Documentation
-
- **★ WORK IN PROGRESS ★**
+# Documentation index
 
+* [Home page](index.md)
 
 ## Compiler usage
 
@@ -68,3 +67,16 @@
 * [Undocumented instruction support](abi/undocumented.md)
 
 * [Reference for labels in generated assembly code](abi/generated-labels.md)
+
+## External links
+
+* [Example programs](https://github.com/KarolS/millfork/tree/master/examples)
+
+* [Millfork wiki](https://github.com/KarolS/millfork/wiki)
+
+* [Benchmarks](https://github.com/KarolS/millfork-benchmarks)
+
+* [Downloads](https://github.com/KarolS/millfork/releases/)  
+
+* [Source code](https://github.com/KarolS/millfork)
+

docs/abi/calling-convention.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Millfork calling convention
 

docs/abi/generated-labels.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Guide to generated label names
 

docs/abi/inlining.md

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

docs/abi/undefined-behaviour.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Undefined behaviour
 

docs/abi/undocumented.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Undocumented opcodes
 

docs/abi/variable-storage.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Variable storage
 

docs/api/apple2-programming-guide.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 ### A note about Apple II
 

docs/api/bbcmicro-programming-guide.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 ### A note about BBC Micro
 

docs/api/command-line.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Command-line options
 
@@ -15,16 +15,19 @@
 *  `-o <file>` – Output filename, without extension.
 Extension will be added automatically,
 `.prg` for Commodore (including LUnix/LNG),
-`.a2` for Apple,
+`.crt` for Commodore cartridges,
 `.xex` for Atari computers,
-`.bin` for Atari VCS,
-`.nes` for NES,
-no extension for BBC micro program file,
-`.inf` for BBC Micro metadata,
-`.d88` for PC-88 disk images,
-`.com` for CP/M executables,
+`.a2` for Apple,
+`.dsk` for PC-88 disk images,
+`.tap` for ZX-Spectrum tape images,
 `.rom` for MSX cartridge images,
-`.tap` for ZX-Spectrum tape images.
+`.com` for CP/M executables,
+`.nes` for NES/Famicom,
+`.bin` for Atari 2600,
+no extension for BBC micro program file,
+`.inf` for BBC Micro file metadata,
+`.asm` for assembly output,
+`.lbl`, `.nl`, `.fns`, or `.sym` for label file.
 
 * `-s` – Generate also the assembly output. It is not compatible with any assembler, but it serves purely informational purpose. The file has the same nam as the output file and the extension is `.asm`.
 

docs/api/commodore-programming-guide.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 ### A note about Commodore 64
 

docs/api/cpc-programming-guide.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 ### A note about Amstrad CPC
 

docs/api/custom-platform.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 ## Adding a custom platform
 

docs/api/famicom-programming-guide.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Famicom/NES programming guide
 

docs/api/gb-programming-guide.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Game Boy programming guide
 

docs/api/getting-started.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Getting started
 
@@ -21,6 +21,12 @@ Compile it using the following commandline:
 java -jar millfork.jar hello_world.mfk -o hello_world -t c64
 ```
 
+or if you're using a Windows native build:
+
+```
+millfork hello_world.mfk -o hello_world -t c64
+```
+
 Run the output executable (here using the VICE emulator):
 
 ```
@@ -31,20 +37,7 @@ 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;
-`crt` for Commodore cartridges;
-`xex` for Atari computers;
-`a2` for Apple;
-`dsk` for PC-88;
-`tap` for ZX Spectrum;
-`rom` for MSX cartridges;
-`com` for CP/M;
-`nes` for Famicom;
-`bin` for Atari 2600;
-`inf` for BBC file metadata;
-`asm` for assembly output;
-`lbl`, `nl`, `fns`, or `sym` for label file
+* `-o FILENAME` – specifies the base name for your output file, an appropriate file extension will be appended.
 
 * `-t PLATFORM` – specifies the target platform.
 Each platform is defined in an `.ini` file in the include directory.

docs/api/lunix-programming-guide.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 ### A note about LUnix
 

docs/api/rom-vs-ram.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 ### ROM vs RAM targets
 

docs/api/target-platforms.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
                                                       
 # Target platforms
 

docs/index.md

@@ -1,70 +1,35 @@
-# Documentation
+![](./logo_transparent.png)
 
- **★ WORK IN PROGRESS ★**
+**Millfork** is a middle-level programming language for 8-bit microprocessors.
 
+Millfork focuses on performance, compactness, simplicity and readability.
 
-## Compiler usage
+* [**Documentation index**](README.md)
 
-* [Getting started](api/getting-started.md)
+* [**Getting started**](api/getting-started.md)
 
-* [Command-line option reference](api/command-line.md)
+* [**List of supported platforms**](api/target-platforms.md)
 
-* [Target platform reference](api/target-platforms.md)
+* [**Example programs**](https://github.com/KarolS/millfork/tree/master/examples)
 
-* [Defining a custom platform](api/custom-platform.md)
+* [**Millfork wiki**](https://github.com/KarolS/millfork/wiki)
 
-## Language reference
+* [**Benchmarks**](https://github.com/KarolS/millfork-benchmarks)
 
-* [Preprocessor](lang/preprocessor.md)
+* [**FAQ**](various/faq.md)
 
-* [Syntax](lang/syntax.md)
+* [**Downloads**](https://github.com/KarolS/millfork/releases/)  
 
-* [Types](lang/types.md)
+* [**Source code**](https://github.com/KarolS/millfork)
 
-* [Literals](lang/literals.md)
+#### Contact
 
-* [List of text encodings and escape sequences](lang/text.md)
+Send issues, questions, feature requests and patches to https://github.com/KarolS/millfork/issues/
 
-* [Operators reference](lang/operators.md)
+#### License
 
-* [Functions](lang/functions.md)
+Millfork is © by Karol Stasiak, and is released under the GNU Public License version 3.
 
-* [Inline 6502 assembly syntax](lang/assembly.md)
+Millfork standard include files are © by Karol Stasiak, and are released under the zlib License.
 
-* [Inline 8080/LR35902/Z80 assembly syntax](lang/assemblyz80.md)
-
-* [Important guidelines regarding reentrancy](lang/reentrancy.md)
-
-## Library reference
-
-* [`stdlib` module](stdlib/stdlib.md)
-
-* [`string` module](stdlib/string.md)
-
-* [`stdio` module](stdlib/stdio.md)
-
-* [Modules for reading input devices](stdlib/input.md)
-
-* [Other cross-platform modules (`keyboard`, `err`, `random`)](stdlib/other.md)
-
-* [Definitions available on only some platforms](stdlib/frequent.md)
-
-* [C64-only modules](stdlib/c64.md)
-
-* [`cbm_file` module](stdlib/cbm_file.md)
-
-* [NES-only modules](stdlib/nes.md)
-
-* [Game Boy–only modules](stdlib/gb.md)
-
-## Implementation details
-
-* [Variable storage](abi/variable-storage.md)
-
-* [Calling convention](abi/calling-convention.md)
-
-* [Undefined behaviour](abi/undefined-behaviour.md)
-
-* [Undocumented instruction support](abi/undocumented.md)
-
-* [Reference for labels in generated assembly code](abi/generated-labels.md)
+This means you are allowed to develop Millfork programs, both free and proprietary, open- and closed-source, without any extra obligations or requirements. 

docs/lang/assembly.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Using 6502 assembly within Millfork programs
 

docs/lang/assemblyz80.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Using 8080/LR35902/Z80 assembly within Millfork programs
 

docs/lang/functions.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Function definitions
 

docs/lang/interfacing.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Interfacing with external code 
 

docs/lang/literals.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Literals and initializers
 

docs/lang/operators.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Operators
 

docs/lang/preprocessor.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Preprocessor
 

docs/lang/reentrancy.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Reentrancy
 

docs/lang/syntax.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Syntax
 

docs/lang/text.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Text encodings ans escape sequences
 

docs/lang/types.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Types
 

docs/lang/x86disclaimer.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # 8086 support disclaimer
 

docs/stdlib/c64.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Commodore 64-oriented modules
 

docs/stdlib/cbm_file.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 ## cbm_file
 

docs/stdlib/frequent.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 Definitions on the following list are frequently provided by the default automatically-imported modules. 
 

docs/stdlib/gb.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Game Boy–oriented modules
 

docs/stdlib/input.md

@@ -1,10 +1,12 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 ## joy
 
 The module contains global variables representing the state of the one-button joystick.
 If the program is not using any joystick driver, the state of these variables is undefined.
 
+To actually use this module, an appropriate joystick module must be used, such as `c64_joy`, `nes_joy` or `gb_joy`.
+
 #### `sbyte input_dx`
 
 Horizontal joystick movement. 1 if right, -1 if left, 0 if neither.
@@ -36,6 +38,8 @@ The `mouse` module automatically imports the `x_coord` module.
 The module contains global variables representing the state of the mouse.
 If the program is not using any mouse driver, the state of these variables is undefined.
 
+To actually use this module, an appropriate mouse module must be used, such as `c1531`.
+
 #### `x_coord mouse_x`
 
 Mouse X position.

docs/stdlib/nes.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # NES/Famicom-oriented modules
 

docs/stdlib/other.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 ## keyboard
 

docs/stdlib/stdio.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 ## stdio
 

docs/stdlib/stdlib.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 ## stdlib
 

docs/stdlib/string.md

@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 ## string
 

docs/various/faq.md

@@ -1,4 +1,4 @@
-[< back to index](index.md)
+[< back to index](../README.md)
 
 # Frequently Asked Questions
 
@@ -20,7 +20,7 @@ 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, 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.
+Support for other devices using supported processors can be easily added, usually without modifying the compiler.
 
 ### What microprocessors are supported?
 
@@ -68,11 +68,9 @@ Unfortunately not:
 
 * Floating point math support is absent.
 
-* There are no complex datatypes yet.
+* Pointer arithmetic is very limited.
 
-* There are no arrays other than byte arrays.
-
-* There are no pointers other than byte pointers.
+* Millfork preprocessor is less powerful than C preprocessor.
 
 * There is no support for linking with external libraries not written in Millfork.
 You either need to rewrite foreign assembly into Millfork assembly syntax,

examples/README.md

@@ -30,6 +30,8 @@
 
 * [Galencia starfield](c64/galencia.mfk) – a port of the starfield effect from the game *Galencia* 
 
+* [Space Poker \[external link\]](https://github.com/KarolS/spacepoker) – a game made for the 2018 Reset C64 Craptastic 4KB Game Competition
+
 ### Other examples
 
 * Multifile ([source code](c64/multifile.mfk), [platform definition](c64/multifile.ini)) –

mkdocs.yml

@@ -0,0 +1,55 @@
+site_name: Millfork documentation
+theme: readthedocs
+nav:
+  - Home: index.md
+  - Index: README.md
+  - FAQ: various/faq.md
+  - User guide:
+    - Getting started: api/getting-started.md
+    - Command-line option reference: api/command-line.md
+    - Target platform reference: api/target-platforms.md
+    - Defining a custom platform: api/custom-platform.md
+    - Differences between ROM and RAM targets: api/rom-vs-ram.md
+    - Platform-specific guides:
+        - Apple 2: api/apple2-programming-guide.md
+        - Amstrad CPC: api/cpc-programming-guide.md
+        - Commodore 64: api/commodore-programming-guide.md
+        - C64 with LUnix: api/lunix-programming-guide.md
+        - BBC Micro: api/bbcmicro-programming-guide.md
+        - Game Boy: api/gb-programming-guide.md
+        - NES/Famicom: api/famicom-programming-guide.md
+  - Language reference:
+    - Preprocessor: lang/preprocessor.md
+    - Syntax: lang/syntax.md
+    - Types: lang/types.md
+    - Literals: lang/literals.md
+    - Text encodings: lang/text.md
+    - Operators: lang/operators.md
+    - Functions: lang/functions.md
+    - Inline 6502 assembly: lang/assembly.md
+    - Inline 8080/LR35902/Z80 assembly: lang/assemblyz80.md
+    - Reentrancy guidelines: lang/reentrancy.md
+  - Library reference:
+    - stdlib module: stdlib/stdlib.md
+    - string module: stdlib/string.md
+    - stdio module: stdlib/stdio.md
+    - keyboard, err, random: stdlib/other.md
+    - joy, mouse, x_coord: stdlib/input.md
+    - Platform-dependent modules: stdlib/frequent.md
+    - cbm_file module: stdlib/cbm_file.md
+    - C64-only modules: stdlib/c64.md
+    - NES-only modules: stdlib/nes.md
+    - Game Boy–only modules: stdlib/gb.md
+  - Implementation details:
+    - Calling convention: abi/calling-convention.md
+    - Generated labels: abi/generated-labels.md
+    - Inlining: abi/inlining.md
+    - Undefined behaviour: abi/undefined-behaviour.md
+    - Undocumented instruction support: abi/undocumented.md
+    - Variable storage: abi/variable-storage.md
+  - External links:
+    - Downloads: https://github.com/KarolS/millfork/releases/
+    - Source code: https://github.com/KarolS/millfork
+    - Example programs: https://github.com/KarolS/millfork/tree/master/examples
+    - Millfork wiki: https://github.com/KarolS/millfork/wiki
+    - Benchmarks: https://github.com/KarolS/millfork-benchmarks