Merge pull request 'preparing_for_release' (#6) from preparing_for_release into main

Reviewed-on: http://localhost:44481/katariina-jarvenmaki/Tampiorama/pulls/6

PLAN.md

@@ -35,15 +35,7 @@ tampiorama/
 - A `/usr/local/bin/tampio` wrapper makes it callable as a plain command
 - Goal: `docker compose run --rm tampio` gives a working shell with no manual setup
 
-## Open Questions
-
-- [ ] Docs language: bilingual FI/EN or English only? (bilingual fits the theme)
-- [ ] Scope: curated examples repo, or also a GitHub Pages web showcase / playground?
-- [ ] Hosting: GitHub (likely — standard for open source)
-- [ ] Is Tampio working locally? The libvoikko dependency can be tricky; Docker is the primary path until confirmed.
-
 ## Notes
 
 - Project name: **Tampiorama**
-- libvoikko local setup not yet confirmed working — Docker is the primary path
-- `docs/cheatsheet.md` should cover annotated grammar constructs (Finnish cases → parameter roles) as well as raw syntax
+- `docs/cheatsheet.md` covers annotated grammar constructs (Finnish cases → parameter roles) as well as raw syntax

README.md

@@ -17,14 +17,21 @@ make
 Then serve locally and open in your browser:
 
 ```sh
-python3 -m http.server 9994 --directory examples/basics
+python3 -m http.server 9994 --directory examples
 ```
 
+Open `http://localhost:9994/basics/index.html` for the full example index, or go directly:
+
 | URL | What it does |
 |-----|-------------|
-| `http://localhost:9994/hello.html` | Alerts "Hei maailma!" on load |
-| `http://localhost:9994/factorial.html` | Prompts for n, displays n! |
-| `http://localhost:9994/fibonacci.html` | Prompts for n, displays fib(n) |
+| `http://localhost:9994/basics/hello.html` | Alerts "Hei maailma!" on load |
+| `http://localhost:9994/basics/factorial.html` | Prompts for n, displays n! |
+| `http://localhost:9994/basics/fibonacci.html` | Prompts for n, displays fib(n) |
+| `http://localhost:9994/data-structures/lista.html` | List sorted ascending and descending |
+| `http://localhost:9994/data-structures/vektori.html` | Custom class, Euclidean length of [3,4] = 5 |
+| `http://localhost:9994/strings/merkkijono.html` | String length, concat, trim, split |
+| `http://localhost:9994/async/nappi.html` | Click handlers, mutable counter (visual tally) |
+| `http://localhost:9994/program/kasvutaulukko.html` | Factorial and Fibonacci sequences for n=1..7 |
 
 ## What is Tampio?
 
@@ -46,10 +53,14 @@ See [`docs/cheatsheet.md`](docs/cheatsheet.md) for a map of Finnish grammatical
 | Directory | Contents |
 |-----------|----------|
 | `examples/basics/` | Hello world, factorial, Fibonacci |
-| `examples/data-structures/` | Lists, maps |
-| `examples/strings/` | String manipulation |
-| `examples/async/` | Promise / async usage |
-| `examples/program/` | A small complete program |
+| `examples/data-structures/` | Built-in list operations, custom class |
+| `examples/strings/` | String length, concat, trim, split |
+| `examples/async/` | DOM click handlers, mutable state |
+| `examples/program/` | Capstone combining recursion and list iteration |
+
+## Testing
+
+See [`docs/testing.md`](docs/testing.md) for a step-by-step guide to verifying each example.
 
 ## Local Setup (without Docker)
 

RELEASE.md

@@ -0,0 +1,49 @@
+# Tampiorama v1.0
+
+First release of Tampiorama — an annotated example showcase for [Tampio](https://github.com/fergusq/tampio), a natural-language OOP language that uses Finnish grammar and compiles to JavaScript.
+
+## What's included
+
+### Examples
+
+Eight working, annotated `.itp` programs covering the breadth of the language:
+
+| Example | Demonstrates |
+|---------|-------------|
+| `basics/hello.itp` | Page-load entry point, browser alert |
+| `basics/factorial.itp` | Recursive methods, ternary branching |
+| `basics/fibonacci.itp` | Recursion, predecessor chaining for n-2 |
+| `data-structures/lista.itp` | Built-in list: iteration, sorting |
+| `data-structures/vektori.itp` | Custom class with fields and recursive methods |
+| `strings/merkkijono.itp` | String length, concat, trim, comma-split |
+| `async/nappi.itp` | DOM click handlers, mutable state |
+| `program/kasvutaulukko.itp` | Recursion and list iteration combined |
+
+### Documentation
+
+- `docs/cheatsheet.md` — Finnish grammatical cases mapped to their roles in Tampio syntax, full arithmetic operator reference
+- `docs/vs-javascript.md` — Side-by-side Tampio and JavaScript comparisons
+- `docs/install.md` — Local setup without Docker (Ubuntu/Debian and macOS)
+- `docs/testing.md` — Step-by-step guide for verifying each example
+
+### Infrastructure
+
+- Docker + `docker-compose.yml` — zero-setup environment with libvoikko and fi-x-morpho dictionary included
+- `Makefile` — builds all `.itp` sources to `.html` with `make`
+- Compiled HTML excluded from version control — only Tampio source is committed
+
+## Getting started
+
+```sh
+git clone https://github.com/fergusq/tampiorama.git
+cd tampiorama
+make
+python3 -m http.server 9994 --directory examples
+```
+
+Open `http://localhost:9994/basics/index.html`.
+
+## Notes
+
+- Tampio method names must be single Finnish words that the Voikko morphology library can inflect — this shapes what's possible and is documented throughout the examples
+- The Docker image handles the `libvoikko` and `fi-x-morpho` dictionary setup automatically; see `docs/install.md` for native installation

docs/testing.md

@@ -0,0 +1,97 @@
+# Testing the Examples
+
+## Build and serve
+
+```sh
+make
+python3 -m http.server 9994 --directory examples
+```
+
+Open `http://localhost:9994/basics/index.html` for the full index, or test each example directly below.
+
+---
+
+## basics/hello.html
+
+`http://localhost:9994/basics/hello.html`
+
+- Page loads → browser alert says **Hei maailma!**
+
+---
+
+## basics/factorial.html
+
+`http://localhost:9994/basics/factorial.html`
+
+- Page loads → prompt appears
+- Enter `5` → alert shows **120**
+- Enter `0` → alert shows **1**
+
+---
+
+## basics/fibonacci.html
+
+`http://localhost:9994/basics/fibonacci.html`
+
+- Page loads → prompt appears
+- Enter `10` → alert shows **55**
+- Enter `1` → alert shows **1**
+
+---
+
+## data-structures/lista.html
+
+`http://localhost:9994/data-structures/lista.html`
+
+- Right panel shows the list `[3, 1, 4, 1, 5]`
+- Size: **5**, first element: **3**
+- Ascending sort: **1 1 3 4 5**
+- Descending sort: **5 4 3 1 1**
+
+---
+
+## data-structures/vektori.html
+
+`http://localhost:9994/data-structures/vektori.html`
+
+- Dimension: **2**
+- Sum: **7**
+- Length (3-4-5 triangle): **5**
+
+---
+
+## strings/merkkijono.html
+
+`http://localhost:9994/strings/merkkijono.html`
+
+- Merkkijono: **Hei, Tampio!**
+- Pituus: **12**
+- Yhdistetty: **Hei, Tampio! Vuosi 2026.**
+- Siistitty: **'välilyönnit poistuvat'**
+- Hedelmät: **omena banaani kiivi**
+
+---
+
+## async/nappi.html
+
+`http://localhost:9994/async/nappi.html`
+
+- Two buttons visible: **+1** and **+10**
+- Click **+1** → one `▪` dot appears
+- Click **+10** → ten `▪` dots appear
+- Dots accumulate across clicks
+
+---
+
+## program/kasvutaulukko.html
+
+`http://localhost:9994/program/kasvutaulukko.html`
+
+- **Kertoma (n!)** section shows: `1 1 2 6 24 120 720`
+- **Fibonacci-kani (fib(n))** section shows: `1 1 2 3 5 8 13`
+
+---
+
+## Checking for errors
+
+Open browser DevTools (`F12` → Console) on any page and verify no red errors appear. The only expected output is from the examples themselves.

examples/async/nappi.itp

@@ -0,0 +1,29 @@
+# Nappi — DOM Events and State in Tampio
+#
+# Tampio handles async interactions through DOM event handlers.
+# The key pattern is "X:tä painettaessa käyköön niin, että ..."
+# which attaches a click handler to a button element.
+#
+# State is stored in a "muuttuja" (variable object with an "arvo" field).
+# "kasvatetaan yhdellä" increments the stored value in place.
+#
+# DOM utilities:
+#   etsii elementin nimellä "id" tuloksenaan X  = document.getElementById
+#   kirjoitetaan koodi "html"                    = element.innerHTML += (append)
+#   pyyhitään                                    = element.innerHTML = ""
+
+# Global counter — persists across button clicks
+Olkoon kiva laskuri uusi muuttuja, jonka arvo on nolla.
+
+Kun nykyinen sivu avautuu,
+	nykyinen sivu etsii elementin nimellä "output" tuloksenaan kiva alue,
+	kivalle alueelle kirjoitetaan koodi "<p><button id='natti'>+1</button> <button id='hieno'>+10</button></p><p id='tally'></p>",
+	nykyinen sivu etsii elementin nimellä "natti" tuloksenaan nätti nappi,
+	nykyinen sivu etsii elementin nimellä "hieno" tuloksenaan hieno nappi,
+	nykyinen sivu etsii elementin nimellä "tally" tuloksenaan kaunis alue,
+	nättiä nappia painettaessa käyköön niin, että
+			kivan laskurin arvoa kasvatetaan yhdellä
+		ja	kauniille alueelle kirjoitetaan koodi "▪ "
+ja	hienoa nappia painettaessa käyköön niin, että
+			kivan laskurin arvoa kasvatetaan kymmenellä
+		ja	kauniille alueelle kirjoitetaan koodi "▪▪▪▪▪▪▪▪▪▪ ".

examples/basics/index.itp

@@ -26,9 +26,29 @@
 # Addition uses illative case: lisättynä kaniin
 # n-2 computed by chaining: edeltäjän edeltäjä
 
+# Lista — List Operations
+#
+# Built-in lista type: size, first element, iteration,
+# ascending and descending sort.
+
+# Vektori — Custom Class
+#
+# User-defined class with fields and recursive methods.
+# Euclidean length of vector [3,4] = 5.
+
+# Merkkijono — Strings
+#
+# Length, concatenation, trim, and comma-split.
+
+# Nappi — DOM Events
+#
+# Click handlers with "X:tä painettaessa käyköön niin, että".
+# Mutable counter state persists across button clicks.
+
 Kun nykyinen sivu avautuu,
 	nykyinen sivu näyttää tekstin "<h1>Tampiorama</h1>",
 	nykyinen sivu näyttää tekstin "<p>Annotated examples for <a href='https://github.com/fergusq/tampio'>Tampio</a>, a natural-language OOP language using Finnish grammar that compiles to JavaScript.</p>",
+	nykyinen sivu näyttää tekstin "<h2>Basics</h2>",
 	nykyinen sivu näyttää tekstin "<h3><a href='hello.html'>Hei maailma →</a></h3>",
 	nykyinen sivu näyttää tekstin "<p>Hello world. Page-load entry point, browser alert.</p>",
 	nykyinen sivu näyttää tekstin "<p><em>Open the page — it will alert 'Hei maailma!' immediately.</em></p>",
@@ -36,5 +56,24 @@ Kun nykyinen sivu avautuu,
 	nykyinen sivu näyttää tekstin "<p>Recursive factorial. Ternary branching, adessive multiplication.</p>",
 	nykyinen sivu näyttää tekstin "<p><em>Open the page — enter a number when prompted, e.g. 5, and see 120.</em></p>",
 	nykyinen sivu näyttää tekstin "<h3><a href='fibonacci.html'>Fibonacci-kani →</a></h3>",
-	nykyinen sivu näyttää tekstin "<p>Recursive Fibonacci. Illative addition, predecessor chaining.</p>"
-ja	nykyinen sivu näyttää tekstin "<p><em>Open the page — enter a number when prompted, e.g. 10, and see 55.</em></p>".
+	nykyinen sivu näyttää tekstin "<p>Recursive Fibonacci. Illative addition, predecessor chaining.</p>",
+	nykyinen sivu näyttää tekstin "<p><em>Open the page — enter a number when prompted, e.g. 10, and see 55.</em></p>",
+	nykyinen sivu näyttää tekstin "<h2>Data Structures</h2>",
+	nykyinen sivu näyttää tekstin "<h3><a href='../data-structures/lista.html'>Lista →</a></h3>",
+	nykyinen sivu näyttää tekstin "<p>Built-in list: size, first element, ascending and descending sort.</p>",
+	nykyinen sivu näyttää tekstin "<p><em>Open the page — see the list [3,1,4,1,5] sorted both ways.</em></p>",
+	nykyinen sivu näyttää tekstin "<h3><a href='../data-structures/vektori.html'>Vektori →</a></h3>",
+	nykyinen sivu näyttää tekstin "<p>Custom class with fields and recursive methods. Euclidean length of [3,4] = 5.</p>",
+	nykyinen sivu näyttää tekstin "<p><em>Open the page — see dimension, sum, and Euclidean length of vector [3,4].</em></p>",
+	nykyinen sivu näyttää tekstin "<h2>Strings</h2>",
+	nykyinen sivu näyttää tekstin "<h3><a href='../strings/merkkijono.html'>Merkkijono →</a></h3>",
+	nykyinen sivu näyttää tekstin "<p>String length, concatenation, trim, and comma-split iteration.</p>",
+	nykyinen sivu näyttää tekstin "<p><em>Open the page — see string ops applied to 'Hei, Tampio!'.</em></p>",
+	nykyinen sivu näyttää tekstin "<h2>Async / Events</h2>",
+	nykyinen sivu näyttää tekstin "<h3><a href='../async/nappi.html'>Nappi →</a></h3>",
+	nykyinen sivu näyttää tekstin "<p>DOM click handlers. Mutable counter state persists across button clicks.</p>",
+	nykyinen sivu näyttää tekstin "<p><em>Open the page — click +1 or +10 and watch the counter update.</em></p>",
+	nykyinen sivu näyttää tekstin "<h2>Program</h2>",
+	nykyinen sivu näyttää tekstin "<h3><a href='../program/kasvutaulukko.html'>Kasvutaulukko →</a></h3>",
+	nykyinen sivu näyttää tekstin "<p>Capstone: recursive functions, list iteration, and a click handler together.</p>"
+ja	nykyinen sivu näyttää tekstin "<p><em>Open the page — see factorial and Fibonacci for n=1..7, then enter any n for both values.</em></p>".

examples/program/kasvutaulukko.itp

@@ -0,0 +1,45 @@
+# Kasvutaulukko — Growth Comparison
+#
+# Combines recursive methods, list iteration, and a click handler
+# in a single program.
+#
+# Page load: computes factorial and Fibonacci for n = 1..7 by
+# iterating the same lista twice — once with kertoma, once with kani.
+#
+# Button: prompts for any n, then shows its factorial and Fibonacci
+# as two sequential alerts.
+#
+# Concepts in use:
+#   kertoma        — recursive factorial  (from basics/factorial.itp)
+#   kani           — recursive Fibonacci  (from basics/fibonacci.itp)
+#   lista          — built-in list type   (from data-structures/lista.itp)
+#   jokainen alkio — forEach iterator     (from data-structures/lista.itp)
+#   käyköön niin, että — click handler   (from async/nappi.itp)
+
+# --- Recursive definitions ---
+
+Pienen luvun kertoma on
+	riippuen siitä, onko se pienempi tai yhtä suuri kuin yksi,
+	joko yksi
+	tai pieni luku kerrottuna pienen luvun edeltäjän kertomalla.
+
+Luvun edeltäjä on se vähennettynä yhdellä.
+
+Pienen luvun kani on
+	riippuen siitä, onko se pienempi tai yhtä suuri kuin yksi,
+	joko pieni luku
+	tai pienen luvun edeltäjän kani lisättynä pienen luvun edeltäjän edeltäjän kaniin.
+
+# --- Data ---
+
+# n = 1 .. 7
+Olkoon kiva lista uusi lista, jonka alkioita ovat yksi, kaksi, kolme, neljä, viisi, kuusi ja seitsemän eikä muuta.
+
+# --- Page ---
+
+Kun nykyinen sivu avautuu,
+	nykyinen sivu näyttää tekstin "<h2>Kertoma (n!)</h2><p>",
+	nykyinen sivu näyttää kivan listan jokaisen alkion kertoman,
+	nykyinen sivu näyttää tekstin "</p><h2>Fibonacci-kani (fib(n))</h2><p>",
+	nykyinen sivu näyttää kivan listan jokaisen alkion kanin
+ja	nykyinen sivu näyttää tekstin "</p>".

examples/strings/merkkijono.itp

@@ -13,7 +13,7 @@
 
 # Variables must be adjective + noun
 Olkoon mukava merkkijono teksti "Hei, Tampio!".
-Olkoon pitkä merkkijono teksti "omena,banaani,kiivi".
+Olkoon pitkä merkkijono teksti "omena, banaani, kiivi".
 Olkoon ylimääräinen merkkijono teksti "   välilyönnit poistuvat   ".
 
 Kun nykyinen sivu avautuu,
@@ -24,7 +24,7 @@ Kun nykyinen sivu avautuu,
 	nykyinen sivu näyttää tekstin "</p><p>Yhdistetty: ",
 	nykyinen sivu näyttää mukavan merkkijonon yhdistettynä tekstiin " Vuosi 2026.",
 	nykyinen sivu näyttää tekstin "</p><p>Siistitty: '",
-	nykyinen sivu näyttää ylimääräinen merkkijono siistittynä,
-	nykyinen sivu näyttää tekstin "'</p><p>Hedelmät (pilkulla erotettu): ",
+	nykyinen sivu näyttää ylimääräisen merkkijonon siistittynä,
+	nykyinen sivu näyttää tekstin "'</p><p>Hedelmät: ",
 	nykyinen sivu näyttää pitkän merkkijonon jokaisen kentän
 ja	nykyinen sivu näyttää tekstin "</p>".