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/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/sampling.md b/docs/reference/sample_slicing.md
similarity index 76%
rename from docs/reference/sampling.md
rename to docs/reference/sample_slicing.md
index a06415c92f..074fa71aa8 100644
--- a/docs/reference/sampling.md
+++ b/docs/reference/sample_slicing.md
@@ -1,16 +1,15 @@
 ---
-title: Sampling
-id: sampling
+title: Sample slicing
+id: sample_slicing
 ---
 
 
-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
@@ -161,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
@@ -226,32 +202,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
diff --git a/docs/reference/samplers.md b/docs/reference/sample_speed.md
similarity index 51%
rename from docs/reference/samplers.md
rename to docs/reference/sample_speed.md
index a3f768c46a..e736133967 100644
--- a/docs/reference/samplers.md
+++ b/docs/reference/sample_speed.md
@@ -1,162 +1,62 @@
 ---
-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.
 
-## Basic sample manipulation
-
-### amp
-
-```haskell
-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`.
-
-```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.
-
-### begin
-
-```haskell
-Type: begin :: 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:
-
-```haskell
-d1 $ s "bev" # begin 0.5 # legato 1
-```
-
-In the above example, the sample is started from the half of its total length.
+## Playback-rate effects
 
-```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 playied on every cycle, but the start point from which they are playied changes on each cycle.
-
-### end
-
-```haskell
-Type: end :: 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.
-
-```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.
+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.
 
-```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.
-
-### gain
-
-```haskell
-Type: gain :: 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`.
-
-```haskell
-d1 $ s "arpy" # gain 0.8
-```
-
-This plays the first `arpy` sample at a quieter level than the default.
+### accelerate
 
 ```haskell
-d1 $ s "ab*16" # gain (range 0.8 1.3 $ sine)
+Type: accelerate :: Pattern Double -> ControlPattern
 ```
 
-This plays a hihat sound, `16` times per cycle, with a `gain` moving from `0.8` to `1.3` following a sine wave.
-
-### grain
+A pattern of numbers that speed up (or slow down) samples while they play.
 
 ```haskell
-Type: grain :: Pattern Double -> Pattern Double -> ControlPattern
+d1 $ s "arpy" # accelerate 2
 ```
 
-`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:
+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 $ slow 2 $ s "bev" # grain 0.2 0.1 # legato 1
+d1 $ arp "up" $ note "c'maj'4" # s "arpy" # accelerateTake "susan" [0.2,1,-1]
 ```
 
-is equivalent to:
+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
-d1 $ slow 2 $ s "bev" # begin 0.2 # end 0.3 # legato 1
+Type: loopAt :: Pattern Time -> ControlPattern -> ControlPattern
 ```
 
-### grain'
+`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
-Type: grain' :: Pattern String -> ControlPattern
+d1 $ loopAt 4 $ sound "breaks125"
 ```
 
-`grain'` is simply a fast shortcut to join a `begin` and an `end`.
+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 $ slow 2 $ s "bev" # grain' "0.2:0.3" # legato 1
+d1 $ loopAt 4 $ chop 32 $ sound "breaks125"
 ```
 
-This example is equivalent to:
-
+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 $ slow 2 $ s "bev" # begin 0.2 # end 0.3 # legato 1
- ```
-
-## Sample effects
-
-### accelerate
-
-```haskell
-Type: accelerate :: Pattern Double -> ControlPattern
+d1 $ juxBy 0.6 (|* speed "2") $ loopAt "<4 6 2 3>" $ chop 12 $ sound "fm:14"
 ```
 
-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
@@ -177,29 +77,6 @@ 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).
 
-### 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.
-:::
-
-```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.
 
 ### unit
 
diff --git a/docs/reference/sample_trimming.md b/docs/reference/sample_trimming.md
new file mode 100644
index 0000000000..ee24e0fd58
--- /dev/null
+++ b/docs/reference/sample_trimming.md
@@ -0,0 +1,172 @@
+---
+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
+
+This function allows us to indicate the 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.
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",