Put app-common documentation in apps/README.md

apps/README.md

@@ -61,3 +61,38 @@ relevant parts of the app's glue unit in your kernel's glue unit. This is often
 simpler and more efficient. However, if your shell is a big program, it might
 run into zasm's limits. In that case, you'd have to assemble your shell
 separately.
+
+## Common features
+
+The folder `lib/` contains code shared in more than one apps and this has the
+effect that some concepts are exactly the same in many application. They are
+therefore sharing documentation, here.
+
+### Number literals
+
+There are decimal, hexadecimal and binary literals. A "straight" number is
+parsed as a decimal. Hexadecimal literals must be prefixed with `0x` (`0xf4`).
+Binary must be prefixed with `0b` (`0b01100110`).
+
+Decimals and hexadecimal are "flexible". Whether they're written in a byte or
+a word, you don't need to prefix them with zeroes. Watch out for overflow,
+however.
+
+Binary literals are also "flexible" (`0b110` is fine), but can't go over a byte.
+
+There is also the char literal (`'X'`), that is, two quotes with a character in
+the middle. The value of that character is interpreted as-is, without any
+encoding involved. That is, whatever binary code is written in between those
+two quotes, it's what is evaluated. Only a single byte at once can be evaluated
+thus. There is no escaping. `'''` results in `0x27`. You can't express a newline
+this way, it's going to mess with the parser.
+
+### Expressions
+
+An expression is a bunch of literals or symbols assembled by operators. For
+now, only `+`, `-` and `*` operators are supported. No parenthesis yet.
+
+Symbols have a different meaning depending on the application. In zasm, it's
+labels and constants. In basic, it's variables.
+
+Expressions can't contain spaces.

apps/basic/README.md

@@ -49,12 +49,11 @@ by typing a whitespace.
 
 Only 16-bit integers (unsigned for now) are supported in this BASIC. When
 printed, they're printed in decimal form. When expressing number literals, you
-can do so either in decimal (`42`), hexadecimal (`0x2a`), binary (`0b101010`)
+can do so either in multiple forms. . See "Number literals" in `apps/README.md`
-or char ('a', resulting in number 97).
+for details.
 
 Expressions are accepted wherever a number is expected. For example,
-`print 2+3` will print `5`. Expressions can't have whitespace inside them and
+`print 2+3` will print `5`.  See "Expressions" in `apps/README.md`.
-don't support (yet) parentheses. Supported operators are `+`, `-`, `*` and `/`.
 
 Inside a `if` command, "truth" expressions are accepted (`=`, `<`, `>`, `<=`,
 `>=`). A thruth expression that doesn't contain a truth operator evaluates the

apps/zasm/README.md

@@ -28,28 +28,13 @@ The resulting `zasm` binary takes asm code in stdin and spits binary in stdout.
 
 ## Literals
 
-There are decimal, hexadecimal and binary literals. A "straight" number is
+See "Number literals" in `apps/README.md`.
-parsed as a decimal. Hexadecimal literals must be prefixed with `0x` (`0xf4`).
-Binary must be prefixed with `0b` (`0b01100110`).
 
-Decimals and hexadecimal are "flexible". Whether they're written in a byte or
+On top of common literal logic, zasm also has string literals. It's a chain of
-a word, you don't need to prefix them with zeroes. Watch out for overflow,
+characters surrounded by double quotes. Example: `"foo"`. This literal can only
-however.
+be used in the `.db` directive and is equivalent to each character being
-
+single-quoted and separated by commas (`'f', 'o', 'o'`). No null char is
-Binary literals are also "flexible" (`0b110` is fine), but can't go over a byte.
+inserted in the resulting value (unlike what C does).
-
-There is also the char literal (`'X'`), that is, two qutes with a character in
-the middle. The value of that character is interpreted as-is, without any
-encoding involved. That is, whatever binary code is written in between those
-two quotes, it's what is evaluated. Only a single byte at once can be evaluated
-thus. There is no escaping. `'''` results in `0x27`. You can't express a newline
-this way, it's going to mess with the parser.
-
-Then comes our last literal, the string literal. It's a chain of characters
-surrounded by double quotes. Example: `"foo"`. This literal can only be used
-in the `.db` directive and is equivalent to each character being single-quoted
-and separated by commas (`'f', 'o', 'o'`). No null char is inserted in the
-resulting value (unlike what C does).
 
 ## Labels
 
@@ -100,11 +85,7 @@ of declaration order.
 
 ## Expressions
 
-Wherever a constant is expected, an expression can be written. An expression
+See "Expressions" in `apps/README.md`.
-is a bunch of literals or symbols assembled by operators. For now, only `+`, `-`
-and `*` operators are supported. No parenthesis yet.
-
-Expressions can't contain spaces.
 
 ## The Program Counter