Update documentation

1 files changed, 34 insertions, 0 deletions

diff --git a/documentation/parsing.md b/documentation/parsing.md
new file mode 100644
index 0000000..43d5028
--- /dev/null
+++ b/documentation/parsing.md
@@ -0,0 +1,34 @@
+# Reading QSP
+
+The QSP language was not designed to be processed in this way. There are
+ambivalent cases that cannot be represented cleanly via a grammar.
+
+An example is the `!` character, which can indicate the start of a comment, or
+an inequality operator.
+
+Another example is the `*` character, which can be the first character of an
+instruction, or a multiplication operation. For example:
+
+- `*clr()` is a valid instruction, but `5 *clr()` is not.
+- `*rnd()` is an invalid instruction, but `5 *rnd()` is valid.
+(As a bonus `rnd* rnd()` is also valid…)
+
+What's more, the language is very permissive, allowing for structures that are
+actually incorrect.
+
+For example:
+
+```
+if $PARGS[0] = 'Day1':
+end
+
+elseif $ARGS[0] = 'Week1':
+end
+```
+
+As a result, the application may pick up errors on particular cases that are
+nonetheless valid. I've tried to respect the syntax of the QSP language as much
+as possible, but on borderline cases, I consider that being stricter is
+positive.
+
+