Reorder some sections

doc/tal.md

@@ -16,21 +16,22 @@ Words starting with `,` are
 Comments in TAL are written `( ... )` and support nesting. Eg. `( () )` is a valid comment. `( ( )` is not.
 TAL does not have a way to "close all start comments" like Java and some other languages do.
 
-## Includes
+## Literals
-TAL files can include other files by writing `~<filename>`.
-For instance the `uxnasm.tal` file writes `~projects/library/string.tal` to include implementations of string functions.
-As with other preprocessor and assembler languages, TAL does not support namespacing, renaming or selective importing.
 
-- All included code is assembled at the point where it is included.
+Hex constants are written `#[0-9a-f]{1,4}`.
-- TAL does not support multiple definition or idempotent includes, and will error on repeated or recursive inclusion.
+For instance `#00` or `#ffff` would be valid hex constants, the first assembling to one word, the second to two.
+One and two byte literal quantities may also be provided without the `#` prefix.
 
-## Macros
+Words may be captured as ASCII formatted strings.
-Macros are sequences of instructions which may be repeated.
+Such strings are written `"<word>`.
-Macros are defined by writing `%macro-name { ... }`.
+For instance `"foo` would cause the bytes `#66 #6f #6f #00` to be literally inserted into the memory image.
-The canonical UXNASM does not allow macros to exceed 64 words in size.
 
-When macros are invoked by using the macro-name as a bare word, the contents of the macro will be inserted.
+As `"` notation cannot capture whitespace, the `#20` (space), `#0a` (newline) and `#09` (tab) character constants are common.
-Sub-macro references are supported and will be expanded with no recursion guards or limit.
+
+## Brackets
+
+`[` and `]` are treated as whitespace, and may be used for visual grouping.
+While they have semantics in traditional Forth, they have no semantics in TAL.
 
 ## Padding
 
@@ -49,6 +50,28 @@ Defining a top-level word establishes a scope within which sub-labels may be def
 `&bar` following `@foo` would create the label `foo/bar`.
 This can be used to create semantic tables.
 
+### Example - the system device
+
+```tal
+|00 @System     &vector $2 &wst      $1 &rst    $1 &eaddr  $2 &ecode  $1 &pad     $1 &r       $2 &g      $2 &b     $2 &debug  $1 &halt $1
+```
+
+`|00` aligns the assembler to `0x0000`.
+
+This line of code creates the following symbols:
+- `System` at `0x0000`
+- `Sytstem/vector` at `0x0000`
+- `System/wst` at `0x0002`, shifted from `System/vector` by the `$2`
+- `System/rst` at `0x0003`
+- `System/eaddr` at `0x0004`
+- `System/ecode` at `0x0005`
+- `System/pad` at `0x0006`
+- `System/r` at `0x0008`
+- `System/g` at `0x000a`
+- `System/b` at `0x000c`
+- `System/debug` at `0x000e`
+- `System/halt` at `0x000f`
+
 ## References
 
 Labels may be referenced in one of seven ways:
@@ -66,7 +89,7 @@ Absolute labels are double quantities.
 Relative labels are single signed byte quantities with a ±127 range.
 
 The zero page (`#00XX`) is used for system devices, along other things.
-It's common to see labels such as `.Mouse/state`, being a reference to the address `#0096`.
+It's common to see labels such as `.System/vector`, being a reference to the address `#0000` packed into just `#00`
 However as UXN has a special `LDZ` operation for loading from the zero page, this address can be specified as simply `#96` to save a byte.
 As the last device is mapped to `#CX`, it is common to see `#DX`, `#EX` and `#FX` used for program-global variables for ease of access.
 
@@ -77,18 +100,18 @@ For bytecode compactness, UXN programs tend to use computed rather than absolute
 
 The difference between single and double word references is critical, because the `LDR` instruction is a computed relative load, whereas `LDA` is an absolute short address load.
 
-## Brackets
+## Includes
-`[` and `]` are treated as whitespace, and may be used for visual grouping.
+TAL files can include other files by writing `~<filename>`.
-While they have semantics in traditional Forth, they have no semantics in TAL.
+For instance the `uxnasm.tal` file writes `~projects/library/string.tal` to include implementations of string functions.
+As with other preprocessor and assembler languages, TAL does not support namespacing, renaming or selective importing.
 
-## Literals
+- All included code is assembled at the point where it is included.
+- TAL does not support multiple definition or idempotent includes, and will error on repeated or recursive inclusion.
 
-Hex constants are written `#[0-9a-f]{1,4}`.
+## Macros
-For instance `#00` or `#ffff` would be valid hex constants, the first assembling to one word, the second to two.
+Macros are sequences of instructions which may be repeated.
-One and two byte literal quantities may also be provided without the `#` prefix.
+Macros are defined by writing `%macro-name { ... }`.
+The canonical UXNASM does not allow macros to exceed 64 words in size.
 
-Words may be captured as ASCII formatted strings.
+When macros are invoked by using the macro-name as a bare word, the contents of the macro will be inserted.
-Such strings are written `"<word>`.
+Sub-macro references are supported and will be expanded with no recursion guards or limit.
-For instance `"foo` would cause the bytes `#66 #6f #6f #00` to be literally inserted into the memory image.
-
-As `"` notation cannot capture whitespace, the `#20` (space), `#0a` (newline) and `#09` (tab) character constants are common.