use multiple code example blocks in docs, where it fits to ease copying them

Author: emuell

docs/book.toml

@@ -16,6 +16,9 @@ max-level = 3
 [output.html]
 default-theme = "dark"
 preferred-dark-theme = "ayu"
+git-repository-url = "https://github.com/emuell/afseq"
+git-repository-icon = "fa-github"
+edit-url-template = "https://github.com/emuell/afseq/edit/master/docs/{path}"
 additional-css = [ "src/styles.css" ]
 
 [output.linkcheck]

docs/src/API/cycle.md

@@ -20,12 +20,16 @@
 >  ```lua
 > --A chord sequence
 > cycle("[c4, e4, g4] [e4, g4, b4] [g4, b4, d5] [b4, d5, f#5]")
+> ```
+> ```lua
 > --Arpeggio pattern with variations
 > cycle("<c4 e4 g4> <e4 g4> <g4 b4 d5> <b4 f5>")
+> ```
+> ```lua
 > --Euclidean Rhythms
 > cycle("c4(3,8) e4(5,8) g4(7,8)")
-> --Polyrhythm
-> cycle("{c4 e4 g4 b4}%2, {f4 d4 a4}%4")
+> ```
+> ```lua
 > --Map custom identifiers to notes
 > cycle("bd(3,8)"):map({ bd = "c4 #1" })
 >  ```  
@@ -84,16 +88,22 @@
 >   bd = "c4",
 >   sn = "e4 #1 v0.2"
 > })
+> ```
+> ```lua
 > --Using a static map table with targets
 > cycle("bd:1 <bd:5, bd:7>"):map({
->   -- instrument #1,5,7 will be set as specified
+>   -- instrument #1,5,7 are set additionally, as specified
 >   bd = { key = "c4", volume = 0.5 },
 > })
+> ```
+> ```lua
 > --Using a dynamic map function
 > cycle("4 5 4 <5 [4|6]>"):map(function(context, value)
 >   -- emit a random note with 'value' as octave
 >   return math.random(0, 11) + value * 12
 > end)
+> ```
+> ```lua
 > --Using a dynamic map function generator
 > cycle("4 5 4 <4 [5|7]>"):map(function(init_context)
 >   local notes = scale("c", "minor").notes
@@ -104,6 +114,8 @@
 >     return { key = note + octave * 12 }
 >   end
 > end)
+> ```
+> ```lua
 > --Using a dynamic map function to map values to chord degrees
 > cycle("1 5 1 [6|7]"):map(function(init_context)
 >   local cmin = scale("c", "minor")

docs/src/API/pattern.md

@@ -8,23 +8,28 @@
 > ```lua
 > -- using + and * operators to combine patterns
 > pattern.from{ 0, 1 } * 3 + { 1, 0 }
-> 
+> ```
+> ```lua
 > -- repeating, spreading and subsets
 > pattern.from{ 0, 1, { 1, 1 } }:repeat_n(4):spread(1.25):take(16)
-> 
+> ```
+> ```lua
 > -- euclidean patterns
 > pattern.euclidean(12, 16)
 > pattern.from{ 1, 0.5, 1, 1 }:euclidean(12)
-> 
+> ```
+> ```lua
 > -- generate/init from functions
 > pattern.new(8):init(1) --> 1,1,1,1,1,1,1,1
 > pattern.new(12):init(function() return math.random(0.5, 1.0) end )
 > pattern.new(16):init(scale("c", "minor").notes_iter())
-> 
+> ```
+> ```lua
 > -- generate note patterns
 > pattern.from{ "c4", "g4", "a4" } * 7 + { "a4", "g4", "c4" }
-> 
-> -- generate chord patterns
+> ```
+> ```lua
+> -- generate chords from degree values
 > pattern.from{ 1, 5, 6, 4 }:map(function(index, degree)
 >   return scale("c", "minor"):chord(degree)
 > end)

docs/src/API/rhythm.md

@@ -19,7 +19,8 @@
 >   pattern = pattern.euclidean(12, 16),
 >   emit = { "c4", "g4", { "c5 v0.7", "g5 v0.4" }, "a#4" }
 > }
-> 
+> ```
+> ```lua
 > -- trigger a chord sequence every 4 bars after 4 bars
 > return rhythm {
 >   unit = "bars",
@@ -30,7 +31,8 @@
 >     note("g3'm7"):transpose({ 0, 12, 0, 0 })
 >   }
 > }
-> 
+> ```
+> ```lua
 > --trigger notes in a seeded, random subdivision pattern
 > local seed = 23498
 > return rhythm {
@@ -44,7 +46,8 @@
 >   end,
 >   emit = { "c4" }
 > }
-> 
+> ```
+> ```lua
 > --trigger random notes in a seeded random pattern from a pentatonic scale
 > local cmin = scale("c5", "pentatonic minor").notes
 > return rhythm {
@@ -56,13 +59,13 @@
 >     return { key = cmin[math.random(#cmin)], volume = 0.7 }
 >   end
 > }
-> 
+> ```
+> ```lua
 > --emit a tidal cycle every new bar
 > return rhythm {
 >   unit = "bars",
 >   emit = cycle("[c4 [f5 f4]*2]|[c4 [g5 g4]*3]")
 > }
-> --
 > ```  
 
 
@@ -95,26 +98,39 @@
 > create other less common rhythm bases.
 > #### examples:
 > ```lua
-> unit = "beats", resolution = 1.01 --> slightly off beat pulse
-> unit = "1/16", resolution = 4/3 --> triplet
+> -- slightly off beat pulse
+> unit = "beats", 
+> resolution = 1.01
+> ```
+> ```lua
+> -- triplet
+> unit = "1/16", 
+> resolution = 4/3
 > ```
 
 ### resolution : [`number`](../API/builtins/number.md)[`?`](../API/builtins/nil.md) {#resolution}
 > Factor which is applied on `unit` to specify the final time resolution of the emitter.
 > #### examples:
 > ```lua
-> unit = "beats", resolution = 1.01 --> slightly off beat pulse
-> unit = "1/16", resolution = 4/3 --> triplet
+> -- slightly off beat pulse
+> unit = "beats",
+> resolution = 1.01
+> ```
+> ```lua
+> -- triplet
+> unit = "1/16",
+> resolution = 4/3
 > ```
 
 ### offset : [`number`](../API/builtins/number.md)[`?`](../API/builtins/nil.md) {#offset}
 > Optional offset in `unit * resolution` time units. By default 0.
 > When set, the rhythm's event output will be delayed by the given offset value.
 > #### examples:
 > ```lua
+> -- start emitting after 4*4 beats
 > unit = "1/4",
 > resolution = 4,
-> offset = 4 -- start emitting after 4*4 beats
+> offset = 4
 > ```
 
 ### inputs : [`InputParameter`](../API/input.md#InputParameter)[] {#inputs}
@@ -126,18 +142,19 @@
 > ```lua
 > -- trigger a single note as specified by input parameter 'note'
 > -- when input parameter 'enabled' is true, else triggers nothing.
+> return rhythm {
 >   inputs = {
 >     parameter.boolean("enabled", true),
 >     parameter.integer("note", 48, { 0, 127 })
 >   },
-> -- [...]
 >   emit = function(context)
 >     if context.inputs.enabled then -- boolean value
 >       return note(context.inputs.note) -- integer value
 >     else
 >       return nil
 >     end
 >   end
+> }
 > ```
 
 ### pattern : [`boolean`](../API/builtins/boolean.md) | [`number`](../API/builtins/number.md) | `0` | `1` | [`Pulse`](#Pulse) | [`nil`](../API/builtins/nil.md)[] | (context : [`PatternContext`](../API/rhythm.md#PatternContext)) `->` [`boolean`](../API/builtins/boolean.md) | [`number`](../API/builtins/number.md) | `0` | `1` | [`Pulse`](#Pulse) | [`nil`](../API/builtins/nil.md) | (context : [`PatternContext`](../API/rhythm.md#PatternContext)) `->` (context : [`PatternContext`](../API/rhythm.md#PatternContext)) `->` [`boolean`](../API/builtins/boolean.md) | [`number`](../API/builtins/number.md) | `0` | `1` | [`Pulse`](#Pulse) | [`nil`](../API/builtins/nil.md) {#pattern}
@@ -158,27 +175,31 @@
 > ```lua
 > -- static pattern
 > pattern = { 1, 0, 0, 1 }
+> ```
+> ```lua
 > -- "cram" pulses into a single pulse slot via subdivisions
 > pattern = { 1, { 1, 1, 1 } }
-> 
+> ```
+> ```lua
 > -- patterns created via the "patterns" lib
 > pattern = pattern.from{ 1, 0 } * 3 + { 1, 1 }
 > pattern = pattern.euclidean(7, 16, 2)
-> 
+> ```
+> ```lua
 > -- stateless pattern function
 > pattern = function(context)
 >   return math.random(0, 1)
 > end
-> 
+> ```
+> ```lua
 > -- stateful generator function
 > pattern = function(init_context)
 >   local triggers = table.new{ 0, 6, 10 }
 >   return function(context)
->     local step = (context.step - 1) % 16
+>     local step = (context.pulse_step - 1) % 16
 >     return triggers:contains(step)
 >   end
 > end
-> 
 > ```
 
 ### repeats : [`boolean`](../API/builtins/boolean.md) | [`integer`](../API/builtins/integer.md) {#repeats}
@@ -192,10 +213,14 @@
 > 
 > #### examples:
 > ```lua
-> repeat = 0 -- one-shot
-> repeat = false -- also a one-shot
-> repeat = 3 -- play the pattern 4 times
-> repeat = true -- play & repeat forever
+> -- one-shot
+> repeat = 0
+> -- also a one-shot
+> repeat = false
+> -- play the pattern 4 times
+> repeat = 3
+> -- play & repeat forever (default)
+> repeat = true
 > ```
 
 ### gate : (context : [`GateContext`](../API/rhythm.md#GateContext)) `->` [`boolean`](../API/builtins/boolean.md) | (context : [`GateContext`](../API/rhythm.md#GateContext)) `->` (context : [`GateContext`](../API/rhythm.md#GateContext)) `->` [`boolean`](../API/builtins/boolean.md) {#gate}
@@ -214,6 +239,12 @@
 >   return context.pulse_value > math.random()
 > end
 > ```
+> ```lua
+> -- threshold gate: skips all pulse values below a given threshold value
+> gate = function(context)
+>   return context.pulse_value > 0.5
+> end
+> ```
 
 ### emit : [`Cycle`](../API/cycle.md#Cycle) | [`Sequence`](../API/sequence.md#Sequence) | [`Note`](../API/note.md#Note) | [`NoteValue`](#NoteValue) | [`Note`](../API/note.md#Note) | [`NoteValue`](#NoteValue)[] | (context : [`EmitterContext`](../API/rhythm.md#EmitterContext)) `->` [`NoteValue`](#NoteValue) | (context : [`EmitterContext`](../API/rhythm.md#EmitterContext)) `->` (context : [`EmitterContext`](../API/rhythm.md#EmitterContext)) `->` [`NoteValue`](#NoteValue) {#emit}
 > Specify the melodic pattern of the rhythm. For every pulse in the rhythmical pattern, the event
@@ -231,16 +262,22 @@
 > ```lua
 > -- a sequence of c4, g4
 > emit = {"c4", "g4"}
+> ```
+> ```lua
 > -- a chord of c4, d#4, g4
 > emit = {{"c4", "d#4", "g4"}} -- or {"c4'min"}
+> ```
+> ```lua
 > -- a sequence of c4, g4 with volume 0.5
 > emit = sequence{"c4", "g4"}:volume(0.5)
-> 
+> ```
+> ```lua
 > -- stateless generator function
 > emit = function(context)
 >   return 48 + math.random(1, 4) * 5
 > end
-> 
+> ```
+> ```lua
 > -- stateful generator function
 > emit = function(init_context)
 >   local count, step, notes = 1, 2, scale("c5", "minor").notes
@@ -250,16 +287,17 @@
 >     return { key = key, volume = 0.5 }
 >   end
 > end
-> 
+> ```
+> ```lua
 > -- a note pattern
 > local tritone = scale("c5", "tritone")
-> .. -- instrument #1,5,7 will be set as specified.
+> --[...]
 > emit = pattern.from(tritone:chord(1, 4)):euclidean(6) +
 >   pattern.from(tritone:chord(5, 4)):euclidean(6)
-> 
+> ```
+> ```lua
 > -- a tidal cycle
-> emit = cycle("<[a3 c4 e4 a4]*3 [d4 g3 g4 c4]>")
-> --
+> emit = cycle("<[a3 c4 e4 a4]*3 [d4 g3 g4 c4]>"),
 > ```
 
   

docs/src/API/scale.md

@@ -240,7 +240,7 @@
 > #### examples:
 > ```lua
 > local cmin = scale("c4", "minor")
-> cmin:fit("c4", "d4", "f4") -> 48, 50, 53 (cmaj -> cmin)
+> cmin:fit("c4", "d4", "f4") --> 48, 50, 53 (cmaj -> cmin)
 > ```  
 
 

types/nerdo/library/cycle.lua

@@ -44,16 +44,22 @@ local Cycle = {}
 ---  bd = "c4",
 ---  sn = "e4 #1 v0.2"
 ---})
+---```
+---```lua
 -----Using a static map table with targets
 ---cycle("bd:1 <bd:5, bd:7>"):map({
----  -- instrument #1,5,7 will be set as specified
+---  -- instrument #1,5,7 are set additionally, as specified
 ---  bd = { key = "c4", volume = 0.5 },
 ---})
+---```
+---```lua
 -----Using a dynamic map function
 ---cycle("4 5 4 <5 [4|6]>"):map(function(context, value)
 ---  -- emit a random note with 'value' as octave
 ---  return math.random(0, 11) + value * 12
 ---end)
+---```
+---```lua
 -----Using a dynamic map function generator
 ---cycle("4 5 4 <4 [5|7]>"):map(function(init_context)
 ---  local notes = scale("c", "minor").notes
@@ -64,6 +70,8 @@ local Cycle = {}
 ---    return { key = note + octave * 12 }
 ---  end
 ---end)
+---```
+---```lua
 -----Using a dynamic map function to map values to chord degrees
 ---cycle("1 5 1 [6|7]"):map(function(init_context)
 ---  local cmin = scale("c", "minor")
@@ -91,12 +99,16 @@ function Cycle:map(map) end
 --- ```lua
 -----A chord sequence
 ---cycle("[c4, e4, g4] [e4, g4, b4] [g4, b4, d5] [b4, d5, f#5]")
+---```
+---```lua
 -----Arpeggio pattern with variations
 ---cycle("<c4 e4 g4> <e4 g4> <g4 b4 d5> <b4 f5>")
+---```
+---```lua
 -----Euclidean Rhythms
 ---cycle("c4(3,8) e4(5,8) g4(7,8)")
------Polyrhythm
----cycle("{c4 e4 g4 b4}%2, {f4 d4 a4}%4")
+---```
+---```lua
 -----Map custom identifiers to notes
 ---cycle("bd(3,8)"):map({ bd = "c4 #1" })
 --- ```