Feat: continue to improve documentation

docs/forth/about_forth.md

@@ -1,46 +1,47 @@
 # About Forth
 
-Forth is a _stack-based_ programming language created by Charles H. Moore in the early 1970s. It was designed with simplicity, directness, and interactive exploration in mind. Forth has been used for many years to do scientific work and program embedded systems: it was used to control telescopes and was running on some devices used in space missions among other things. Forth quickly evolved into multiple implementations targetting various computer architectures. None of them really took off and became popular. Nonetheless, the ideas behind Forth continue to garner the interest of many different people in very different (often unrelated) fields. Nowadays, Forth languages are used by hackers and artists for their peculiarity. Forth is simple, direct and beautiful to implement. Forth is an elegant and minimal language to learn. It is easy to understand, to extend and to apply to a specific task. The Forth we use in Cagire is specialized in making live music. We think of it as a DSL: a _Domain Specific Language_. 
+Forth is a _stack-based_ programming language created by Charles H. Moore in the early 1970s. It was designed with simplicity, directness, and interactive exploration in mind. Forth has been used for scientific work and embedded systems: it controlled telescopes and even ran on hardware aboard space missions. It evolved into many implementations targeting various architectures, but none of them really caught on. Nonetheless, the ideas behind Forth continue to attract people from very different, often unrelated fields. Today, Forth languages are used by hackers and artists for their unconventional nature. Forth is simple, direct, and beautiful to implement. Forth is an elegant, minimal language, easy to understand, extend, and tailor to a specific task. The Forth we use in Cagire is specialized in making live music. It is used as a DSL: a _Domain Specific Language_. 
 
 ## Why Forth?
 
-Most programming languages nowadays use a complex syntax made of `variables`, `expressions` and `statements` like `x = 3 + 4`. Forth works differently. It is way more simple than that, has almost no syntax and performs computations in a quite unique way. You push values onto a `stack` and apply `words` that transform them:
+Most programming languages rely on a complex syntax of `variables`, `expressions` and `statements` like `x = 3 + 4` or `do_something(()=>bob(4))`. Forth works differently. It has almost no syntax at all. Instead, you push values onto a `stack` and apply `words` that transform them:
 
 ```forth
 3 4 +
 ```
 
-This program leaves the number `7` on the stack. There are no variables, no parentheses, no syntax to remember. You just end up with words and numbers separated by spaces. For live coding music, this directness is quite exciting. All you do is think in terms of transformations and add things to the stack: take a note, shift it up, add reverb, play it.
+The program above leaves the number `7` on the stack. There are no variables, no parentheses, no syntax to remember. You just end up with words and numbers separated by spaces. For live coding music, this directness is quite exciting. All you do is think in terms of transformations and add things to the stack: take a note, shift it up, add reverb, play it.
 
 ## The Stack
 
 The stack is where values live. When you type a number, it goes on the stack. When you type a word, it usually takes values off and puts new ones back.
 
 ```forth
-3       ( stack: 3 )
-4       ( stack: 3 4 )
-+       ( stack: 7 )
+3 ;; stack: 3
+4 ;; stack: 3 4
++ ;; stack: 7
 ```
 
-The stack is `last-in, first-out`. The most recent value is always on top. This means that its often better to read Forth programs from the end to the beginning: from right to left, from the bottom to the top.
+The stack is `last-in, first-out`. The most recent value is always on top. This means that it's often better to read Forth programs from right to left, bottom to top.
 
 ## Words
 
 Everything in Forth is either a `number` or a `word`. Words are like functions but conceptually simpler. They have no arguments or return values in the traditional sense. They just manipulate the stack directly.
 
 ```forth
-dup     ( duplicate the top value )
-drop    ( discard the top value )
-swap    ( swap the top two values )
+dup ;; duplicate the top value
+drop ;; discard the top value
+swap ;; swap the top two values
 ```
 
 Words compose naturally on the stack. To double a number:
 
 ```forth
-3 dup +   ( 3 3 +)
+;; 3 3 +
+3 dup + 
 ```
 
-There are a lot of words in a Forth and thus, Cagire has a `Dictionary` embedded directly into the application. You can also create your own words. They will work just like the already existing words. There are good reasons to create new words on-the-fly:
+Forth has a large vocabulary, so Cagire includes a `Dictionary` directly in the application. You can also create your own words. They will work just like existing words. The only difference is that these words will not be included in the dictionary. There are good reasons to create new words on-the-fly:
 
 - To make synth definitions.
 - To abstract _some piece of code_ that you use frequently.
@@ -48,32 +49,32 @@ There are a lot of words in a Forth and thus, Cagire has a `Dictionary` embedded
 
 ## Values
 
-Four types of values can live on the stack:
+Four basic types of values can live on the stack:
 
 - **Integers**: `42`, `-7`, `0`
 - **Floats**: `0.5`, `3.14`, `-1.0`
 - **Strings**: `"kick"`, `"hello"`
 - **Quotations**: `{ dup + }` (code as data)
 
-Quotations are special. They let you pass code around as a value. This is how conditionals and loops work. Think nothing of it for now, you will learn more about how to use it later on.
+Floats can omit the leading zero: `.25` is the same as `0.25`, and `-.5` is `-0.5`.
 
-## Stack Notation
+Parentheses are ignored by the parser. You can use them freely for visual grouping without affecting execution:
 
-Documentation uses a notation to show what words do:
-
-```
-( before -- after )
+```forth
+(c4 note) (0.5 gain) "sine" s .
 ```
 
-For example, `+` has the signature `( a b -- sum )`. It takes two values and leaves one.
+Quotations are special. They let you pass code around as a value. This is how conditionals and loops work. Don't worry about them for now — you'll learn how to use them later.
+
+Any word that is not recognized as a built-in or a user definition becomes a string on the stack. This means `kick s` and `"kick" s` are equivalent. You only need quotes when the string contains spaces or when it conflicts with an existing word name.
 
 ## The Command Register
 
-Traditional Forth programs print text to a terminal. Cagire's Forth builds sound commands instead. This happens through an invisible accumulator called the command register. The command register has two parts:
+Traditional Forth programs print text to a terminal. Cagire's Forth builds sound commands instead. This happens through an internal accumulator called the command register. The command register has two parts:
 - a **sound name** (what instrument to play)
 - a list of **parameters** (how to play it)
 
-Three types of words interact with it:
+Three kinds of words interact with it:
 
 ```forth
 kick sound      ;; sets the sound name
@@ -108,8 +109,3 @@ The order of parameters does not matter. You can even emit multiple times in a s
 ```
 
 This is useful when conditionals might cancel a sound before it emits.
-
-## More details
-
-- Each step has its own stack and independant runtime.
-- Word definitions and variable definitions are shared by all steps.