improve readme and example of the stdio module

README.md

@@ -449,3 +449,33 @@ such as animations.
 ; 0-left, 1-right, 2-middle
 (sc-mbtn PRESSED BTN)
 ```
+
+## Stdio module
+
+- This module currently defines two global handles: `@stdin` and `@stdout`.
+- You can think of these handles as streams or SFRs (special function registers).
+  To use them, simply load data to or from the handles (e.g. `(ld r0 @stdin)`).
+- They operate over unicode code points, which are a superset of ASCII.
+
+You can use these special handles in almost all instructions:
+
+```
+(cmp @stdin 'y' 
+    (eq? (ld @stdout '1'))
+    (ne? (ld @stdout '0')))
+```
+
+When you compile a program using such handles, you will get a strange looking assembly:
+
+```
+0000 : (ld @0x6372736e00000001 72)
+0001 : (ld @0x6372736e00000001 101)
+0002 : (ld @0x6372736e00000001 108)
+```
+
+These are unique constants assigned to the streams at compile time. They are not meant to be used
+directly, but the value can be obtained by simply leaving out the '@' sign: `(ld r0 stdin)`. 
+That can be useful when these stream handles need to be passed to a function. Obviously this makes
+more sense when there are different kinds of streams available, not just these two default ones.
+
+.

examples/stdio.csn

@@ -6,12 +6,20 @@
 
     (:loop)
     (ld r0 @stdin)
+
+    ; exit by pressing 'q'
+    (cmp r0 'q'
+        (=? (ld @stdout '\n')
+            (halt)))
+
+    ; uppercase ASCII
     (cmp r0 'a' (<? (j :badchar)))
     (cmp r0 'z' (>? (j :badchar)))
-    (sub r0 32) ; to uppercase
+    (sub r0 32)
     (ld @stdout r0)
     (j :loop)
+
     (:badchar)
-    (ld @stdout '🐈')
+    (ld @stdout '🐈') ; show a kitty if not ASCII
     (j :loop)
 )