June documentation update (#161)

* add @dndrks' quickstart patches * add first round of grid guide patches * make sure patch images are sized correctly on mobile * Add links to download quickstart patches * Add another TT quickstart * Incorporate the rest of the grid legends into docs * optimize pngs with oxipng and pngquant * Flow and consistency pass
Dewb · Jun 18, 2023 · d4a2bb0 · d4a2bb0
1 parent 6f3ee23
commit d4a2bb0
Show file tree

Hide file tree

Showing 53 changed files with 208 additions and 105 deletions.
diff --git a/docs/content/extra.css b/docs/content/extra.css
@@ -1,16 +1,27 @@
 .module-image-sixhp {
-    margin: 0em 2rem 1.5rem 0em;
+    margin: 0rem 2rem 1.5rem 0rem;
     width: 9.5rem;
     height: auto;
     float: left;
 }
 
 .module-image-eighteenhp {
-    margin: 0em 2rem 1.5rem 0rem;
+    margin: 0rem 2rem 1.5rem 0rem;
     width: 28rem;
     height: auto;
 }
 
+.patch-image {
+    margin: 0rem;
+    width: 100% !important;
+}
+
+.patch-download-link:before {
+    content: "\01F4BE";
+    text-decoration: none;
+    padding: 4px;
+}
+
 /* Adjust module image sizes on mobile screens */
 @media (max-width: 32rem) {
     .module-image-sixhp {

diff --git a/docs/content/images/all-modules-50.png b/docs/content/images/all-modules-50.png
diff --git a/docs/content/images/all-modules.png b/docs/content/images/all-modules.png
diff --git a/docs/content/images/ansible-50.png b/docs/content/images/ansible-50.png
diff --git a/docs/content/images/ansible-earthsea-quickstart.png b/docs/content/images/ansible-earthsea-quickstart.png
diff --git a/docs/content/images/ansible-kria-grid-legend.png b/docs/content/images/ansible-kria-grid-legend.png
diff --git a/docs/content/images/ansible-kria-quickstart.png b/docs/content/images/ansible-kria-quickstart.png
diff --git a/docs/content/images/ansible-meadowphysics-quickstart.png b/docs/content/images/ansible-meadowphysics-quickstart.png
diff --git a/docs/content/images/ansible-quickstart-earthsea.png b/docs/content/images/ansible-quickstart-earthsea.png
diff --git a/docs/content/images/ansible-quickstart-kria.png b/docs/content/images/ansible-quickstart-kria.png
diff --git a/docs/content/images/ansible-quickstart-meadowphysics.png b/docs/content/images/ansible-quickstart-meadowphysics.png
diff --git a/docs/content/images/ansible.png b/docs/content/images/ansible.png
diff --git a/docs/content/images/connection-made.png b/docs/content/images/connection-made.png
diff --git a/docs/content/images/connection-menu.png b/docs/content/images/connection-menu.png
diff --git a/docs/content/images/earthsea-50.png b/docs/content/images/earthsea-50.png
diff --git a/docs/content/images/earthsea-grid-legend.png b/docs/content/images/earthsea-grid-legend.png
diff --git a/docs/content/images/earthsea-quickstart.png b/docs/content/images/earthsea-quickstart.png
diff --git a/docs/content/images/earthsea.png b/docs/content/images/earthsea.png
diff --git a/docs/content/images/grids-50.png b/docs/content/images/grids-50.png
diff --git a/docs/content/images/grids.png b/docs/content/images/grids.png
diff --git a/docs/content/images/meadowphysics-50.png b/docs/content/images/meadowphysics-50.png
diff --git a/docs/content/images/meadowphysics-grid-legend-links.png b/docs/content/images/meadowphysics-grid-legend-links.png
diff --git a/docs/content/images/meadowphysics-grid-legend-rules.png b/docs/content/images/meadowphysics-grid-legend-rules.png
diff --git a/docs/content/images/meadowphysics-grid-legend.png b/docs/content/images/meadowphysics-grid-legend.png
diff --git a/docs/content/images/meadowphysics-quickstart.png b/docs/content/images/meadowphysics-quickstart.png
diff --git a/docs/content/images/meadowphysics.png b/docs/content/images/meadowphysics.png
diff --git a/docs/content/images/teletype-50.png b/docs/content/images/teletype-50.png
diff --git a/docs/content/images/teletype-quickstart-1.png b/docs/content/images/teletype-quickstart-1.png
diff --git a/docs/content/images/teletype-quickstart-2.png b/docs/content/images/teletype-quickstart-2.png
diff --git a/docs/content/images/teletype-quickstart.png b/docs/content/images/teletype-quickstart.png
diff --git a/docs/content/images/teletype.png b/docs/content/images/teletype.png
diff --git a/docs/content/images/whitewhale-50.png b/docs/content/images/whitewhale-50.png
diff --git a/docs/content/images/whitewhale-grid-legend.png b/docs/content/images/whitewhale-grid-legend.png
diff --git a/docs/content/images/whitewhale-quickstart.png b/docs/content/images/whitewhale-quickstart.png
diff --git a/docs/content/images/whitewhale.png b/docs/content/images/whitewhale.png
diff --git a/docs/content/modules/ansible.md b/docs/content/modules/ansible.md
@@ -50,53 +50,74 @@ Ansible **IN 1** and **IN 2** jacks accept trigger/gate inputs. Their function d
 
 # Quickstart
 
-All of these quickstart examples use Ansible alongside modules from VCV's [Fundamental collection](https://vcvrack.com/Fundamental).
+All of these quickstart examples use Ansible alongside modules from VCV's [Free collection](https://vcvrack.com/Free).
 
 **Kria**
 
-![ansible quickstart kria screenshot](../images/ansible-quickstart-kria.png){: style="width: 40em;"}
+![ansible kria quickstart screenshot](../images/ansible-kria-quickstart.png){: class="patch-image" }
 *uses: Ansible, ADSR, VCA, VCO, AUDIO*
 
-- Connect Ansible to a grid
-- Patch **TR 1** to the GATE input of ADSR
-- Patch **CV 1** to the V/OCT input of VCO
-- Patch **CV 2** to the PWM input of VCO and add modulation using the attenuator
-- Patch ADSR's ENV and VCO's SQR to a VCA, then to AUDIO's L input
-- Press some pads in Kria's top row to create a rhythm on **TR 1**
-- Switch to the NOTE page on the grid and set notes for **CV 1**
-- Switch to Track 2 on the grid and set notes for **CV 2**'s modulation of the VCO's pulse width
-- Switch to the OCTAVE page on the grid and set different octaves for **CV 2**'s steps
+[ansible-kria-quickstart.vcv](../patches/ansible-kria-quickstart.vcv){: class="patch-download-link" }
+
+- Connect Ansible to a grid. (See [Making Connections](../../general/connections/#making-connections).)
+- The LED next to the **MODE** key should be *yellow-orange*. If it isn't, hold + release the **MODE** key to cycle through modes until Kria is active.
+- Patch **TR 1** to the GATE input of ADSR.
+- Patch **CV 1** to the V/OCT input of VCO.
+- Patch **CV 2** to the PWM input of VCO and add modulation using the attenuator.
+- Patch ADSR's ENV and VCO's SQR to a VCA, then to AUDIO's L input.
+- Press some pads in Kria's top row to create a rhythm on **TR 1**.
+- Switch to the NOTE page on the grid by pressing the 7th key on the bottom row, and set notes for **CV 1**.
+- Switch to Track 2 on the grid by pressing the 2nd key on the bottom row, and set notes for **CV 2**'s modulation of the VCO's pulse width.
+- Switch to the OCTAVE page on the grid by pressing the 8th key on the bottom row, and set different octaves for **CV 2**'s steps.
 
 **Meadowphysics**
 
-![ansible quickstart meadowphysics screenshot](../images/ansible-quickstart-meadowphysics.png){: style="width: 40em;"}
+![ansible meadowphysics quickstart screenshot](../images/ansible-meadowphysics-quickstart.png){: class="patch-image" }
 *uses: Ansible, ADSR, VCA, VCO, AUDIO*
 
-- Connect Ansible to a grid (hold + release **KEY 2** to move from Kria to Meadowphysics)
-- <kbd>Ctrl-Shift-click</kbd> (<kbd>Cmd-Shift-click</kbd> on Mac) **KEY 2** on Ansible's faceplate to open the [config interface](https://monome.org/docs/ansible/meadowphysics/#config)
-- Set the *voice mode* to *2 CV/TR voices*
-- Patch **TR 1** to the GATE input of ADSR
-- Patch **CV 1** to the V/OCT input of VCO
-- Patch **CV 2** to the PWM input of VCO and add modulation using the attenuator
-- Patch ADSR's ENV and VCO's SQR to a VCA, then to AUDIO's L input
-- Hold down any pad outside of column 1 in any row and press another pad in the same row to create a [count range](https://monome.org/docs/ansible/meadowphysics/#basic) -- if you're using a virtual grid, <kbd>Ctrl-click</kbd> (<kbd>Cmd-click</kbd> on Mac) will hold a pressed pad until you release <kbd>Ctrl</kbd> / <kbd>Cmd</kbd>
+[ansible-meadowphysics-quickstart.vcv](../patches/ansible-meadowphysics-quickstart.vcv){: class="patch-download-link" }
+
+- Connect Ansible to a grid. (See [Making Connections](../../general/connections/#making-connections).)
+- Hold + release the **MODE** key to move from Kria to Meadowphysics. The LED next to the **MODE** key should be *white*.
+- <kbd>Ctrl-Shift-click</kbd> (<kbd>Cmd-Shift-click</kbd> on Mac) **KEY 2** on Ansible's faceplate to open the [config interface](https://monome.org/docs/ansible/meadowphysics/#config).
+- Set the *voice mode* to *2 CV/TR voices*.
+- Patch **TR 1** to the GATE input of ADSR.
+- Patch **CV 1** to the V/OCT input of VCO.
+- Patch **CV 2** to the PWM input of VCO and add modulation using the attenuator.
+- Patch ADSR's ENV and VCO's SQR to a VCA, then to AUDIO's L input.
+- Hold down any pad outside of column 1 in any row and press another pad in the same row to create a [count range](https://monome.org/docs/ansible/meadowphysics/#basic) -- if you're using a virtual grid, <kbd>Ctrl-click</kbd> (<kbd>Cmd-click</kbd> on Mac) will hold a pressed pad until you release <kbd>Ctrl</kbd> / <kbd>Cmd</kbd>.
 
 **Earthsea**
 
-![ansible quickstart earthsea screenshot](../images/ansible-quickstart-earthsea.png){: style="width: 40em;"}
+![ansible earthsea quickstart screenshot](../images/ansible-earthsea-quickstart.png){: class="patch-image" }
 *uses: Ansible, ADSR (2x), VCO (2x), VCA MIX, AUDIO*
 
-- Connect Ansible to a grid (hold + release **KEY 2** to move from Meadowphysics to Earthsea)
-- Hold the bottom-left pad on the grid to enter the [voice allocation interface](https://monome.org/docs/ansible/earthsea/#voice-allocation) and set the first two outputs to active on both *pattern* and *live*
-- Instantiate two ADSR's, two VCO's
-- Set one of the VCO's FREQ to 1/2 the FREQ of the other
-- Patch **TR 1** and **TR 2** to the GATE input of each ADSR
-- Patch **CV 1** and **CV 2** to the V/OCT input of each VCO
-- Patch one output of each VCO to the first two inputs of VCA MIX
-- Patch each ADSR's ENV output to the corresponding CV inputs of VCA MIX
-- Patch the VCA MIX's MIX output to AUDIO's L input
-- [Arm a pattern recorder](https://monome.org/docs/ansible/earthsea/#pattern-recording)
-- Record some chord shapes on the grid and play the pattern back
+[ansible-earthsea-quickstart.vcv](../patches/ansible-earthsea-quickstart.vcv){: class="patch-download-link" }
+
+- Connect Ansible to a grid. (See [Making Connections](../../general/connections/#making-connections).)
+- Hold + release the **MODE** key to move from Kria to Meadowphysics and then Earthsea.  The LED next to the **MODE** key should be *yellow-white*.
+- Hold the bottom-left pad on the grid to enter the [voice allocation interface](https://monome.org/docs/ansible/earthsea/#voice-allocation) and set the first two outputs to active on both *pattern* and *live*.
+- Instantiate two ADSR and two VCO modules.
+- Set one of the VCO's FREQ to 1/2 the FREQ of the other.
+- Patch **TR 1** and **TR 2** to the GATE input of each ADSR.
+- Patch **CV 1** and **CV 2** to the V/OCT input of each VCO.
+- Patch one output of each VCO to the first two inputs of VCA MIX.
+- Patch each ADSR's ENV output to the corresponding CV inputs of VCA MIX.
+- Patch the VCA MIX's MIX output to AUDIO's L input.
+- [Arm a pattern recorder](https://monome.org/docs/ansible/earthsea/#pattern-recording) by pressing the key in the third row of the leftmost column.
+- Record some chord shapes on the grid. Hit the pattern record arm key again to stop recording and play the pattern back.
+
+# Grid reference
+
+When using Kria, the bottom row of the grid controls the track/mode/view, and is consistent across modes (with a couple of exceptions.) The rest of the grid contents depend on the mode you're in. See [the hardware documentation](https://monome.org/docs/ansible/kria/) for more details.
+
+![ansible kria grid legend screenshot](../images/ansible-kria-grid-legend.png){: class="patch-image" }
+
+[ansible-kria-grid-legend.vcv](../patches/ansible-kria-grid-legend.vcv){: class="patch-download-link" } *(requires [Stoermelder Glue](https://library.vcvrack.com/Stoermelder-P1))*
+
+For Meadowphysics, see the [grid legends for standalone Meadowphysics](../meadowphysics/#grid-reference).
+
+For Earthsea, see the [grid legend for standalone Earthsea](../earthsea/#grid-reference). Ansible Earthsea is identical except the last two functions, Slew and Portamento, are replaced by the [Runes](https://monome.org/docs/ansible/earthsea/#runes) and [Voice Allocation](https://monome.org/docs/ansible/earthsea/#voice-allocation) screens.
 
 # Further reading
 

diff --git a/docs/content/modules/earthsea.md b/docs/content/modules/earthsea.md
@@ -9,7 +9,7 @@ Without a grid connection it will not produce any output, but once a sequence ha
 
 # CV 1-3 knobs and outputs
 
-The **CV 1-3** jacks each output a 0 V to 10 V signal that is initially controlled by the paired knob. When using a [shape memory gesture](https://monome.org/docs/earthsea/#shape-memories) on the grid, the previously stored CV values will be recalled, subject to the [slew settings](https://monome.org/docs/earthsea/#shape-memories). These values are also displayed on the bottom three rows of a connected grid.
+The **CV 1-3** jacks each output a 0 V to 10 V signal that is initially controlled by the paired knob. When using a [shape memory gesture](https://monome.org/docs/earthsea/#shape-memories) on the grid, the previously stored CV values will be recalled, subject to the [slew settings](https://monome.org/docs/earthsea/#slew). These values are also displayed on the bottom three rows of a connected grid.
 
 # EDGE and POS outputs
 
@@ -20,26 +20,42 @@ The **CV 1-3** jacks each output a 0 V to 10 V signal that is initially controll
 
 Earthsea does not have any inputs.
 
+# Grid reference
+
+Earthsea uses the leftmost column for mode controls, leaving the entire rest of the grid as a playing surface (called the *keymap*.) Notes in the keymap are arranged by semitones on the x-axis and by fourths on the y-axis. The most recently played key is highlighted; the pitch of this key will be present on the *POS* output in V/oct format.
+
+Various forms of information are shown on the grid as horizontal bars underneath the keymap. When the sequencer is playing, the top row will display the progress of the loop. The bottom three rows show the current value of CV 1-3.
+
+![earthsea grid legend screenshot](../images/earthsea-grid-legend.png){: class="patch-image" }
+
+[earthsea-grid-legend.vcv](../patches/earthsea-grid-legend.vcv){: class="patch-download-link" } *(requires [Stoermelder Glue](https://library.vcvrack.com/Stoermelder-P1))*
+
 # Quickstart
-This quickstart example uses Earthsea alongside modules from VCV's [Fundamental collection](https://vcvrack.com/Fundamental).
 
-![earthsea quickstart screenshot](../images/earthsea-quickstart.png){: style="width: 40em;"}
+This quickstart example uses Earthsea alongside modules from VCV's [Free collection](https://vcvrack.com/Free).
+
+![earthsea quickstart screenshot](../images/earthsea-quickstart.png){: class="patch-image" }
 *uses: Earthsea, ADSR, VCO, VCF, VCA MIX, AUDIO*
 
-- Connect Earthsea to a grid
-- Patch Earthsea's **EDGE** to ADSR's GATE input
-- Patch Earthsea's  **POS** to VCO's V/OCT input
-- Patch VCO's SQR output to VCF's IN
-- Patch VCF's LPF output to IN 1 of VCA MIX
-- Patch ADSR's ENV output to CV 1 of VCA MIX
-- Patch VCA MIX's MIX output to AUDIO's L input
-- Patch Earthsea's **CV 1** to the PWM input of VCO and add modulation using the attenuator above the input
-- Patch Earthsea's **CV 2** to the CUT input of VCF and add modulation using the attenuator above the input
-- [Arm a pattern recorder](https://monome.org/docs/earthsea/#patterns), record a melody on the grid, and play the pattern back
-- Add voltage to Earthsea's **CV 1** and **CV 2** and perform a [triples shape-memory](https://monome.org/docs/earthsea/#shape-memories) to store it
-- Repeat the previous step for additional values and **triples** *shape-memories*
-- As the pattern plays, switch between *shape-memories*
-- [Add slew to each shape-memory](https://monome.org/docs/earthsea/#slew)
+[earthsea-quickstart.vcv](../patches/earthsea-quickstart.vcv){: class="patch-download-link" }
+
+- Connect Earthsea to a grid. (See [Making Connections](../../general/connections/#making-connections).)
+- Patch Earthsea's **EDGE** output to ADSR's GATE input.
+- Patch Earthsea's  **POS** output to VCO's V/OCT input.
+- Patch VCO's SQR output to VCF's IN.
+- Patch VCF's LPF output to IN 1 of VCA MIX.
+- Patch ADSR's ENV output to CV 1 of VCA MIX.
+- Patch VCA MIX's MIX output to AUDIO's L input.
+- Patch Earthsea's **CV 1** output to the PWM input of VCO and add modulation using the attenuator above the input.
+- Patch Earthsea's **CV 2** output to the CUT input of VCF and add modulation using the attenuator above the input.
+- [Arm a pattern recorder](https://monome.org/docs/earthsea/#patterns) by pressing the key in the third row of the first column. Record a melody by pressing keys on the grid in columns 2-16. Hit the third key in the first column again to start playing the pattern back.
+
+If you have a hardware grid and can make simultaneous multi-finger gestures, you can try the shape memory feature:
+
+- Add voltage to Earthsea's **CV 1** and **CV 2** by turning their knobs clockwise, and perform a [shape-memory gesture](https://monome.org/docs/earthsea/#shape-memories) to store those settings and start editing the new shape.
+- Repeat the previous step for additional values and **triples** *shape-memories*.
+- As the pattern plays, switch between *shape-memories*.
+- [Add slew to a shape memory CV channel](https://monome.org/docs/earthsea/#slew) by holding down the 7th key in the first column and turning the CV 1 knob.
 
 # Further reading
 

diff --git a/docs/content/modules/grids.md b/docs/content/modules/grids.md
@@ -40,5 +40,7 @@ Locking and holding keys can work together. For example, to adjust loop length i
 
 # Theme and protocol options
 
-...
+From the right-click menu, you can change the *Theme* of a individual grid instance to differentiate it from other grids in your patch, or just for personal style preference. The four themes are *loosely* based on the various eras of grid controller hardware. They don't have identical brightness curves and some themes may be more satisfying than others for certain modules and modes.
+
+There is also a menu option to change the protocol the grid is simulating. This might be useful if you have an older-protocol hardware grid and you want to practice with the same non-varibright behavior on a virtual grid, or if you are developing new module firmware and want to test against older, non-varibright grids. Most users should leave this set to *Mext (varibright)*.
 
diff --git a/docs/content/modules/meadowphysics.md b/docs/content/modules/meadowphysics.md
@@ -5,6 +5,8 @@ Meadowphysics generates eight interrelated gate sequences. Without a grid connec
 
 [Read the introduction to the hardware module](http://monome.org/docs/meadowphysics/#introduction).
 
+The trigger outputs from Meadowphysics are suitable for firing off ADSR envelopes, pinging LPGs or filters, clocking or resetting sequencers, triggering drum modules or samplers, or whatever complex events you have in your patch. Meadowphysics was originally designed as a script-triggering companion to [Teletype](../teletype), so try using them together once you're familiar with both.
+
 # Main outputs
 
 Outputs 1-8 produce gates at 8 V according to the counters on rows 1-8 of the grid. Outputs follow the pulse length of the clock; the built-in clock has a 50% duty cycle.
@@ -21,11 +23,13 @@ VCV Rack will remember the current working memory in your patch, but the **PRESE
 
 # Quickstart
 
-This quickstart example uses Meadowphysics alongside modules from VCV's [Fundamental collection](https://vcvrack.com/Fundamental). Note that Meadowphysics was originally designed as a script-triggering companion to [Teletype](../teletype), so this example won't showcase the full potential of the module. Once you become familiar with Teletype, we encourage you to revisit this module!
+This quickstart example uses Meadowphysics alongside modules from VCV's [Free collection](https://vcvrack.com/Free). 
 
-![meadowphysics quickstart screenshot](../images/meadowphysics-quickstart.png){: style="width: 40em;"}
+![meadowphysics quickstart screenshot](../images/meadowphysics-quickstart.png){: class="patch-image" }
 *uses: Meadowphysics, VCO (2x), VCA MIX (2x), FADE, LFO, AUDIO*
 
+[meadowphysics-quickstart.vcv](../patches/meadowphysics-quickstart.vcv){: class="patch-download-link" }
+
 - Connect Meadowphysics to a grid
 - Patch the four outputs of each VCO to the four inputs of each ADSR
 - Patch the eight **TR** outputs of Meadowphysics to the CV inputs of each ADSR
@@ -36,6 +40,14 @@ This quickstart example uses Meadowphysics alongside modules from VCV's [Fundame
 - Hold down any pad outside of column 1 in any row and press another pad in the same row to create a [count range](https://monome.org/docs/ansible/meadowphysics/#basic)
 - Change the [rule](https://monome.org/docs/meadowphysics/#rules--ranges) for each range
 
+# Grid reference
+
+![meadowphysics grid legend screenshot](../images/meadowphysics-grid-legend.png){: class="patch-image" }
+![meadowphysics grid legend links screenshot](../images/meadowphysics-grid-legend-links.png){: class="patch-image" }
+![meadowphysics grid legend rules screenshot](../images/meadowphysics-grid-legend-rules.png){: class="patch-image" }
+
+[meadowphysics-grid-legends.vcv](../patches/meadowphysics-grid-legends.vcv){: class="patch-download-link" } *(requires [Stoermelder Glue](https://library.vcvrack.com/Stoermelder-P1))*
+
 # Further reading
 
 * Meadowphysics [hardware documentation](http://monome.org/docs/meadowphysics/)