tsoding · rexim · Jun 11, 2025 · Jun 11, 2025
diff --git a/.github/workflows/ci.yml b/.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
diff --git a/README.md 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/).

diff --git a/examples/.gitignore b/examples/.gitignore
@@ -2,3 +2,4 @@
 !*/
 !**/*.b
 !.gitignore
+!**/README.md
diff --git a/examples/README.md b/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.
diff --git a/examples/80_brainfck.b → examples/brainfck.b b/examples/80_brainfck.b → examples/brainfck.b
diff --git a/examples/55_da.b → examples/da.b b/examples/55_da.b → examples/da.b
diff --git a/examples/45_duffs_device.b → examples/duffs_device.b b/examples/45_duffs_device.b → examples/duffs_device.b
diff --git a/examples/30_echo.b → examples/echo.b b/examples/30_echo.b → examples/echo.b
diff --git a/examples/40_fib.b → examples/fib.b b/examples/40_fib.b → examples/fib.b
diff --git a/examples/60_game_of_life.b → examples/game_of_life.b b/examples/60_game_of_life.b → examples/game_of_life.b
diff --git a/examples/10_hello_world.b → examples/hello_world.b b/examples/10_hello_world.b → examples/hello_world.b
diff --git a/examples/11_name.b → examples/name.b b/examples/11_name.b → examples/name.b
diff --git a/examples/70_raylib.b → examples/raylib.b b/examples/70_raylib.b → examples/raylib.b
diff --git a/examples/50_rule110.b → examples/rule110.b b/examples/50_rule110.b → examples/rule110.b
diff --git a/examples/20_seq.b → examples/seq.b b/examples/20_seq.b → examples/seq.b
diff --git a/examples/90_snake.b → examples/snake.b b/examples/90_snake.b → examples/snake.b
diff --git a/examples/uxn/README.md b/examples/uxn/README.md
@@ -0,0 +1,3 @@
+# Uxn Examples
+
+Here we keep examples for the [Uxn](https://100r.co/site/uxn.html). They are weird enough to deserve a dedicated folder.
diff --git a/examples/uxn/03_callable_globals.b → examples/uxn/callable_globals.b b/examples/uxn/03_callable_globals.b → examples/uxn/callable_globals.b
diff --git a/examples/uxn/01_hello.b → examples/uxn/hello.b b/examples/uxn/01_hello.b → examples/uxn/hello.b
diff --git a/examples/uxn/02_screen.b → examples/uxn/screen.b b/examples/uxn/02_screen.b → examples/uxn/screen.b
-Original file line number
+Diff line change
@@ Expand Up / @@ -2,3 +2,4 @@ @@
     !*/
     !**/*.b
     !.gitignore
+    !**/README.md
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Uxn Examples

		Here we keep examples for the [Uxn](https://100r.co/site/uxn.html). They are weird enough to deserve a dedicated folder.