From 608958c1ed88f91ad7ed76b14fee38757e72229b Mon Sep 17 00:00:00 2001
From: Karol Stasiak <karol.m.stasiak@gmail.com>
Date: Tue, 27 Feb 2018 13:26:56 +0100
Subject: [PATCH] Documentation improvements

---
 doc/abi/generated-labels.md |  2 ++
 doc/api/getting-started.md  |  4 ++--
 doc/api/target-platforms.md |  4 ++--
 doc/lang/assembly.md        |  4 +++-
 doc/lang/literals.md        | 41 +++++++++++++++++++++++++++++++++++++
 5 files changed, 50 insertions(+), 5 deletions(-)

diff --git a/doc/abi/generated-labels.md b/doc/abi/generated-labels.md
index 5d334974..51045ac9 100644
--- a/doc/abi/generated-labels.md
+++ b/doc/abi/generated-labels.md
@@ -46,6 +46,8 @@ where `11111` is a sequential number and `xx` is the type:
 
 * `to` – end of a `for-to` loop
 
+* `ur` – a copy due to loop unrolling
+
 * `wh` – beginning of a `while` statement
 
 
diff --git a/doc/api/getting-started.md b/doc/api/getting-started.md
index a0f68e10..c7e3d820 100644
--- a/doc/api/getting-started.md
+++ b/doc/api/getting-started.md
@@ -31,7 +31,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, `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)
 
 * `-I DIR;DIR;DIR;...` – specifies the paths to directories with modules to include.  
 
@@ -41,7 +41,7 @@ You may be also interested in the following:
 
 * `-O`, `-O2`, `-O3` – enable optimization (various levels)
 
-* `--detailed-flow` – use more resource-consuming but more precise flow analysis engine for better optimization
+* `--inline` – automatically inline functions for better optimization
 
 * `-s` – additionally generate assembly output
 
diff --git a/doc/api/target-platforms.md b/doc/api/target-platforms.md
index e6965b1c..d90bd1e5 100644
--- a/doc/api/target-platforms.md
+++ b/doc/api/target-platforms.md
@@ -34,8 +34,8 @@ Cartridge targets are not yet available.
 
 ### A note about Apple II
 
-Apple II variants other than II+/IIe/Enhanced IIe (which means the original II, IIc and IIc+) 
-and later compatible computers (Apple III and IIgs) are untested.
+Apple II variants other than II+/IIe/Enhanced IIe are untested;
+this includes the original II, IIc and IIc+, but also later compatible computers (Apple III and IIgs).
 They may or may not work.
 
 The compiler output is a raw machine code file, which then has to be put on a disk. 
diff --git a/doc/lang/assembly.md b/doc/lang/assembly.md
index 30214db2..a1d88299 100644
--- a/doc/lang/assembly.md
+++ b/doc/lang/assembly.md
@@ -15,11 +15,13 @@ Currently, `RMBx`/`SMBx`/`BBRx`/`BBSx` are not supported yet.
 
 Undocumented instructions are supported using various opcodes
 
-Labels have to be followed by a colon and they can optionally be on a separate line:
+Labels have to be followed by a colon and they can optionally be on a separate line.
+Indentation is not important:
 
     first:  INC x
     second: 
             INC y
+    INC z
 
 
 Label names have to start with a letter and can contain digits, underscores and letters.
diff --git a/doc/lang/literals.md b/doc/lang/literals.md
index 9f60d7b3..b0d344db 100644
--- a/doc/lang/literals.md
+++ b/doc/lang/literals.md
@@ -1 +1,42 @@
 # Literals and initializers
+
+## Numeric literals
+
+Decimal: `1`, `10`
+
+Binary: `%0101`, `0b101001`
+
+Hexadecimal: `$D323`, `0x2a2`
+
+## String literals
+
+String literals are surrounded with double quotes and followed by the name of the encoding:
+
+    "this is a string" ascii
+
+Characters between the quotes are interpreted literally, 
+there are no ways to escape special characters or quotes.
+
+Currently available encodings:
+
+* `ascii` – standard ASCII
+
+* `pet` or `petscii` – PETSCII (ASCII-like character set used by Commodore machines)
+
+* `scr` – Commodore screencodes
+
+When programming for Commodore,
+use `pet` for strings you're printing using standard I/O routines
+and `scr` for strings you're copying to screen memory directly.
+
+
+## Array initialisers 
+
+An array is initialized with either a string literal,
+or a list of byte literals and strings, surrounded by brackets:
+
+    array a = [1, 2]
+    array b = "----" scr
+    array c = ["hello world!" ascii, 13]
+
+Trailing commas (`[1, 2,]`) are not allowed.
\ No newline at end of file