Adding stuff, fixing stuff

docs/content/configuration/editors/basic_repl.md

@@ -2,3 +2,9 @@
 title: Shrimp's native REPL
 tag: configuration, editors
 ---
+
+#shrimp comes with a built-in REPL (Read, Eval, Print, Loop) interface. There are two versions of it:
+- **python**: the native Python Read Eval Print Loop, which is the default! It is the interpreter program that runs when you type `python` in your terminal, the same that normally executes your scripts.
+- **ptpython**: a more advanced REPL with syntax highlighting, autocompletion, and other features. It can be configured more extensively from the [configuration file](/configuration/config_file/configuration_tour#editor).
+
+Both should only be used directly for rapid prototyping and testing. For live coding performances, it is recommended to use a text editor with a #shrimp plugin or whatever can help you send Python code to a live REPL. You will continue to interact with the REPL but only indirectly to send code to it.

docs/content/configuration/editors/text_editors.md

@@ -3,25 +3,32 @@ title: Choosing a Text Editor
 tag: configuration, editors
 ---
 
-Shrimp features a [native REPL](./basic_repl.md) that you can use to write and run your code. It is useful to experiment very fast without having to boot multiple software. However, you might want to use a code editor to be more comfortable. Support for Python is widespread, and you can use any code editor you like. The feature you are looking for is the ability to evaluate code fragments or code blocks in a separate terminal or REPL. Here are some code editors that I recommend:
+Shrimp comes with an [REPL](./basic_repl.md) (_Read, Eval, Print, Loop_) that you can use to write and run your code. It is useful to experiment very fast without having to boot multiple software. However, you might want to use a code editor to be more comfortable in the long run. 
+
+Support for Python in code editors is widespread, and you can use any code editor you like. The feature you are looking for is the ability to evaluate code blocks in a separate terminal. Here are some code editors that I recommend:
+
 
 - [Microsoft VSCode](https://code.visualstudio.com/): the ubiquitous modern code editor by the fear inducing company Microsoft.
 - [Vim](https://www.vim.org/) or [Neovim](https://neovim.io/): old school text editor for cool kids and hackers. I highly recommend using Neovim and learning Vim keybindings. This is a life changing experience.
 - [Emacs](https://www.gnu.org/software/emacs/): Emacs is everything and optionally a text editor. It is a very powerful and extensible text editor. It is also a Lisp interpreter. You can do pretty much anything with it. It is a bit harder to learn than Vim, but it is worth it.
 
+| <img src="https://code.visualstudio.com/assets/images/code-stable.png" width=200> | <img src="https://upload.wikimedia.org/wikipedia/commons/9/9f/Vimlogo.svg" width=200>   | <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/2/22/Heckert_GNU_white.svg/langfr-1920px-Heckert_GNU_white.svg.png" width=200>  |
+|---|---|---|
+
 ## VSCode
 
-There are multiple techniques you can use to live-code in VSCode:
+I have tried multiple techniques to live code with #shrimp in VSCode. Here are some tips:
 
-- Use [Jupyter Notebooks](../editors/jupyter_notebook.md) to write and run your code.
-- Check the `Run Selection in Python Terminal` shortcut in the command palette. Add a keybinding.
-- Wait for the dedicated Shrimp extension for VSCode...
+- Make use of [Jupyter Notebooks](../editors/jupyter_notebook.md) to write and run your code. They are well supported.
+- Map a keybinding to the `Run Selection in Python Terminal` shortcut in the command palette.
+- Wait for a dedicated #shrimp extension for VSCode. This might be a thing in the future.
 
 ## Vim / Neovim
 
 You will have to configure Vim to send code to a REPL. Neovim has native integration of the `terminal`. Here are some plugins that can help you setting up the perfect environment:
 
 - [vim-slime](https://github.com/jpalardy/vim-slime) is a plugin that allows you to send code from Vim to a REPL (attached or distant). The initial setup can be a bit daunting. Read the instructions carefully and never think about it again.
+- [iron.nvim](https://github.com/Vigemus/iron.nvim) is the same thing but more modern and featureful.
 
 ## Emacs
 

docs/content/get_started/clock_tempo.md → docs/content/get_started/long_tutorial/clock_tempo.md

@@ -1,11 +1,11 @@
 ---
 title: 3) Clock and Tempo
-tag: get started, tutorial
+tag: get_started, tutorial
 ---
 
 ## Clock basics
 
-Everything you do in #shrimp is synchronized or relative to a clock. The clock is the heart of the system. It is the object that keeps track of time, that schedules events to take place. It is important to understand how the clock works and what you can expect from it!
+Everything you do in #shrimp is synchronized or relative to a musical clock. The clock is the beating heart of the system. It is the object that keeps track of time, that schedules events and when they should take place! When you boot #shrimp, the clock is already there, waiting for events to schedule, for functions to run, etc. It will be there until you quit the session.
 
 ### Getting / setting the tempo
 

docs/content/get_started/long_tutorial/global_parameters.md

@@ -0,0 +1,23 @@
+---
+title: 4) Global Parameters
+tag: get_started, tutorial
+---
+
+## Global scale
+
+The default scale when you start the program is the natural minor scale. The default root note is `60`. You can change the default scale and root note used by the [Pnote](/reference/patterns/note) object by tweaking the `G`([GlobalConfig](/reference/global_config)) object:
+
+```python
+G.root = 40
+G.scale = SCALES.dorian
+```
+
+## Local scale
+
+Of course, you can also change these values only for the sequence itself without altering the grand scheme of things:
+
+```python
+p1 >> note(
+    note=Pn("0 2 4 0 3 5 0 1 3", root=40, scale=SCALES.dorian),
+)
+```

docs/content/get_started/hello_world.md → docs/content/get_started/long_tutorial/hello_world.md

@@ -4,23 +4,50 @@ tag: get started, tutorial
 ---
 
 > [!note] Before you start!
-> This section will start with the basics of Shrimp using MIDI. Please configure a [MIDI Output](/configuration/input_output/midi_configuration/) device before you start. You will also need a software or hardware synthesizer that can receive MIDI messages. Take a look at the list of [recommended software](/installation/recommended_software) if you need to install some :)
+> This section will teach you the basics of Shrimp using MIDI. Please configure a [MIDI Output](/configuration/input_output/midi_configuration/) device before you start. You will also need a software or hardware synthesizer that can receive MIDI messages. Take a look at the list of [recommended software](/installation/recommended_software) if you need to install some :)
 
 ## First steps
 
-
 ### Playing one note
 
-Welcome! In this section, you will learn the basics of playing melodies and rhythms using #shrimp. You will also learn how to send MIDI messages to your synthesizer in order to control it. The most basic thing you can do with Shrimp is to play a note. Let's start with that!
+Welcome! In this section, you will learn the basics of playing melodies and rhythms using #shrimp. 
+
+The most basic thing you can do with Shrimp is to play a note. Let's start with that:
 
 ```python
 p1 >> note(60)
 ```
 
-This line of code will play a note with the MIDI number 60. The `note()` function is a very important type of object in Shrimp. It is a `Sender` object that holds `Patterns`. In this case, it is so simple that we are not even using a pattern. We are just sending a single note to the synthesizer. 
+This line of code will play a note with the MIDI number 60. The `note()` function is a very important type of function in Shrimp. It is a [Sender](/reference/senders/senders). It holds [Patterns](/reference/patterns/pattern) or values. Using them, it plays an event. In this case, it is so simple that we are just passing a number, a single note to be played by the synthesizer.
+
+The function `note()` is passed to `p1`, our first [Player](/reference/player/player). Players are like the members of a band: they play the music. In this case, `p1` is in charge of playing that one single note.
 
 >[!tip] MIDI Numbers
-> The MIDI number 60 corresponds to the note C4. You can find the MIDI numbers for each note in the [MIDI Note Number](https://en.wikipedia.org/wiki/MIDI#MIDI_note_numbers) Wikipedia page.
+> The MIDI number 60 corresponds to the note C4. You can find the MIDI numbers for each note in the [MIDI Note Number](https://en.wikipedia.org/wiki/MIDI#MIDI_note_numbers) Wikipedia page. Don't worry, there are better ways to represent notes, introduced later in this tutorial 🙃.
+
+>[!tip] Default values
+> There are default values for everything! We are just passing a note number, but we end up with a **note length**, a **note duration**, a **note velocity**, etc. We are also playing on the **first channel**, etc.
+
+### Stopping Playback
+
+You can stop a [Player](/reference/player/player) by setting it to `None`. This will stop the generation of new events:
+
+```python
+p1 >> None
+```
+
+You can also stop it by using the `stop` method:
+
+```python
+p1.stop()
+```
+
+If you are dealing with multiple `Players` gone rogue, you can stop all of them at once by using the special `silence` function. This is a very powerful function that will stop everything that is currently playing:
+
+```python
+silence()
+```
+
 
 ### Playing more notes
 
@@ -30,61 +57,67 @@ Let's add another note to our melody:
 p1 >> note(Pseq(60, 65, 67, 72, 75))
 ```
 
-This line of code will play two notes in sequence: C4 and D4. The [Pseq](/reference/patterns/pseq) object is your first encounter with a very important concept in Shrimp: `Patterns`. `Patterns` are objects that can generate sequences of values. In this case, the [Pseq](/reference/patterns/pseq) object generates a sequence of two values: `60` and `62`.
+This line of code will play two notes in sequence: `C4` and `D4`. Note that you didn't had to stop the player to update the code. This is [live coding](https://en.wikipedia.org/wiki/Live_coding)! Everything is updated in real-time, and most things can be replaced by most other things without interrupting the musical flow. 
 
-### Play from a scale
+The [Pseq](/reference/patterns/pseq) object is your first encounter with a very important concept in Shrimp: [Patterns](/reference/Patterns). Patterns are objects that generate sequences of values. In this case, the [Pseq](/reference/patterns/pseq) object generates a sequence of two values: `60` and `62`, our notes.
 
-Using crude MIDI numbers is not very fun. Let's use a scale instead. Shrimp has a built-in scale system. Let's use it to generate a sequence of notes:
+If we want to be more specific, we can rewrite the example above like this:
 
 ```python
 p1 >> note(
-    note=Pnote("0 2 4 0 3 5 0 1 3"),
+    note=Pseq(60, 65, 67, 72, 75)
 )
 ```
 
-Hey, this is a new object: [Pnote](/reference/patterns/pnote). This object generates a sequence of notes based on a scale and a root note. Each number is a degree of the scale. You can go up and down the scale by using positive and negative numbers. 
+It is a good practice to layout your code spacially to make it more readable. We are playing with simple examples but it will soon start to get more complex.
 
-The default scale is the natural minor scale. You can change the default scale used by the [Pnote](/reference/patterns/note) object by tweaking the `G`([GlobalConfig](/reference/global_config)) object:
+>[!tip] Lazy tip: `Pseq` is `P`
+> Some very common patterns have a shorthand notation. You can use `P` instead of `Pseq`. There are other shorthands like this that we will soon discover!
 
-```python
-G.root = 40
-G.scale = SCALES.dorian
-```
+### Notes and scales
 
-Of course, you can also change these values only for the sequence itself without altering the grand scheme of things:
+Picking notes based on raw MIDI numbers is not very fun. Let's play some notes from a scale instead. #shrimp has a built-in scale system. Let's use it:
 
 ```python
-p1 >> n(
-    note=Pn("0 2 4 0 3 5 0 1 3", root=40, scale=SCALES.dorian),
+p1 >> note(
+    note=Pnote(0, 2, 4, 0, 3, 5, 0, 1, 3)
 )
 ```
 
-### Stopping patterns
+Hey, this is a new object: [Pnote](/reference/patterns/pnote). This object generates a sequence of notes based on a scale and a root note. Each number is a degree of the scale. You can go up and down the scale by using positive and negative numbers. If you want to learn more about the scale system, [wait for bit longer](/get_started/global_parameters/).
 
-You can stop a `Player` by setting it to `None`. This will stop the generation of new events:
 
-```python
-p1 >> None
-```
+### Note Velocity
 
-You can also stop it by using the `stop` method:
+Use the `velocity` (or `vel`) argument to change the amplitude of the note: 
 
 ```python
-p1.stop()
+p1 >> note(
+    note=Pn(0, 2, 4, 0, 3, 5, 0, 1, 3),
+    vel=Pseq(50, 80, 100, 90),
+)
 ```
 
-If you are dealing with multiple `Players` gone rogue, you can stop all of them at once by using the special `silence` function. This is a very powerful function that will stop everything that is currently playing:
+### Note Duration
+
+The length of a note can be controlled using the `length` (or `len`) argument:
 
 ```python
-silence()
+p1 >> note(
+    note=Pn(0, 2, 4, 0, 3, 5, 0, 1, 3),
+    vel=Pseq(50, 80, 100, 90),
+    len=Phuman(0.1),
+)
 ```
 
+
+
 ### What is `p1`?
 
-Shrimp has three main concepts: `Players`, `Senders` and `Patterns`. They are fairly easy to understand if you think of them as a matrioska doll:
-- `Players`: they hold `Senders` and manage them. They are the base object that you interact with.
-- `Senders`: they hold `Patterns` and the values held are generating an event (MIDI Note, etc).
-- `Patterns`: they generate sequences of values. Some are just generating a single value.
+Shrimp has three main concepts: Players, Senders and Patterns. They are fairly easy to understand if you think of them as a matrioska doll:
+- [Players](/reference/player/player): they hold `Senders` and manage them. They are the base object that you interact with.
+- [Senders](/reference/senders/senders): they hold `Patterns` and the values held are generating an event (MIDI Note, etc).
+- [Patterns](/reference/patterns/pattern): they generate sequences of values. Some are just generating a single value.
 
 >[!tip] Think of it like this: `Player` -> `Sender` -> `Patterns`.
 

docs/content/get_started/long_tutorial/index.md

@@ -0,0 +1,4 @@
+---
+title: Detailed Tutorial
+tag: get_started, tutorial
+---