From c0951fc9d44433ad3ebbd541d6a9a64a6cec61c8 Mon Sep 17 00:00:00 2001
From: charles <charles@tipsy.codes>
Date: Thu, 12 Mar 2026 20:59:11 -0700
Subject: [PATCH] fix: readme instruction

---
 README.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/README.md b/README.md
index cdadbb3..e2f5948 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,76 @@ An implementation of the RPG language from IBM.
 
 Language reference: https://www.ibm.com/docs/en/i/7.5.0?topic=introduction-overview-rpg-iv-programming-language
 
+## Usage
+
+### Building
+
+```rust-langrpg/README.md
+cargo build --release
+```
+
+### Running
+
+The compiler ships as a standalone binary that loads the embedded BNF grammar, builds a parser, and runs a suite of RPG IV snippet examples to demonstrate the grammar in action:
+
+```rust-langrpg/README.md
+cargo run --bin demo
+```
+
+You will see output similar to:
+
+```rust-langrpg/README.md
+=== RPG IV Free-Format Parser ===
+
+[grammar] Loaded successfully.
+[parser]  Built successfully (all non-terminals resolved).
+
+=== Parsing Examples ===
+
+  ┌─ simple identifier (identifier) ─────────────────────
+  │  source : "myVar"
+  │  result : OK
+  └──────────────────────────────────────────────
+...
+=== Summary ===
+  total   : 42
+  matched : 42
+  failed  : 0
+
+All examples parsed successfully.
+```
+
+### Hello World in RPG IV
+
+The following is a complete Hello World program written in RPG IV free-format syntax, as understood by this parser:
+
+hello.rpg:
+
+```rust-langrpg/README.md
+CTL-OPT DFTACTGRP(*NO);
+
+DCL-S greeting CHAR(25) INZ('Hello, World!');
+
+DCL-PROC main EXPORT;
+  DSPLY greeting;
+  RETURN;
+END-PROC;
+```
+
+Breaking it down:
+
+- `CTL-OPT DFTACTGRP(*NO);` — control option spec declaring the program does not run in the default activation group
+- `DCL-S greeting CHAR(25) INZ('Hello, World!');` — standalone variable declaration: a 25-character field initialised to `'Hello, World!'`
+- `DCL-PROC main EXPORT; ... END-PROC;` — a procedure named `main`, exported so it can be called as a program entry point
+- `DSPLY greeting;` — displays the value of `greeting` to the operator message queue
+- `RETURN;` — returns from the procedure
+
+To validate this program, execute the compiler to build the data:
+
+```sh
+cargo run --release -- -o main hello.rpg
+```
+
 ## Implementation
 
 The RPG language was converted to an BNF, and fed into the bnf crate (https://docs.rs/bnf/latest/bnf/).