README - its developing...

README.md

@@ -1,33 +1,52 @@
 # Orca-Workshop
 
+Orca is an esoteric programming language and live editor designed to quickly create procedural sequencers.   
+Orca is one of the inventions of Devine Lu Linvega of the small artist collective 'Hundred Rabbits'.
+
+In this workshop we will:
+
+1. Look at a few orca demos to get an impression
+2. Get an orca setup running on your machine
+3. Get a very quick language overview
+4. Play through some tutorials together
+5. Get hooked and get lost in the rabbithole of orca
+
+Please find a collection of orca resources at the end of this document.
+
 ## Installation
 
 ### Orca
 
 There are many implementations of Orca.   
-The ones that work for this workshop are:
+The ones that work well for this workshop are:
 
-* JS/electron: https://github.com/hundredrabbits/Orca
+* Easy setup: electron/js
-* ANSI-C: https://github.com/hundredrabbits/Orca-c
+* Advanced setup: ANSI-C implementation
 
 #### Easy setup
 
 The quickest way to get started on any platform is to just use the 'fancy' electron framework version. I recommend doing that for the workshop, to avoid the "install-party" effect.
+Download and run the binary release. The source link is just for your reference.
 
 * Binary release: https://hundredrabbits.itch.io/orca
+* Source/Docs: https://github.com/hundredrabbits/Orca
 
 #### Advanced Setup
 
-My favourite setup though, is running the ANSI-C version in [Cool-Retro-Term](https://github.com/Swordfish90/cool-retro-term)  
+My favourite setup though, is running the ANSI-C version in [Cool-Retro-Term](https://github.com/Swordfish90/cool-retro-term).  
-Orca AND Cool-Retro-Term are available in many package manager, have a look in yours. Maybe you are lucky...
+Orca AND Cool-Retro-Term are available in many package managers, have a look in yours. Maybe you are lucky...   
+Of course you can run this version of orca in any terminal.
+
+* Source/Docs: https://github.com/hundredrabbits/Orca-c
 
 ### Pilot
 
-Orca cant make any sounds, it can only generate MIDI, OSC or UDP output.
+Orca cant make any sounds on its own, it can only generate MIDI, OSC or UDP output.  
-Pilot is a 'companion' program (from hundredrabbits as well) that is a fun little synthesizer and is very easy to use with orca over UDP.
+Pilot is a 'companion' program (from hundredrabbits as well) that is a fun little synthesizer and is very easy to use with orca over UDP.   
+Download and run the binary release. The source link is just for your reference.
 
-* Github/Docs: https://github.com/hundredrabbits/Pilot
 * Binary release: https://hundredrabbits.itch.io/pilot
+* Source/Docs: https://github.com/hundredrabbits/Pilot
 
 ## Language Quick Overview
 
@@ -39,22 +58,28 @@ Pilot is a 'companion' program (from hundredrabbits as well) that is a fun littl
 * Data is just Base36 numbers '0-9' and 'a-z'
 * I/O: no I just O. MIDI/OSC/UDP
 
-
 # Tutorials
 
-## Tutorial: Bangs and Sounds
+## Tutorial 1: First Bleeps
+
+In this tutorial we will only learn 2 of the 26 operators, and we will already be making noise.   
+Isn't that great?
+
+Have a look into the directory `tutorials/1_first_bleeps/`.
+There is an orca program for each chapter.
 
 ### 1. Bangs
 
+The 'bang' is the trigger that activates lower-case operators.   
+There is technically only one operator that directly generates a bang. Its the operator `D`.
+
+* `D` - Delay, bang periodically ()
+
+### 2. First Bleeps
+
 Operators you learn in this chapter:
 
-* 'D' - Delay, bang periodically
+* `;` - Send UDP packet (- / data)
-*
-
-
-### 2. Sounds
-Operators you learn in this chapter:
-* `;` - UDP
 
 for synthesizing the actual waves we are using 'Pilot', a soft-synth which we control with UDP packets.
 So, the commands we send using the UDP output operator are actually Pilot commands, not orca.
@@ -63,6 +88,7 @@ Pilot commands are 3-5 'bytes' long, where the first 3 are required.
 The format is: `CH` `OCT` `NOTE` [`VOL`] [`DECAY`]
 
 Where:
+
 * `CH` - Channels 1-f exist, they all sound different (and they are monophonic)
 * `OCT` - Around 8 octaves should definitely exist
 * `NOTE` - Note names where Upper-case are white keys and Lower-case are Black-keys
@@ -74,35 +100,80 @@ Example:
 
 ### Putting It All Together
 
+## Tutorial 2: Scopehero
 
-## Tutorial: Flying East Scope
+This is a very empowering tutorial with its 13 operators covered.
+Have a look into the directory `tutorials/2_scopehero/`.
+There is an orca program for each chapter.
 
 ### 1. Arithmetic
 
-Operators you learn in this chapter:
+In this chapter you learn (almost) all the operators to generate and manipulate numbers:
 
 * `C` - Count (speed / modulo)
 * `I` - Increment (increment / max)
 * `R` - Random (min / max)
-* `A` - Add (operand/operand)
+* `A` - Add (operand / operand)
-* `B` - Subtract (operand/operand)
+* `B` - Subtract (operand / operand)
-* `M` - Multiply (operand/operand)
+* `M` - Multiply (operand / operand)
 
 ### 2. Variables
 
-Operators you learn in this chapter:
+In this chapter you learn all the operators related to variables:
 
-* `V` - Variable r/w single (Write: name / val | Read: - / name)
+* `V` - Variable, r/w single (Write: name / val | Read: - / name)
-* `K` - Kontakt read multiple (Read: count / names)
+* `K` - Kontakt, read multiple (Read: count / names)
 
-### 3. Flying East
+### 3. Writer
 
-Operators you learn in this chapter:
+There are a number of operators to write data into the grid.
+In this chapter we only look at one:
+
+* `X` - Write (x, y / data )
+
+### 4. Flying Operators
+
+In this chapter you learn about all the _flying_ operators `\o/ \o/ \o/`:
 
-* `X` - Write
 * `E` - East
+* `W` - West
+* `N` - North
+* `S` - South
 
-### Putting It All Together
+### 5. Scope
+
+**Putting it all together**
+
+Yay, by now we have already learned 15 operator, more than half of them all.   
+Now we can combine them to create a 'scope' to visualize and debug any variable values.
+
+### 6. ScopeHero
+
+**Putting it even togetherererer**
+
+What is even more fun than 1 scope, is 3 scopes.  
+Let generate 2 'signals', add them together to create a third signal, and use our scope technique to visualize whats going on.
 
 
+## Resources
 
+### Orca
+
+#### General
+
+* Maybe the most official home of Orca: https://100r.co/site/orca.html
+* Docs/Examples: https://wiki.xxiivv.com/site/orca.html
+
+#### ANSI-C version
+
+* https://github.com/hundredrabbits/Orca-c
+
+#### JS/Electron version
+
+* Browser/online version: https://hundredrabbits.github.io/Orca/
+* Binaries (js/electron): https://hundredrabbits.itch.io/orca
+* Sources/Docs: https://github.com/hundredrabbits/Orca
+
+### Pilot
+
+* Source/Docs: https://github.com/hundredrabbits/pilot