Merge pull request #138 from tsoding/examples-order

Use the size of the examples as the complexity indicator

Author: rexim

.github/workflows/ci.yml

@@ -75,4 +75,4 @@ jobs:
       - name: Run Tests
         run: |
           make
-          ./build/b -run -t 6502 ./examples/10_hello_world.b ./std/6502.b
+          ./build/b -run -t 6502 ./examples/hello_world.b ./std/6502.b

README.md

@@ -22,7 +22,7 @@ Compiler for the B Programming Language implemented in [Crust](https://github.co
 
 ```console
 $ make
-$ ./build/b -run ./examples/10_hello_world.b
+$ ./build/b -run ./examples/hello_world.b
 ```
 
 ### Uxn
@@ -32,7 +32,7 @@ $ ./build/b -run ./examples/10_hello_world.b
 The compiler supports [Uxn](https://100r.co/site/uxn.html) target. Make sure you have `uxnemu` in your `$PATH` if you want to use `-run` flag.
 
 ```console
-$ ./build/b -t uxn -run ./examples/10_hello_world.b ./std/uxn.b
+$ ./build/b -t uxn -run ./examples/hello_world.b ./std/uxn.b
 ```
 
 Also check out more examples at [./examples/](./examples/).

examples/.gitignore

@@ -2,3 +2,4 @@
 !*/
 !**/*.b
 !.gitignore
+!**/README.md

examples/README.md

@@ -0,0 +1,15 @@
+# Examples
+
+This folder contains examples that are meant to be read by the users of the language to learn and explore the capabilities of the language.
+
+It is recommended to study them in the order of their complexity: from simplest to the most complex. Generally, the size of the file roughly corresponds to its complexity so we recommend to sort the examples by their size and follow that order.
+
+In a Linux console this could be achived by the running command:
+
+```
+$ ls -lS
+```
+
+Where the `-S` flag of the [ls](https://man7.org/linux/man-pages/man1/ls.1.html) utility sorts the files by size, largest first.
+
+In other operating systems and applications please use similar functionality.