Documentation overhaul

KarolS · Jul 15, 2019 · 52c5a10 · 52c5a10
1 parent f3dcfc7
commit 52c5a10
Show file tree

Hide file tree

Showing 47 changed files with 157 additions and 136 deletions.
diff --git a/README.md b/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
diff --git a/docs/README.md b/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)
+
diff --git a/docs/abi/calling-convention.md b/docs/abi/calling-convention.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Millfork calling convention
 

diff --git a/docs/abi/generated-labels.md b/docs/abi/generated-labels.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Guide to generated label names
 

diff --git a/docs/abi/inlining.md b/docs/abi/inlining.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Macros and inlining
 

diff --git a/docs/abi/undefined-behaviour.md b/docs/abi/undefined-behaviour.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Undefined behaviour
 

diff --git a/docs/abi/undocumented.md b/docs/abi/undocumented.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Undocumented opcodes
 

diff --git a/docs/abi/variable-storage.md b/docs/abi/variable-storage.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Variable storage
 

diff --git a/docs/api/apple2-programming-guide.md b/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
 

diff --git a/docs/api/bbcmicro-programming-guide.md b/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
 

diff --git a/docs/api/command-line.md b/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`.
 

diff --git a/docs/api/commodore-programming-guide.md b/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
 

diff --git a/docs/api/cpc-programming-guide.md b/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
 

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

diff --git a/docs/api/famicom-programming-guide.md b/docs/api/famicom-programming-guide.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Famicom/NES programming guide
 

diff --git a/docs/api/gb-programming-guide.md b/docs/api/gb-programming-guide.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Game Boy programming guide
 

diff --git a/docs/api/getting-started.md b/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.

diff --git a/docs/api/lunix-programming-guide.md b/docs/api/lunix-programming-guide.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 ### A note about LUnix
 

diff --git a/docs/api/rom-vs-ram.md b/docs/api/rom-vs-ram.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 ### ROM vs RAM targets
 

diff --git a/docs/api/target-platforms.md b/docs/api/target-platforms.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Target platforms
 

diff --git a/docs/index.md b/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. 
diff --git a/docs/lang/assembly.md b/docs/lang/assembly.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Using 6502 assembly within Millfork programs
 

diff --git a/docs/lang/assemblyz80.md b/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
 

diff --git a/docs/lang/functions.md b/docs/lang/functions.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Function definitions
 

diff --git a/docs/lang/interfacing.md b/docs/lang/interfacing.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Interfacing with external code 
 

diff --git a/docs/lang/literals.md b/docs/lang/literals.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Literals and initializers
 

diff --git a/docs/lang/operators.md b/docs/lang/operators.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Operators
 

diff --git a/docs/lang/preprocessor.md b/docs/lang/preprocessor.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Preprocessor
 

diff --git a/docs/lang/reentrancy.md b/docs/lang/reentrancy.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Reentrancy
 

diff --git a/docs/lang/syntax.md b/docs/lang/syntax.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Syntax
 

diff --git a/docs/lang/text.md b/docs/lang/text.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Text encodings ans escape sequences
 

diff --git a/docs/lang/types.md b/docs/lang/types.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Types
 

diff --git a/docs/lang/x86disclaimer.md b/docs/lang/x86disclaimer.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # 8086 support disclaimer
 

diff --git a/docs/logo_transparent.png b/docs/logo_transparent.png
diff --git a/docs/stdlib/c64.md b/docs/stdlib/c64.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 # Commodore 64-oriented modules
 

diff --git a/docs/stdlib/cbm_file.md b/docs/stdlib/cbm_file.md
@@ -1,4 +1,4 @@
-[< back to index](../index.md)
+[< back to index](../README.md)
 
 ## cbm_file
 

diff --git a/docs/stdlib/frequent.md b/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.