improve instructions catalog

.gitignore

@@ -0,0 +1 @@
+node_modules

docs/_command-template.md

@@ -0,0 +1,26 @@
+# Command documentation template
+
+Use this template to create or standardize a command/function page in the documentation. Every command page must follow the structure below and include one representative, runnable example for a generic MSX.
+
+Description
+- Provide a concise explanation of what the command or function does and where it is typically used.
+
+Syntax
+> Show the formal syntax and list the parameters with short descriptions.
+
+Example program
+- Add a single, clear example program that can be executed on a generic MSX. Include a link to the example `.BAS` file stored in the `examples/` directory.
+
+```basic
+10 REM Example program for COMMAND_NAME
+20 REM Add your code here
+30 END
+```
+
+Explanation
+- Step-by-step explanation of what the example does and what to expect when running it on a generic MSX.
+
+See also
+- Link to related commands or examples.
+
+[<< Back](./index.md)

docs/chrs.md

@@ -1,13 +1,18 @@
 ### CHR$
-The CHR$ **function** in MSX BASIC is used to convert an ASCII code (a number) into its corresponding character. This function is useful when you need to display special characters or control codes that are not easily typed from the keyboard.
 
-#### Syntax
->CHR$(`number`)
+Description
 
-An integer value between 0 and 255 representing the ASCII code of the character you want to display.
+CHR$ is a function that returns the character corresponding to a numeric code. It is commonly used to display special characters or control codes that cannot be typed directly from the keyboard.
 
-#### Example Program
-The following MSX BASIC program prints all available ASCII characters (from 0 to 255) on the screen:
+Syntax
+
+> CHR$(number)
+
+- `number` — Integer code of the character (typical range 0–255). The function returns a one-character string.
+
+Example program
+
+- Example file: `../examples/CHRS/LIST-ALL-CHARS.BAS`
 
 ```basic
 10 FOR I = 0 TO 255
@@ -16,8 +21,8 @@ The following MSX BASIC program prints all available ASCII characters (from 0 to
 40 END
 ```
 
-This program uses a `FOR` loop to iterate through all ASCII codes from 0 to 255, converting each code to its corresponding character using the `CHR$` function and printing it on the screen. 
+Explanation
 
-The semicolon (;) at the end of the `PRINT` statement ensures that the characters are printed on the same line.
+This program iterates through numeric character codes from 0 to 255 and prints the character returned by `CHR$` for each code. The semicolon after `PRINT` keeps output on the same line. Note that many codes correspond to non-printable control characters and may affect the display or cursor position; the output will vary depending on the MSX text mode and the emulator or hardware.
 
-[<< Back](./index.md)
+[<< Back](./index.md)

docs/circle.md

@@ -0,0 +1,33 @@
+### CIRCLE
+
+Description
+
+`CIRCLE` draws a circle, arc, or ellipse on a graphics screen. It supports radius, optional tracing angles to draw arcs, and an aspect ratio parameter to stretch horizontally or vertically.
+
+Syntax
+
+> CIRCLE [STEP](X,Y), radius [, color [, tracingStart [, tracingEnd [, aspect]]]]
+
+- `X,Y` — Center coordinates.
+- `radius` — Radius of the main axis.
+- `color` — Optional color index.
+- `tracingStart`, `tracingEnd` — Angles in radians (0..2π) to draw partial arcs.
+- `aspect` — Aspect ratio for ellipse drawing.
+
+Example — multiple concentric circles/ellipses
+
+- Example file: `../examples/CIRCLE/CIRCLE-DEMO.BAS`
+
+```basic
+10 SCREEN 2: COLOR 15,1,7: CLS
+20 FOR R = 10 TO 80 STEP 10
+30 CIRCLE (127,95), R, INT(R/10) + 1
+40 NEXT R
+50 GOTO 50
+```
+
+Explanation
+
+This program draws several circles of increasing radius centered at `(127,95)` using different colors. The `aspect` parameter is omitted; on some machines (PAL vs NTSC) the same radius may appear slightly stretched.
+
+[<< Back](./index.md)

docs/close.md

@@ -0,0 +1,30 @@
+### CLOSE
+
+Description
+
+`CLOSE` closes open file handles and releases associated I/O buffers. Without parameters it closes all open files. Closing files ensures data is flushed to the device.
+
+Syntax
+
+> CLOSE [#file1, #file2, ...]
+
+- `#fileN` — File handle(s) previously assigned by `OPEN`. When omitted all opened files are closed.
+
+Example
+
+```basic
+10 MAXFILES = 2
+20 OPEN "CAS:DEMO" FOR INPUT AS #1
+30 OPEN "LPT:" FOR OUTPUT AS #2
+40 INPUT #1, A$
+50 PRINT #2, A$
+60 CLOSE #2
+70 CLOSE #1
+80 END
+```
+
+Explanation
+
+This snippet demonstrates opening two files and closing them explicitly when finished. Closing files prevents data loss and frees file slots for new `OPEN` operations.
+
+[<< Back](./index.md)

docs/cls.md

@@ -0,0 +1,26 @@
+### CLS
+
+Description
+
+`CLS` clears the current screen and resets the text cursor position to the top-left (implementation-dependent coordinates). It does not clear program variables.
+
+Syntax
+
+> CLS
+
+Example
+
+- Example file: `../examples/CLS/CLS-COLOR.BAS`
+
+```basic
+10 CLS
+20 COLOR 7,0,1
+30 PRINT "Screen cleared and colors set"
+40 END
+```
+
+Explanation
+
+`CLS` wipes the text/graphics display region; follow with `COLOR` and `PRINT` to update the screen contents.
+
+[<< Back](./index.md)

docs/color.md

@@ -0,0 +1,29 @@
+### COLOR
+
+Description
+
+`COLOR` configures foreground (text), background and border colors used by subsequent text and some graphics commands. Colors are specified by numeric indices (implementation palette depends on MSX generation and video mode).
+
+Syntax
+
+> COLOR foreground[, background[, border]]
+
+- `foreground` — Color index for text/plot color.
+- `background` — Optional background color index.
+- `border` — Optional border color index.
+
+Example
+
+- Example file: `../examples/COLOR/COLOR-DEMO.BAS`
+
+```basic
+10 COLOR 7,0,1
+20 PRINT "White text, black background, blue border"
+30 END
+```
+
+Explanation
+
+The example sets the text color to 7 (white), background to 0 (black) and the screen border to 1 (blue). The actual color mapping may vary by machine and mode.
+
+[<< Back](./index.md)

docs/dim.md

@@ -1,14 +1,20 @@
 ### DIM
 
-The `DIM` command in MSX BASIC is used to declare and allocate memory for arrays. Arrays are used to store multiple values in a single variable, which can be accessed using an index.
+Description
 
-#### Syntax
->DIM array_name(`size`)
+`DIM` reserves memory for one or more arrays and initializes the array variables. Arrays allow storing a collection of values under a single name and accessing each element by index.
 
-- *array_name*: The name of the array.
-- *size*: The number of elements in the array.
+Syntax
+
+> DIM array_name(size)
+
+- `array_name` — Name of the array.
+- `size` — Upper bound for the array index. For multi-dimensional arrays use multiple bounds separated by commas, e.g. `DIM A(n, m)`.
+
+Example program
+
+- Example file: `../examples/DIM/SINGLE-DIM.BAS`
 
-#### Single-Dimensional Array
 ```basic
 10 DIM A(5)
 20 FOR I = 1 TO 5
@@ -21,25 +27,8 @@ The `DIM` command in MSX BASIC is used to declare and allocate memory for arrays
 90 END
 ```
 
-This example declares a single-dimensional array A with 5 elements, reads values into the array, and prints them.
-
-#### Multi-Dimensional Array
-```basic
-10 DIM B(3, 3)
-20 FOR I = 1 TO 3
-30 FOR J = 1 TO 3
-40 READ B(I, J)
-50 NEXT J
-60 NEXT I
-70 FOR I = 1 TO 3
-80 FOR J = 1 TO 3
-90 PRINT "B("; I; ","; J; ") = "; B(I, J)
-100 NEXT J
-110 NEXT I
-120 DATA 1, 2, 3, 4, 5, 6, 7, 8, 9
-130 END
-```
+Explanation
 
-This example declares a two-dimensional array B with 3x3 elements, reads values into the array, and prints them.
+This program declares a one-dimensional array `A` and reads five values into it using `READ` and `DATA`. The second loop prints each element with its index. For multi-dimensional arrays use `DIM` with multiple bounds and access elements with multiple indices, e.g. `B(I, J)`.
 
-[<< Back](./index.md)
+[<< Back](./index.md)

docs/end.md

@@ -0,0 +1,26 @@
+### END
+
+Description
+
+`END` terminates program execution and closes open files. Execution stops and the interpreter returns to the READY prompt.
+
+Syntax
+
+> END
+
+Example
+
+- Example file: `../examples/END/END-DEMO.BAS`
+
+```basic
+10 PRINT "START"
+20 END
+30 PRINT "NEVER REACHED"
+40 END
+```
+
+Explanation
+
+When the interpreter reaches line 20 (`END`) execution stops. Any statements after `END` in the program are not executed.
+
+[<< Back](./index.md)

docs/for-next.md

@@ -1,22 +1,33 @@
 ### FOR / NEXT
-The `FOR / NEXT` loop is used to execute a block of code repeatedly for a defined number of iterations. It automatically manages a counter variable, starting from an initial value, incrementing it by a specified step (default is 1), and stopping when it exceeds the specified limit.  
 
-```basic
-FOR <Variable> = <Start> TO <End> [STEP <Increment>]
-    <Block of code>
-NEXT <Variable>
+Description
 
-```
-- Variable: A counter variable that controls the loop.
-- Start: The initial value of the counter.
-- End: The value at which the loop stops.
-- STEP (optional): Defines the increment (positive or negative) applied to the counter after each iteration. Default is 1.
+`FOR ... NEXT` is a loop structure that repeats a block of statements a fixed number of times. A counter variable advances automatically from a start value to an end value optionally using a step increment.
+
+Syntax
+
+> FOR variable = start TO end [STEP increment]
+>     statements
+> NEXT [variable]
 
+- `variable` — Loop counter variable.
+- `start` — Initial value for the counter.
+- `end` — Final value for the counter; loop stops when the counter passes this value.
+- `STEP` (optional) — Signed increment applied each iteration. Default is `1`.
+
+Example program
+
+- Example file: `../examples/FOR-NEXT/LOOP.BAS`
 
 ```basic
-10 FOR I = 1 TO 5
+10 FOR I = 1 TO 50
 20 PRINT I
 30 NEXT I
+40 END
 ```
 
-[<< Back](./index.md)
+Explanation
+
+This example prints the numbers from 1 to 50. The loop executes the `PRINT` statement 50 times; the counter `I` is incremented automatically by 1 each iteration. To change the increment use `STEP`, e.g. `FOR I = 1 TO 50 STEP 2`.
+
+[<< Back](./index.md)

docs/gosub.md

@@ -1,14 +1,34 @@
 ### GOSUB / RETURN
-The GOSUB command is used to call a subroutine, which is a block of code that can be executed from multiple places in the program. The RETURN command is used to return to the line following the GOSUB call.
 
-```basic
-10 GOSUB 100
-20 PRINT "Back to main program"
-30 END
+Description
+
+`GOSUB` transfers execution to a subroutine located at a specified line number. `RETURN` brings execution back to the statement following the `GOSUB` call. Subroutines help avoid duplicating code and organize functionality.
+
+Syntax
+
+> GOSUB line_number
+> ...
+> RETURN
+
+- `line_number` — The line number where the subroutine starts.
 
-100 PRINT "In subroutine"
-110 RETURN
+Example program
 
+- Example file: `../examples/GOSUB/SURFACE-CALC.BAS`
+
+```basic
+10 PRINT "SURFACE AREA CALCULATOR"
+20 INPUT "INSERT HEIGHT";A
+30 INPUT "INSERT WIDTH";B
+40 GOSUB 70
+50 PRINT "SURFACE AREA IS:";SURFACE
+60 END
+70 SURFACE = A * B
+80 RETURN
 ```
 
-[<< Back](./index.md)
+Explanation
+
+The main program (lines 10–60) reads `A` and `B` from the user and calls the subroutine at line 70 with `GOSUB 70`. The subroutine computes `SURFACE = A * B` and uses `RETURN` to go back to the line after the `GOSUB`. The main program then prints the computed area and ends.
+
+[<< Back](./index.md)

docs/goto.md

@@ -1,12 +1,29 @@
 ### GOTO
 
-The GOTO command is used to jump to a specific line number in the program. This allows for non-linear execution of code, which can be useful for creating loops or conditional statements.
+Description
+
+`GOTO` transfers program control to a specified line number. It can be used to create loops or to jump over sections of code, but excessive use may make programs harder to read and maintain.
+
+Syntax
+
+> GOTO line_number
+
+- `line_number` — The destination line number to continue execution from.
+
+Example program
+
+- Example file: `../examples/GOTO/INFINITE-PRINT.BAS`
 
 ```basic
-10 A=1
+10 A = 1
 20 PRINT A
-30 A=A+1
+30 A = A + 1
 40 GOTO 20
 50 END
 ```
-[<< Back](./index.md)
+
+Explanation
+
+This program demonstrates a simple loop created with `GOTO`. After printing `A`, the program increments it and jumps back to line 20, printing repeatedly. This example creates an infinite loop; on a real MSX you can interrupt the program with the system `STOP` or `BREAK` key (depending on your emulator or hardware).
+
+[<< Back](./index.md)