From d7b467249ca6301d2c568aee0b253df970048762 Mon Sep 17 00:00:00 2001
From: Asmatzaile <gorkainventor@gmail.com>
Date: Sat, 20 Apr 2024 16:46:42 +0200
Subject: [PATCH 01/13] Add 'dealing with sample overlap', functions 'cut' and
 'legato', reorganize

---
 docs/reference/samplers.md | 147 ++++++++++++++++++++++++++-----------
 1 file changed, 104 insertions(+), 43 deletions(-)

diff --git a/docs/reference/samplers.md b/docs/reference/samplers.md
index a3f768c46a..ff56b170f7 100644
--- a/docs/reference/samplers.md
+++ b/docs/reference/samplers.md
@@ -12,7 +12,9 @@ Each function will be presented following the same model:
 * **Description**: verbal description of the function.
 * **Examples**: a small list of examples that you can copy/paste in your editor.
 
-## Basic sample manipulation
+## Amplitude manipulation
+
+These functions are used to control the amplitude (volume) of the sounds.
 
 ### amp
 
@@ -20,8 +22,7 @@ Each function will be presented following the same model:
 Type: amp :: Pattern Double -> ControlPattern
 ```
 
-`amp` is used to control the amplitude (volume) of the sound. It's very similar
-to `gain`, but it uses a linear function. Its default value is `0.4`.
+`amp` controls the amplitude of the sound using a linear function. Its default value is `0.4`. For the power function equivalent, see `gain`.
 
 ```haskell
 d1 $ s "arpy" # amp 0.6
@@ -35,67 +36,70 @@ d1 $ s "arpy" # amp "<0.4 0.8 0.2>"
 
 In the above example, the volume changes at each cycle.
 
-### begin
+### gain
 
 ```haskell
-Type: begin :: Pattern Double -> ControlPattern
+Type: gain :: Pattern Double -> ControlPattern
 ```
 
-`begin` receives a pattern of numbers from 0 to 1. It skips the beginning of each sample. The numbers indicate the proportion of the samples that needs to be skipped (`0` would play the sample from the start, `1` would skip the whole sample, `0.25` would cut off the first quarter from each sample). For example:
+`gain` controls the amplitude of the sound using a power function. Its default value is `1`. Smaller values make the sound quieter, and greater values make the sound louder.
+
+As `gain` uses a power function, the volume change around `1` is subtle, but it gets more noticable as it increases or decreases. Typical values for `gain` are between `0` and `1.5`. For the linear equivalent, see `amp`.
 
 ```haskell
-d1 $ s "bev" # begin 0.5 # legato 1
+d1 $ s "arpy" # gain 0.8
 ```
 
-In the above example, the sample is started from the half of its total length.
+This plays the first `arpy` sample at a quieter level than the default.
 
 ```haskell
-d1 $ n "0 1 2" # s "ade" # begin "<0 0.25 0.5 0.75>" # legato 1
+d1 $ s "ab*16" # gain (range 0.8 1.3 $ sine)
 ```
 
-In this other example, the first `3` `ade` samples are playied on every cycle, but the start point from which they are playied changes on each cycle.
+This plays a hihat sound, `16` times per cycle, with a `gain` moving from `0.8` to `1.3` following a sine wave.
 
-### end
+
+## Sample trimming, relative to their length
+
+### begin
 
 ```haskell
-Type: end :: Pattern Double -> ControlPattern
+Type: begin :: Pattern Double -> ControlPattern
 ```
 
-The same as `begin`, but cuts off the end of samples, shortening them. For example, `0.75` will cut off the last quarter of each sample.
+`begin` receives a pattern of numbers from 0 to 1. It cuts off the beginning of each sample. The numbers indicate how much of each sample will be skipped, relative to its length (`0` would play the sample from the start, `1` would skip the whole sample, `0.25` would cut off the first quarter from each sample). For example:
 
 ```haskell
-d1 $ s "bev" # begin 0.5 # end 0.65
+d1 $ s "bev" # begin 0.5 # legato 1
 ```
 
-This will play only a small part of the sample: from `50%` its length to `65%` its length.
+In the above example, the sample is started from the half of its total length.
 
 ```haskell
-d1 $ s "bev" >| begin 0.5 >| end "[0.65 0.55]"
+d1 $ n "0 1 2" # s "ade" # begin "<0 0.25 0.5 0.75>" # legato 1
 ```
 
-The example above will play the sample two times for cycle, but the second time will play a shorter segment than the first time, creating some kind of canon effect.
+In this other example, the first `3` `ade` samples are played on every cycle, but the start point from which they are played changes on each cycle.
 
-### gain
+### end
 
 ```haskell
-Type: gain :: Pattern Double -> ControlPattern
+Type: end :: Pattern Double -> ControlPattern
 ```
 
-`gain` is used to control the amplitude (volume) of the sound. Values less than `1` make the sound quieter. Values greater than `1` make the sound louder.
-
-`gain` uses a power function, so the volume change around `1` is subtle, but it gets more noticable as it increases or decreases. Typical values for `gain` are between `0` and `1.5`. For the linear equivalent, see `amp`.
+The same as `begin`, but cuts off the end of samples. For example, `0.75` will cut off the last quarter of each sample.
 
 ```haskell
-d1 $ s "arpy" # gain 0.8
+d1 $ s "bev" # begin 0.5 # end 0.65
 ```
 
-This plays the first `arpy` sample at a quieter level than the default.
+This will play only a small part of the sample: from `50%` its length to `65%` its length.
 
 ```haskell
-d1 $ s "ab*16" # gain (range 0.8 1.3 $ sine)
+d1 $ s "bev" >| begin 0.5 >| end "[0.65 0.55]"
 ```
 
-This plays a hihat sound, `16` times per cycle, with a `gain` moving from `0.8` to `1.3` following a sine wave.
+The example above will play the sample two times for cycle, but the second time will play a shorter segment than the first time, creating some kind of canon effect.
 
 ### grain
 
@@ -135,48 +139,59 @@ This example is equivalent to:
 d1 $ slow 2 $ s "bev" # begin 0.2 # end 0.3 # legato 1
  ```
 
-## Sample effects
 
-### accelerate
+## Sample trimming, relative to the next events: dealing with overlaps
 
-```haskell
-Type: accelerate :: Pattern Double -> ControlPattern
-```
+By default, samples play from start to end when triggered. We can override this behavior so that they are cut off by the next event of the pattern.
 
-A pattern of numbers that speed up (or slow down) samples while they play.
+### cut
 
 ```haskell
-d1 $ s "arpy" # accelerate 2
+Type: cut :: Pattern Int -> ControlPattern
 ```
 
-In this example, the sound starts at the original pitch, and gets higher as it plays. You can use a negative number to make the sound get lower.
+In the style of classic drum-machines, `cut` will stop a playing sample as soon as another sample with in same cutgroup is to be played. For example,
 
 ```haskell
-d1 $ arp "up" $ note "c'maj'4" # s "arpy" # accelerateTake "susan" [0.2,1,-1]
+d1 $ fast 2 $ sound "ho:4 hc ho:4 hc" # cut 1
 ```
 
-Using [state values](https://tidalcycles.org/docs/reference/state_values/#introduction-to-state-values), in this example we apply a different acceleration to each played note.
+makes the pattern sound more realistic, by "choking" the open hi-hat when the closed one plays. 
 
-### speed
+
+### legato
 
 ```haskell
-Type: speed :: Pattern Double -> ControlPattern
+Type: legato :: Pattern Double -> ControlPattern
 ```
 
-A pattern of numbers which changes the speed of sample playback. As a result, the sample duration and pitch will be modified. Negative values will play the sample backwards.
+`legato` modifies the note length relative to the event length. When its value is 1, is equivalent to stopping the sample when the next event (whether it is a sample or a silence), is triggered. Notice the difference between
 
 ```haskell
-d1 $ slow 5 $ s "sax:5" # legato 1 # speed 0.5
+d1 $ sound "sax ~ ~ sax ~ ~ sax ~" # legato 1
 ```
 
-This will play the `sax:5` sample at half its rate. As a result, the sample will last twice the normal time, and will be pitched a whole octave lower. This is equivalent to `d1 $ slow 5 $ s "sax:5" # legato 1 |- note 12`.
+and
 
 ```haskell
-d1 $ fast 2 $ s "breaks125:1" # cps (125/60/4) # speed (-2)
+d1 $ sound "sax ~ ~ sax ~ ~ sax ~" # cut 1
 ```
 
-In the above example, the break (which lasts for exactly one bar at 125 BPM), will be played backwards, and at double speed (so, we use `fast 2` to fill the whole cycle).
+Also, notice how these two lines are equivalent:
+```haskell
+d1 $ sound "sax ~" # legato 1
+d1 $ sound "sax" # legato 0.5
+```
+
+:::caution
+Not to be confused with `sustain`, which gives playback of a sample a duration in seconds.
+:::
+
+:::tip
+If you come from a classical music background, these two terms will probably sound conterintuitive, as there *legato* indicates that notes are to be played smoothly and connected, without silences, and that's what `cut` does in Tidal. You could think about the number after `legato` as the quantity of *tenuto* or each sample has. However, if it **really** bothers you, you can change your [Boot File](https://tidalcycles.org/docs/configuration/boot-tidal/) by appending the lines `tenuto = pF "legato"` and `legato = pI "cut"` in one of the `:{:}` blocks.
+:::
 
+## Sample trimming, in seconds
 ### sustain
 
 ```haskell
@@ -187,6 +202,7 @@ A pattern of numbers that indicates the total duration of sample playback in sec
 
 :::caution
 This `sustain` refers to the whole playback duration, and is not to be confused with the sustain level of a typical ADSR envelope.
+It's also not to be confused with `legato`, which modifies the playback duration relative to the event duration.
 :::
 
 ```haskell
@@ -201,6 +217,51 @@ d1 $ s "breaks125:2!3" # cps (120/60/4) # sustain "0.4 0.2 0.4" # begin "0 0 0.4
 
 Here, we take advantage that `sustain` receives a pattern to build a different break from the original sample.
 
+## Speed-related effects
+
+These section presents effects change  that both the speed and the pitch of the samples.
+
+### accelerate
+
+```haskell
+Type: accelerate :: Pattern Double -> ControlPattern
+```
+
+A pattern of numbers that speed up (or slow down) samples while they play.
+
+```haskell
+d1 $ s "arpy" # accelerate 2
+```
+
+In this example, the sound starts at the original pitch, and gets higher as it plays. You can use a negative number to make the sound get lower.
+
+```haskell
+d1 $ arp "up" $ note "c'maj'4" # s "arpy" # accelerateTake "susan" [0.2,1,-1]
+```
+
+Using [state values](https://tidalcycles.org/docs/reference/state_values/#introduction-to-state-values), in this example we apply a different acceleration to each played note.
+
+### speed
+
+```haskell
+Type: speed :: Pattern Double -> ControlPattern
+```
+
+A pattern of numbers which changes the speed of sample playback. As a result, the sample duration and pitch will be modified. Negative values will play the sample backwards.
+
+```haskell
+d1 $ slow 5 $ s "sax:5" # legato 1 # speed 0.5
+```
+
+This will play the `sax:5` sample at half its rate. As a result, the sample will last twice the normal time, and will be pitched a whole octave lower. This is equivalent to `d1 $ slow 5 $ s "sax:5" # legato 1 |- note 12`.
+
+```haskell
+d1 $ fast 2 $ s "breaks125:1" # cps (125/60/4) # speed (-2)
+```
+
+In the above example, the break (which lasts for exactly one bar at 125 BPM), will be played backwards, and at double speed (so, we use `fast 2` to fill the whole cycle).
+
+
 ### unit
 
 ```haskell

From eb6f14a8c4dffb91eb8965da0447a0b8a0cd2077 Mon Sep 17 00:00:00 2001
From: Asmatzaile <gorkainventor@gmail.com>
Date: Sat, 20 Apr 2024 17:03:05 +0200
Subject: [PATCH 02/13] Move sample-trimming related functions to their own
 page

---
 docs/reference/sample_trimming | 170 +++++++++++++++++++++++++++++++++
 1 file changed, 170 insertions(+)
 create mode 100644 docs/reference/sample_trimming

diff --git a/docs/reference/sample_trimming b/docs/reference/sample_trimming
new file mode 100644
index 0000000000..b3e7594a1d
--- /dev/null
+++ b/docs/reference/sample_trimming
@@ -0,0 +1,170 @@
+---
+title: Sample trimming
+id: sample_trimming
+---
+
+By default, samples play from start to end when triggered. This page presents many functions that allow to trim the samples inside TidalCycles.
+
+Each function will be presented following the same model:
+* **Type signature**: how the function is declared on the **Haskell** side.
+* **Description**: verbal description of the function.
+* **Examples**: a small list of examples that you can copy/paste in your editor.
+
+## Absolute: indicating sample duration in seconds
+
+### sustain
+
+```haskell
+Type: sustain :: Pattern Double -> ControlPattern
+```
+
+A pattern of numbers that indicates the total duration of sample playback in seconds.
+
+:::caution
+This `sustain` refers to the whole playback duration, and is not to be confused with the sustain level of a typical ADSR envelope.
+It's also not to be confused with `legato`, which modifies the playback duration relative to the event duration.
+:::
+
+```haskell
+d1 $ fast 2 $ s "breaks125:1" # cps (120/60/4) # sustain 1
+```
+
+At 120 BPM, a cycle lasts for two seconds. In the above example, we cut the sample so it plays just for one second, and repeat this part two times, so we fill the whole cycle. Note that sample pitch isn't modified.
+
+```haskell
+d1 $ s "breaks125:2!3" # cps (120/60/4) # sustain "0.4 0.2 0.4" # begin "0 0 0.4"
+
+## Event-relative
+
+The following functions allow us to deal with sample overlaps.
+
+### cut
+
+```haskell
+Type: cut :: Pattern Int -> ControlPattern
+```
+
+In the style of classic drum-machines, `cut` will stop a playing sample as soon as another sample with in same cutgroup is to be played. For example,
+
+```haskell
+d1 $ fast 2 $ sound "ho:4 hc ho:4 hc" # cut 1
+```
+
+makes the pattern sound more realistic, by "choking" the open hi-hat when the closed one plays. 
+
+### legato
+
+```haskell
+Type: legato :: Pattern Double -> ControlPattern
+```
+
+`legato` modifies the note length relative to the event length. When its value is 1, is equivalent to stopping the sample when the next event (whether it is a sample or a silence), is triggered. Notice the difference between
+
+```haskell
+d1 $ sound "sax ~ ~ sax ~ ~ sax ~" # legato 1
+```
+
+and
+
+```haskell
+d1 $ sound "sax ~ ~ sax ~ ~ sax ~" # cut 1
+```
+
+Also, notice how these two lines are equivalent:
+```haskell
+d1 $ sound "sax ~" # legato 1
+d1 $ sound "sax" # legato 0.5
+```
+
+:::caution
+Not to be confused with `sustain`, which gives playback of a sample a duration in seconds.
+:::
+
+:::tip
+If you come from a classical music background, these two terms will probably sound conterintuitive, as there *legato* indicates that notes are to be played smoothly and connected, without silences, and that's what `cut` does in Tidal. You could think about the number after `legato` as the quantity of *tenuto* or each sample has. However, if it **really** bothers you, you can change your [Boot File](https://tidalcycles.org/docs/configuration/boot-tidal/) by appending the lines `tenuto = pF "legato"` and `legato = pI "cut"` in one of the `:{:}` blocks.
+:::
+
+## Relative to the sample length
+
+These functions let us trim each sample by specifying on which part Tidal begins and/or ends playing it.
+
+### begin
+
+```haskell
+Type: begin :: Pattern Double -> ControlPattern
+```
+
+`begin` receives a pattern of numbers from 0 to 1. It cuts off the beginning of each sample. The numbers indicate how much of each sample will be skipped, relative to its length (`0` would play the sample from the start, `1` would skip the whole sample, `0.25` would cut off the first quarter from each sample). For example:
+
+```haskell
+d1 $ s "bev" # begin 0.5 # legato 1
+```
+
+In the above example, the sample is started from the half of its total length.
+
+```haskell
+d1 $ n "0 1 2" # s "ade" # begin "<0 0.25 0.5 0.75>" # legato 1
+```
+
+In this other example, the first `3` `ade` samples are played on every cycle, but the start point from which they are played changes on each cycle.
+
+### end
+
+```haskell
+Type: end :: Pattern Double -> ControlPattern
+```
+
+The same as `begin`, but cuts off the end of samples. For example, `0.75` will cut off the last quarter of each sample.
+
+```haskell
+d1 $ s "bev" # begin 0.5 # end 0.65
+```
+
+This will play only a small part of the sample: from `50%` its length to `65%` its length.
+
+```haskell
+d1 $ s "bev" >| begin 0.5 >| end "[0.65 0.55]"
+```
+
+The example above will play the sample two times for cycle, but the second time will play a shorter segment than the first time, creating some kind of canon effect.
+
+### grain
+
+```haskell
+Type: grain :: Pattern Double -> Pattern Double -> ControlPattern
+```
+
+`grain` is another way to specify what part of samples we want to play. Instead of specifying the `begin` and `end`, here we write the `begin` and the `length`.
+
+For example:
+
+```haskell
+d1 $ slow 2 $ s "bev" # grain 0.2 0.1 # legato 1
+```
+
+is equivalent to:
+
+```haskell
+d1 $ slow 2 $ s "bev" # begin 0.2 # end 0.3 # legato 1
+```
+
+### grain'
+
+```haskell
+Type: grain' :: Pattern String -> ControlPattern
+```
+
+`grain'` is simply a fast shortcut to join a `begin` and an `end`.
+
+```haskell
+d1 $ slow 2 $ s "bev" # grain' "0.2:0.3" # legato 1
+```
+
+This example is equivalent to:
+
+```haskell
+d1 $ slow 2 $ s "bev" # begin 0.2 # end 0.3 # legato 1
+ ```
+```
+
+Here, we take advantage that `sustain` receives a pattern to build a different break from the original sample.

From 8057f001df3a67d9d8dc95b9f6a698a6b91ec93f Mon Sep 17 00:00:00 2001
From: Asmatzaile <gorkainventor@gmail.com>
Date: Sat, 20 Apr 2024 17:03:49 +0200
Subject: [PATCH 03/13] Rename sample_trimming to sample_trimming.md

---
 docs/reference/{sample_trimming => sample_trimming.md} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename docs/reference/{sample_trimming => sample_trimming.md} (100%)

diff --git a/docs/reference/sample_trimming b/docs/reference/sample_trimming.md
similarity index 100%
rename from docs/reference/sample_trimming
rename to docs/reference/sample_trimming.md

From eb299036236e95e32ef833934d921b6cc626c933 Mon Sep 17 00:00:00 2001
From: Asmatzaile <gorkainventor@gmail.com>
Date: Sat, 20 Apr 2024 17:06:04 +0200
Subject: [PATCH 04/13] Update sample_trimming.md

---
 docs/reference/sample_trimming.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/reference/sample_trimming.md b/docs/reference/sample_trimming.md
index b3e7594a1d..25151167bc 100644
--- a/docs/reference/sample_trimming.md
+++ b/docs/reference/sample_trimming.md
@@ -33,6 +33,7 @@ At 120 BPM, a cycle lasts for two seconds. In the above example, we cut the samp
 
 ```haskell
 d1 $ s "breaks125:2!3" # cps (120/60/4) # sustain "0.4 0.2 0.4" # begin "0 0 0.4"
+```
 
 ## Event-relative
 
@@ -164,7 +165,6 @@ This example is equivalent to:
 
 ```haskell
 d1 $ slow 2 $ s "bev" # begin 0.2 # end 0.3 # legato 1
- ```
 ```
 
 Here, we take advantage that `sustain` receives a pattern to build a different break from the original sample.

From e24b17e697f5cf6e5f7557ac8e2df34701e37e76 Mon Sep 17 00:00:00 2001
From: Asmatzaile <gorkainventor@gmail.com>
Date: Sat, 20 Apr 2024 17:08:27 +0200
Subject: [PATCH 05/13] Update sample_trimming.md

---
 docs/reference/sample_trimming.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/reference/sample_trimming.md b/docs/reference/sample_trimming.md
index 25151167bc..ee24e0fd58 100644
--- a/docs/reference/sample_trimming.md
+++ b/docs/reference/sample_trimming.md
@@ -10,7 +10,9 @@ Each function will be presented following the same model:
 * **Description**: verbal description of the function.
 * **Examples**: a small list of examples that you can copy/paste in your editor.
 
-## Absolute: indicating sample duration in seconds
+## Absolute
+
+This function allows us to indicate the sample duration in seconds.
 
 ### sustain
 

From 1742307bdb53e07d821633ab844124dbdeab3d8d Mon Sep 17 00:00:00 2001
From: Asmatzaile <gorkainventor@gmail.com>
Date: Sat, 20 Apr 2024 17:09:44 +0200
Subject: [PATCH 06/13] Remove sample trimming functions from samplers.md

---
 docs/reference/samplers.md | 159 -------------------------------------
 1 file changed, 159 deletions(-)

diff --git a/docs/reference/samplers.md b/docs/reference/samplers.md
index ff56b170f7..49b8c15647 100644
--- a/docs/reference/samplers.md
+++ b/docs/reference/samplers.md
@@ -58,165 +58,6 @@ d1 $ s "ab*16" # gain (range 0.8 1.3 $ sine)
 
 This plays a hihat sound, `16` times per cycle, with a `gain` moving from `0.8` to `1.3` following a sine wave.
 
-
-## Sample trimming, relative to their length
-
-### begin
-
-```haskell
-Type: begin :: Pattern Double -> ControlPattern
-```
-
-`begin` receives a pattern of numbers from 0 to 1. It cuts off the beginning of each sample. The numbers indicate how much of each sample will be skipped, relative to its length (`0` would play the sample from the start, `1` would skip the whole sample, `0.25` would cut off the first quarter from each sample). For example:
-
-```haskell
-d1 $ s "bev" # begin 0.5 # legato 1
-```
-
-In the above example, the sample is started from the half of its total length.
-
-```haskell
-d1 $ n "0 1 2" # s "ade" # begin "<0 0.25 0.5 0.75>" # legato 1
-```
-
-In this other example, the first `3` `ade` samples are played on every cycle, but the start point from which they are played changes on each cycle.
-
-### end
-
-```haskell
-Type: end :: Pattern Double -> ControlPattern
-```
-
-The same as `begin`, but cuts off the end of samples. For example, `0.75` will cut off the last quarter of each sample.
-
-```haskell
-d1 $ s "bev" # begin 0.5 # end 0.65
-```
-
-This will play only a small part of the sample: from `50%` its length to `65%` its length.
-
-```haskell
-d1 $ s "bev" >| begin 0.5 >| end "[0.65 0.55]"
-```
-
-The example above will play the sample two times for cycle, but the second time will play a shorter segment than the first time, creating some kind of canon effect.
-
-### grain
-
-```haskell
-Type: grain :: Pattern Double -> Pattern Double -> ControlPattern
-```
-
-`grain` is another way to specify what part of samples we want to play. Instead of specifying the `begin` and `end`, here we write the `begin` and the `length`.
-
-For example:
-
-```haskell
-d1 $ slow 2 $ s "bev" # grain 0.2 0.1 # legato 1
-```
-
-is equivalent to:
-
-```haskell
-d1 $ slow 2 $ s "bev" # begin 0.2 # end 0.3 # legato 1
-```
-
-### grain'
-
-```haskell
-Type: grain' :: Pattern String -> ControlPattern
-```
-
-`grain'` is simply a fast shortcut to join a `begin` and an `end`.
-
-```haskell
-d1 $ slow 2 $ s "bev" # grain' "0.2:0.3" # legato 1
-```
-
-This example is equivalent to:
-
-```haskell
-d1 $ slow 2 $ s "bev" # begin 0.2 # end 0.3 # legato 1
- ```
-
-
-## Sample trimming, relative to the next events: dealing with overlaps
-
-By default, samples play from start to end when triggered. We can override this behavior so that they are cut off by the next event of the pattern.
-
-### cut
-
-```haskell
-Type: cut :: Pattern Int -> ControlPattern
-```
-
-In the style of classic drum-machines, `cut` will stop a playing sample as soon as another sample with in same cutgroup is to be played. For example,
-
-```haskell
-d1 $ fast 2 $ sound "ho:4 hc ho:4 hc" # cut 1
-```
-
-makes the pattern sound more realistic, by "choking" the open hi-hat when the closed one plays. 
-
-
-### legato
-
-```haskell
-Type: legato :: Pattern Double -> ControlPattern
-```
-
-`legato` modifies the note length relative to the event length. When its value is 1, is equivalent to stopping the sample when the next event (whether it is a sample or a silence), is triggered. Notice the difference between
-
-```haskell
-d1 $ sound "sax ~ ~ sax ~ ~ sax ~" # legato 1
-```
-
-and
-
-```haskell
-d1 $ sound "sax ~ ~ sax ~ ~ sax ~" # cut 1
-```
-
-Also, notice how these two lines are equivalent:
-```haskell
-d1 $ sound "sax ~" # legato 1
-d1 $ sound "sax" # legato 0.5
-```
-
-:::caution
-Not to be confused with `sustain`, which gives playback of a sample a duration in seconds.
-:::
-
-:::tip
-If you come from a classical music background, these two terms will probably sound conterintuitive, as there *legato* indicates that notes are to be played smoothly and connected, without silences, and that's what `cut` does in Tidal. You could think about the number after `legato` as the quantity of *tenuto* or each sample has. However, if it **really** bothers you, you can change your [Boot File](https://tidalcycles.org/docs/configuration/boot-tidal/) by appending the lines `tenuto = pF "legato"` and `legato = pI "cut"` in one of the `:{:}` blocks.
-:::
-
-## Sample trimming, in seconds
-### sustain
-
-```haskell
-Type: sustain :: Pattern Double -> ControlPattern
-```
-
-A pattern of numbers that indicates the total duration of sample playback in seconds.
-
-:::caution
-This `sustain` refers to the whole playback duration, and is not to be confused with the sustain level of a typical ADSR envelope.
-It's also not to be confused with `legato`, which modifies the playback duration relative to the event duration.
-:::
-
-```haskell
-d1 $ fast 2 $ s "breaks125:1" # cps (120/60/4) # sustain 1
-```
-
-At 120 BPM, a cycle lasts for two seconds. In the above example, we cut the sample so it plays just for one second, and repeat this part two times, so we fill the whole cycle. Note that sample pitch isn't modified.
-
-```haskell
-d1 $ s "breaks125:2!3" # cps (120/60/4) # sustain "0.4 0.2 0.4" # begin "0 0 0.4"
-```
-
-Here, we take advantage that `sustain` receives a pattern to build a different break from the original sample.
-
 ## Speed-related effects
 
 These section presents effects change  that both the speed and the pitch of the samples.

From 8d006753691ae207e3218a0985fba6abd3533f9b Mon Sep 17 00:00:00 2001
From: Asmatzaile <gorkainventor@gmail.com>
Date: Sat, 20 Apr 2024 18:25:47 +0200
Subject: [PATCH 07/13] Update samplers.md

---
 docs/reference/samplers.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/reference/samplers.md b/docs/reference/samplers.md
index 49b8c15647..1b83850a32 100644
--- a/docs/reference/samplers.md
+++ b/docs/reference/samplers.md
@@ -60,7 +60,7 @@ This plays a hihat sound, `16` times per cycle, with a `gain` moving from `0.8`
 
 ## Speed-related effects
 
-These section presents effects change  that both the speed and the pitch of the samples.
+This section presents effects that change both the speed and the pitch of the samples.
 
 ### accelerate
 

From 0841bc123708f059ee69069baaaa25c2136b669a Mon Sep 17 00:00:00 2001
From: Asmatzaile <gorkainventor@gmail.com>
Date: Sat, 20 Apr 2024 18:44:57 +0200
Subject: [PATCH 08/13] move info about sampling oscillators to oscillators

---
 docs/reference/Oscillators.md | 31 +++++++++++++++++++++++++++++++
 docs/reference/sampling.md    | 33 ++-------------------------------
 2 files changed, 33 insertions(+), 31 deletions(-)

diff --git a/docs/reference/Oscillators.md b/docs/reference/Oscillators.md
index de92ee6fc0..82f9d7a028 100644
--- a/docs/reference/Oscillators.md
+++ b/docs/reference/Oscillators.md
@@ -141,3 +141,34 @@ d1 $ s "bass:5*8" # lpf (slow 4 $ range 200 5000 $ sine)
 :::tip
 Notice that most of the time, the speed up/down will be in sync with your pattern. How convenient!
 :::
+
+## Sampling oscillators and signals
+
+### segment
+
+```haskell
+Type: segment :: Pattern Time -> Pattern a -> Pattern a
+```
+
+`segment` 'samples' the pattern at a rate of `n` events per cycle. Useful for turning a continuous pattern into a discrete one. In this example, the pattern originates from the shape of a sine wave, a continuous pattern. Without segment the samples will get triggered at an undefined frequency which may be very high.
+
+```haskell
+d1 $ n (slow 2 $ segment 16 $ range 0 32 $ sine) # sound "amencutup"
+```
+
+### discretise
+
+`segment` used to be known as `discretise`. The old name remains as an alias and will still work, but may be removed or repurposed in a future version of **Tidal**. 
+
+## Creating oscillators
+
+### sig
+
+```haskell
+Type: sig :: (Time -> a) -> Pattern a
+```
+`sig` takes a function of time and turns it into a pattern. It's very useful for creating continuous patterns such as `sine` or `perlin`. For example, `saw` is defined as
+
+```haskell
+saw = sig $ \t -> mod' (fromRational t) 1
+```
diff --git a/docs/reference/sampling.md b/docs/reference/sampling.md
index a06415c92f..0e1455a29b 100644
--- a/docs/reference/sampling.md
+++ b/docs/reference/sampling.md
@@ -4,13 +4,12 @@ id: sampling
 ---
 
 
-This page will present you all the functions that can be used to slice, cut, reverse or explode your audio samples, incoming signals or oscillators. Each function will be presented following the same model:
+This page will present you all the functions that can be used to slice, cut, reverse or explode your samples. Each function will be presented following the same model:
 * **Type signature**: how the function is declared on the **Haskell** side.
 * **Description**: verbal description of the function.
 * **Examples**: a small list of examples that you can copy/paste in your editor.
 
 
-## Audio sampling
 ### chop
 
 ```haskell
@@ -226,32 +225,4 @@ vs
 ```haskell
 d1 $ smash' 12 [2,3,4] $ s "bev*4"
 ```
-for a dramatic difference.
-
-## Signal sampling 
-### segment
-
-```haskell
-Type: segment :: Pattern Time -> Pattern a -> Pattern a
-```
-
-`segment` 'samples' the pattern at a rate of `n` events per cycle. Useful for turning a continuous pattern into a discrete one. In this example, the pattern originates from the shape of a sine wave, a continuous pattern. Without segment the samples will get triggered at an undefined frequency which may be very high.
-
-```haskell
-d1 $ n (slow 2 $ segment 16 $ range 0 32 $ sine) # sound "amencutup"
-```
-
-### discretise
-
-`segment` used to be known as `discretise`. The old name remains as an alias and will still work, but may be removed or repurposed in a future version of **Tidal**. 
-
-### sig
-
-```haskell
-Type: sig :: (Time -> a) -> Pattern a
-```
-`sig` takes a function of time and turns it into a pattern. It's very useful for creating continuous patterns such as `sine` or `perlin`. For example, `saw` is defined as
-
-```haskell
-saw = sig $ \t -> mod' (fromRational t) 1
-```
+for a dramatic difference.
\ No newline at end of file

From 08deefd6fea7312eed9ca1f6ebd94032f2a75373 Mon Sep 17 00:00:00 2001
From: Asmatzaile <gorkainventor@gmail.com>
Date: Sat, 20 Apr 2024 18:47:13 +0200
Subject: [PATCH 09/13] Move loopAt form sampling to samplers > speed related
 effects

---
 docs/reference/samplers.md | 23 +++++++++++++++++++++++
 docs/reference/sampling.md | 23 -----------------------
 2 files changed, 23 insertions(+), 23 deletions(-)

diff --git a/docs/reference/samplers.md b/docs/reference/samplers.md
index 1b83850a32..1b636551c7 100644
--- a/docs/reference/samplers.md
+++ b/docs/reference/samplers.md
@@ -82,6 +82,29 @@ d1 $ arp "up" $ note "c'maj'4" # s "arpy" # accelerateTake "susan" [0.2,1,-1]
 
 Using [state values](https://tidalcycles.org/docs/reference/state_values/#introduction-to-state-values), in this example we apply a different acceleration to each played note.
 
+### loopAt
+    
+```haskell
+Type: loopAt :: Pattern Time -> ControlPattern -> ControlPattern
+```
+
+`loopAt` makes sample fit the given number of cycles. Internally, it works by setting the unit control to "c", changing the playback speed of the sample with the speed parameter, and setting the density of the pattern to match.
+
+```haskell
+d1 $ loopAt 4 $ sound "breaks125"
+```
+
+It’s a good idea to use this in conjuction with `chop`, so the break is chopped into pieces and you don’t have to wait for the whole sample to start/stop.
+
+```haskell
+d1 $ loopAt 4 $ chop 32 $ sound "breaks125"
+```
+
+Like all **Tidal** functions, you can mess about with this considerably. The below example shows how you can supply a pattern of cycle counts to `loopAt`:
+```haskell
+d1 $ juxBy 0.6 (|* speed "2") $ loopAt "<4 6 2 3>" $ chop 12 $ sound "fm:14"
+```
+
 ### speed
 
 ```haskell
diff --git a/docs/reference/sampling.md b/docs/reference/sampling.md
index 0e1455a29b..beae7a4c14 100644
--- a/docs/reference/sampling.md
+++ b/docs/reference/sampling.md
@@ -160,29 +160,6 @@ d1 $ bite 4 "0 1*2 2*2 [~ 3]" $ n "0 .. 7" # sound "drum"
 d1 $ chew 4 "0 1*2 2*2 [~ 3]" $ n "0 .. 7" # sound "drum"
 ```
 
-### loopAt
-    
-```haskell
-Type: loopAt :: Pattern Time -> ControlPattern -> ControlPattern
-```
-
-`loopAt` makes sample fit the given number of cycles. Internally, it works by setting the unit control to "c", changing the playback speed of the sample with the speed parameter, and setting the density of the pattern to match.
-
-```haskell
-d1 $ loopAt 4 $ sound "breaks125"
-```
-
-It’s a good idea to use this in conjuction with `chop`, so the break is chopped into pieces and you don’t have to wait for the whole sample to start/stop.
-
-```haskell
-d1 $ loopAt 4 $ chop 32 $ sound "breaks125"
-```
-
-Like all **Tidal** functions, you can mess about with this considerably. The below example shows how you can supply a pattern of cycle counts to `loopAt`:
-```haskell
-d1 $ juxBy 0.6 (|* speed "2") $ loopAt "<4 6 2 3>" $ chop 12 $ sound "fm:14"
-```
-
 ### smash
 
 ```haskell

From 3dfdc4968ca5de593b684facac11abdacec3ebd2 Mon Sep 17 00:00:00 2001
From: Asmatzaile <gorkainventor@gmail.com>
Date: Sat, 20 Apr 2024 18:49:27 +0200
Subject: [PATCH 10/13] Rename sampling to sample slicing

---
 docs/reference/{sampling.md => sample_slicing.md} | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
 rename docs/reference/{sampling.md => sample_slicing.md} (99%)

diff --git a/docs/reference/sampling.md b/docs/reference/sample_slicing.md
similarity index 99%
rename from docs/reference/sampling.md
rename to docs/reference/sample_slicing.md
index beae7a4c14..074fa71aa8 100644
--- a/docs/reference/sampling.md
+++ b/docs/reference/sample_slicing.md
@@ -1,6 +1,6 @@
 ---
-title: Sampling
-id: sampling
+title: Sample slicing
+id: sample_slicing
 ---
 
 

From 48b39acfe8308ec154f99b72fb7b2e2105d9556e Mon Sep 17 00:00:00 2001
From: Asmatzaile <gorkainventor@gmail.com>
Date: Sat, 20 Apr 2024 18:54:27 +0200
Subject: [PATCH 11/13] Moved amplitude manipulation from samplers to
 audio_effects

---
 docs/reference/effects.md  | 46 ++++++++++++++++++++++++++++++++++++++
 docs/reference/samplers.md | 46 --------------------------------------
 2 files changed, 46 insertions(+), 46 deletions(-)

diff --git a/docs/reference/effects.md b/docs/reference/effects.md
index 341cf1dbbf..4417e4a963 100644
--- a/docs/reference/effects.md
+++ b/docs/reference/effects.md
@@ -5,6 +5,52 @@ id: audio_effects
 
 ## Basic effects
 
+### Amplitude manipulation
+
+These functions are used to control the amplitude (volume) of the sounds.
+
+#### amp
+
+```haskell
+Type: amp :: Pattern Double -> ControlPattern
+```
+
+`amp` controls the amplitude of the sound using a linear function. Its default value is `0.4`. For the power function equivalent, see `gain`.
+
+```haskell
+d1 $ s "arpy" # amp 0.6
+```
+
+This will play the first `arpy` sample at a volume slightly louder than the default.
+
+```haskell
+d1 $ s "arpy" # amp "<0.4 0.8 0.2>"
+```
+
+In the above example, the volume changes at each cycle.
+
+#### gain
+
+```haskell
+Type: gain :: Pattern Double -> ControlPattern
+```
+
+`gain` controls the amplitude of the sound using a power function. Its default value is `1`. Smaller values make the sound quieter, and greater values make the sound louder.
+
+As `gain` uses a power function, the volume change around `1` is subtle, but it gets more noticable as it increases or decreases. Typical values for `gain` are between `0` and `1.5`. For the linear equivalent, see `amp`.
+
+```haskell
+d1 $ s "arpy" # gain 0.8
+```
+
+This plays the first `arpy` sample at a quieter level than the default.
+
+```haskell
+d1 $ s "ab*16" # gain (range 0.8 1.3 $ sine)
+```
+
+This plays a hihat sound, `16` times per cycle, with a `gain` moving from `0.8` to `1.3` following a sine wave.
+
 ### Pitch
 
 #### Octer
diff --git a/docs/reference/samplers.md b/docs/reference/samplers.md
index 1b636551c7..5d0c04e1c6 100644
--- a/docs/reference/samplers.md
+++ b/docs/reference/samplers.md
@@ -12,52 +12,6 @@ Each function will be presented following the same model:
 * **Description**: verbal description of the function.
 * **Examples**: a small list of examples that you can copy/paste in your editor.
 
-## Amplitude manipulation
-
-These functions are used to control the amplitude (volume) of the sounds.
-
-### amp
-
-```haskell
-Type: amp :: Pattern Double -> ControlPattern
-```
-
-`amp` controls the amplitude of the sound using a linear function. Its default value is `0.4`. For the power function equivalent, see `gain`.
-
-```haskell
-d1 $ s "arpy" # amp 0.6
-```
-
-This will play the first `arpy` sample at a volume slightly louder than the default.
-
-```haskell
-d1 $ s "arpy" # amp "<0.4 0.8 0.2>"
-```
-
-In the above example, the volume changes at each cycle.
-
-### gain
-
-```haskell
-Type: gain :: Pattern Double -> ControlPattern
-```
-
-`gain` controls the amplitude of the sound using a power function. Its default value is `1`. Smaller values make the sound quieter, and greater values make the sound louder.
-
-As `gain` uses a power function, the volume change around `1` is subtle, but it gets more noticable as it increases or decreases. Typical values for `gain` are between `0` and `1.5`. For the linear equivalent, see `amp`.
-
-```haskell
-d1 $ s "arpy" # gain 0.8
-```
-
-This plays the first `arpy` sample at a quieter level than the default.
-
-```haskell
-d1 $ s "ab*16" # gain (range 0.8 1.3 $ sine)
-```
-
-This plays a hihat sound, `16` times per cycle, with a `gain` moving from `0.8` to `1.3` following a sine wave.
-
 ## Speed-related effects
 
 This section presents effects that change both the speed and the pitch of the samples.

From 7d22d3587fa011cfcb714aaaf97f280e15daaa0e Mon Sep 17 00:00:00 2001
From: Asmatzaile <gorkainventor@gmail.com>
Date: Sat, 20 Apr 2024 19:08:31 +0200
Subject: [PATCH 12/13] Rename samplers to sample_speed

---
 docs/reference/{samplers.md => sample_speed.md} | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)
 rename docs/reference/{samplers.md => sample_speed.md} (92%)

diff --git a/docs/reference/samplers.md b/docs/reference/sample_speed.md
similarity index 92%
rename from docs/reference/samplers.md
rename to docs/reference/sample_speed.md
index 5d0c04e1c6..e736133967 100644
--- a/docs/reference/samplers.md
+++ b/docs/reference/sample_speed.md
@@ -1,20 +1,18 @@
 ---
-title: Samplers
-id: samplers
+title: Sample speed
+id: sample_speed
 ---
 
-This page presents many functions related to the use of samples inside TidalCycles.
-
-For specific information about functions used to slice and loop samples see [Sampling](https://tidalcycles.org/docs/reference/sampling).
+This page presents many functions that allow to change the speed at which samples play.
 
 Each function will be presented following the same model:
 * **Type signature**: how the function is declared on the **Haskell** side.
 * **Description**: verbal description of the function.
 * **Examples**: a small list of examples that you can copy/paste in your editor.
 
-## Speed-related effects
+## Playback-rate effects
 
-This section presents effects that change both the speed and the pitch of the samples.
+This section presents effects that change both the speed and the pitch of the samples. As frequencies are scaled at the same ratio of the speed, a 2x playback rate will correspond to half the duration and the pitch sounding an octave higher, and a 0.5x playback rate will correspond to double the duration and the pitch sounding an octave lower.
 
 ### accelerate
 

From 77c8e9fdab398899a4231bd2b1c8b7cee8ae5a83 Mon Sep 17 00:00:00 2001
From: Asmatzaile <gorkainventor@gmail.com>
Date: Tue, 30 Apr 2024 10:29:43 +0200
Subject: [PATCH 13/13] update sidebars.js

---
 sidebars.js | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/sidebars.js b/sidebars.js
index 8b117474f9..2bc8c44e80 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -126,8 +126,9 @@ module.exports = {
       "reference/time",
       "reference/harmony_melody",
       "reference/transitions",
-      "reference/samplers",
-      "reference/sampling",
+      "reference/sample_slicing",
+      "reference/sample_trimming",
+      "reference/sample_speed",
       "reference/randomness",
       "reference/composition",
       "reference/mi-ugens",