Add GettingStarted and KeyCommands articles. Add a few FAQ entries. Various revisions to other articles.

Communities.md

@@ -3,20 +3,25 @@
 
 - [Website](https://vcvrack.com/)
 - [Forum](https://community.vcvrack.com/)
+- [GitHub issue tracker](https://github.com/VCVRack/Rack/issues)
 - [Facebook page](https://www.facebook.com/vcvrack/)
 - [Twitter](https://twitter.com/vcvrack)
-- [Github issue tracker](https://github.com/VCVRack/Rack/issues)
 - [Facebook user group](https://www.facebook.com/groups/vcvrack/)
-- [Facebook developer group](https://www.facebook.com/groups/2035785263299933/)
-- [Facebook French user group](https://www.facebook.com/groups/2069785583250645/)
-- [Facebook Italian user group](https://www.facebook.com/groups/vcvitalia/)
-- [Youtube](https://www.youtube.com/c/VCVRack)
 - [Instagram](https://www.instagram.com/vcvrack/)
+- [Twitch](https://twitch.com/vcvrack)
+- [YouTube](https://www.youtube.com/c/VCVRack)
+- [Bandcamp (Switched On Rack label)](https://switchedonrack.bandcamp.com/)
+- [SoundCloud](https://soundcloud.com/vcvrack)
+
+## Unofficial communities
+
 - [Discord](https://discord.gg/wxa89Mh)
 - [Reddit](https://www.reddit.com/r/vcvrack/)
-- [IRC](http://webchat.freenode.net?channels=%23VCVRack)
+- [Facebook developer group](https://www.facebook.com/groups/2035785263299933/)
 - [Patchstorage](https://patchstorage.com/platform/vcv-rack/)
 - [MuffWiggler thread](https://www.muffwiggler.com/forum/viewtopic.php?t=186899)
 - [KVR Audio thread](https://www.kvraudio.com/forum/viewtopic.php?f=23&t=489230)
+- [Facebook Italian user group](https://www.facebook.com/groups/vcvitalia/)
+- [Facebook French user group](https://www.facebook.com/groups/2069785583250645/)
+- [IRC](https://webchat.freenode.net/#VCVRack)
 - [Hispasonic thread (Spanish)](https://www.hispasonic.com/foros/foro-vcv-rack/516252)
-- [Switched On Rack collaboration albums](https://switchedonrack.bandcamp.com/)

Core.md

@@ -43,6 +43,7 @@ Note: Using multiple Audio modules is experimental and may crash Rack or render
 Most DAWs avoid this feature entirely by restricting audio to a single input and a single output device for stability reasons, but if using multiple audio devices in Rack works with your configuration, more power to you!
 
 
+<a id="MIDI"></a>
 ## MIDI Interfaces
 
 Each MIDI interface module (described below) supports the following drivers.

FAQ.md

@@ -1,5 +1,13 @@
 # FAQ
 
+<a id="acronym"></a>
+## What does "VCV" stand for?
+
+There is no official meaning of the name "VCV", but users have suggested "Virtual Control Voltage" or "Voltage Controlled Virtualization".
+These are good guesses, but "VCV" was chosen simply because it is easy to remember and type.
+
+
+<a id="userfolder"></a>
 ## Where is the "Rack user folder"?
 
 The Rack user folder stores data readable/writable by Rack.
@@ -11,21 +19,18 @@ You can open it by choosing `Help > Open user folder` in the Rack [menu bar](Men
 
 When running Rack in development mode, it is your current working directory instead.
 
-## Will Rack be ported to iOS or Android?
 
-It is not planned. There are many issues with such a project.
+<a id="plugin"></a>
+## I know what modules are, but what is a VCV Rack plugin?
 
-- Technical:
-	- Tablet and phone users don't normally use mice, so a touch driver would need to be written. If GLFW is still used, [touch support](https://github.com/glfw/glfw/issues/42) would need to be added to the library.
-	- There is no user-managed filesystem on iOS, and forcing users to mess with the filesystem is bad UX on Android, so plugin folders and patch files would need to be managed entirely by Rack itself.
-	- RtAudio and RtMidi don't have iOS Core Audio/MIDI or Android HAL/OpenSL ES backends, so they would need to be added and tested.
-	- Apple does not allow apps distributed through the store to download and execute code, so either all plugins would need to be included in the distributable, or it could only be distributed on jailbroken iOS devices, which is an absurd user requirement.
+A plugin is a single unit of software loaded by VCV Rack that can contain multiple modules.
+Plugins are loaded from `<Rack user folder>/plugins-v*`.
+
+When Rack v2 is released, you will be able to add individual modules to your personal module library, rather than entire plugins, so the concept of a "plugin" will soon be hidden from end users and exposed only to developers.
+VCV also plans to offer individual commercial modules for sale, as well as discounted bundles of multiple modules.
 
-- Business:
-	- Such a port would be expensive to develop, so it would need to be sold commercially. Some plugins (proprietary, GPL, etc) would need special licensing agreements in order to be included in the package. Some plugins would increase the cost of the product if included in the package. Others would simply be omitted from the third-party plugin collection.
-	- The friction for a developer to build and test their plugins on iOS/Android is significantly higher than the three desktop OS's, which may decrease their willingness to develop Rack plugins.
-	- When serving an app on the App Store or Google Play, Apple and Google are not obligated to continue serving an app and may remove it at will or change policies on a whim that can disrupt VCV's business model. This would place a large risk upon VCV.
 
+<a id="daws"></a>
 ## Is VCV Rack available as a VST/AU/AAX plugin for DAWs?
 
 VCV Rack can be fully considered a DAW itself rather than a "synthesizer plugin", so Rack is a standalone application.
@@ -36,22 +41,8 @@ The standalone version of Rack v2 will continue to be free/open-source.
 
 Follow the [Rack development blog](https://community.vcvrack.com/t/rack-development-blog/5864) for the most up-to-date Rack development news.
 
-## What was VCV Bridge?
-
-[VCV Bridge](https://github.com/VCVRack/Bridge) was an experimental project for transferring audio/MIDI between VCV Rack and another DAW via a VST2/AU plugin.
-It relied on [inter-process communication (IPC)](https://en.wikipedia.org/wiki/Inter-process_communication) between Rack (server) and the DAW plugin (client), similar to [ReWire](https://en.wikipedia.org/wiki/ReWire_(software_protocol)).
-Because real-time IPC of audio cannot be achieved on non-[real-time operating systems](https://en.wikipedia.org/wiki/Real-time_operating_system), it was never intended as more than a fun experiment, and the project was concluded a month after development started.
-One could say the experiment "failed", but its purpose was primarily to see how much it would fail.
-The conclusion was that it was not reliable enough for the majority of users.
-VCV Bridge was deprecated in July 2018 and is now unsupported.
-The Bridge VST2/AU plugin was removed in Rack 1.0 (although it can be found in [earlier Rack packages](https://vcvrack.com/downloads/)), and the Bridge audio/MIDI driver will be removed in Rack 2.0.
-
-## Does VCV Rack work with touch screens?
-
-Rack's window library GLFW does not support [touch input](https://github.com/glfw/glfw/issues/42) yet, so Rack relies on the operating system to control the mouse cursor using the touch screen.
-This means that multi-touch gestures do not work.
-However, you can disable "View > Lock cursor while dragging" in the menu bar to prevent Rack from grabbing the mouse cursor when interacting with knobs.
 
+<a id="performance"></a>
 ## How do I improve performance of VCV Rack?
 
 VCV Rack simulates a modular synthesizer where each module itself can be a challenge to simulate on a modern computer, whether it's a virtual analog model with hundreds of analog components to simulate, or a digital module designed to be run on an ARM microprocessor similar to your smart phone's.
@@ -114,3 +105,46 @@ Note that some tips have trade-offs or might not provide any benefit for your si
 	- Although Rack's [System Requirements](Installing.html#system-requirements) suggest that computers as old as 2013 can run Rack, it is recommended to use a computer from 2016 or later that is designed for gaming.
 	There are many gaming laptop and desktop computers on the market for as low as $300, the price of an average hardware Eurorack module.
 	Unfortunately, Apple's MacBook Air and older MacBook Pro models are not designed for gaming (despite their high price!) and are therefore not recommended for VCV Rack.
+
+
+<a id="touch"></a>
+## Does VCV Rack work with touch screens?
+
+Rack's window library GLFW does not support [touch input](https://github.com/glfw/glfw/issues/42) yet, so Rack relies on the operating system to control the mouse cursor using the touch screen.
+This means that multi-touch gestures do not work.
+However, you can disable "View > Lock cursor while dragging" in the menu bar to prevent Rack from grabbing the mouse cursor when interacting with knobs.
+
+
+<a id="res"></a>
+## Rack fails to launch on Mac with the error "Rack’s resource directory "n_…/res" does not exist"
+
+Follow the instructions in [this comment](https://github.com/VCVRack/Rack/issues/1623#issuecomment-551374084).
+
+
+<a id="bridge"></a>
+## What was VCV Bridge?
+
+[VCV Bridge](https://github.com/VCVRack/Bridge) was an experimental project for transferring audio/MIDI between VCV Rack and another DAW via a VST2/AU plugin.
+It relied on [inter-process communication (IPC)](https://en.wikipedia.org/wiki/Inter-process_communication) between Rack (server) and the DAW plugin (client), similar to [ReWire](https://en.wikipedia.org/wiki/ReWire_(software_protocol)).
+Because real-time IPC of audio cannot be achieved on non-[real-time operating systems](https://en.wikipedia.org/wiki/Real-time_operating_system), it was never intended as more than a fun experiment, and the project was concluded a month after development started.
+One could say the experiment "failed", but its purpose was primarily to see how much it would fail.
+The conclusion was that it was not reliable enough for the majority of users.
+VCV Bridge was deprecated in July 2018 and is now unsupported.
+The Bridge VST2/AU plugin was removed in Rack 1.0 (although it can be found in [earlier Rack packages](https://vcvrack.com/downloads/)), and the Bridge audio/MIDI driver will be removed in Rack 2.0.
+
+
+<a id="mobile"></a>
+## Will Rack be ported to iOS or Android?
+
+It is not planned. There are many issues with such a project.
+
+- Technical:
+	- Tablet and phone users don't normally use mice, so a touch driver would need to be written. If GLFW is still used, [touch support](https://github.com/glfw/glfw/issues/42) would need to be added to the library.
+	- There is no user-managed filesystem on iOS, and forcing users to mess with the filesystem is bad UX on Android, so plugin folders and patch files would need to be managed entirely by Rack itself.
+	- RtAudio and RtMidi don't have iOS Core Audio/MIDI or Android HAL/OpenSL ES backends, so they would need to be added and tested.
+	- Apple does not allow apps distributed through the store to download and execute code, so either all plugins would need to be included in the distributable, or it could only be distributed on jailbroken iOS devices, which is an absurd user requirement.
+
+- Business:
+	- Such a port would be expensive to develop, so it would need to be sold commercially. Some plugins (proprietary, GPL, etc) would need special licensing agreements in order to be included in the package. Some plugins would increase the cost of the product if included in the package. Others would simply be omitted from the third-party plugin collection.
+	- The friction for a developer to build and test their plugins on iOS/Android is significantly higher than the three desktop OS's, which may decrease their willingness to develop Rack plugins.
+	- When serving an app on the App Store or Google Play, Apple and Google are not obligated to continue serving an app and may remove it at will or change policies on a whim that can disrupt VCV's business model. This would place a large risk upon VCV.

GettingStarted.md

@@ -0,0 +1,45 @@
+# Getting Started
+
+VCV Rack is virtual modular synthesizer platform for Windows/Mac/Linux that simulates Eurorack modules, in addition to original modules that go beyond hardware.
+
+Once [VCV Rack](https://vcvrack.com/Rack) is installed and launched for the first time (see [Installing](Installing.html)), you will see a rack with a template patch.
+
+![Template patch](images/templatepatch.png)
+
+The [*VCV Audio*](Core.html#audio) module is the portal between the virtual and physical world.
+It sends audio from VCV Rack to your speakers and audio device (e.g. sound card or external audio interface).
+It can also receive audio from microphones and your audio device's inputs.
+
+1\. To set up *VCV Audio*, click its display to set the audio driver, device, and optionally sample rate and block size.
+
+[*VCV MIDI-CV*](Core.html#midi-cv) converts MIDI notes from a MIDI device (such as a keyboard or controller) to virtual voltages in Rack.
+It can also use your computer's keyboard as a basic MIDI keyboard.
+
+2\. Use the QWERTY and ZXCVB rows of your keyboard to generate MIDI notes, which are converted to 1V/oct and gate signals.
+
+You can interact with knobs, sliders, and buttons on modules with your mouse.
+
+3\. Drag knobs up/down to rotate. Hold Ctrl (Cmd on Mac) while dragging to fine-tune. Right-click knobs to edit, and double-click to initialize.
+Try changing the frequency of [*VCV VCO-1*](https://library.vcvrack.com/Fundamental/VCO) by adjusting its FREQ knob while playing notes.
+
+All signals in VCV Rack are virtual voltages, but they can classified roughly into a few categories:
+
+- **Audio** signals are audible if played through your speakers. They contain *audio-rate* frequencies typically between 20Hz to 20kHz.
+- **CV** (control voltage) signals can modulate parameters of other modules. For example, an LFO (low-frequency oscillator) can oscillate the pitch of a VCO (voltage-controlled oscillator) or the volume level of a VCA (voltage-controlled oscillator).
+- **1V/oct** (1 volt per octave) signals are CV signals that represent a pitch or note. In this standard, an increase of 1V increases the pitch by 1 octave. Since there are 12 semitones in an octave, an increase of 1/12 V increases the pitch by 1 semitone.
+- **Gate** signals carry an on/off signal. 0V represents off, and a positive voltage (typically 10V) represents on. For example, a gate signal can turn on when a key is pressed and off when the key is released.
+- **Trigger** signals are short gates (usually around 1 millisecond) that cause an event to occur, such as a percussion hit.
+- **Clock** signals are triggers played at a steady tempo, in order to set the musical timing of your patch.
+
+Signals can be connected from module to module via patch cables, and you can even send a signal types for interesting results.
+
+4\. Drag from port to port to create a cable. Move or delete an existing cable by dragging one of its plugs. Stack multiple cables on outputs by holding Ctrl (Cmd on Mac) and dragging from an output.
+
+With VCV Rack, you can build and configure your ideal modular synthesizer rack.
+VCV Rack includes several built-in modules, and you can expand your module collection by installing more online.
+
+5\. Drag a module to move it around the rack. Right-click a module to open its context menu. Right-click on an empty rack space to launch the Module Browser to add new modules.
+
+If you are new to modular synthesizers, we recommend that you learn how to use most of the modules included with VCV Rack and push them to their limits before installing other VCV or third-party modules.
+The included modules are more capable than they might appear, and learning them in depth will give you more power and understanding when learning more modules later.
+When you are ready, browse for more modules on the [VCV Library](https://library.vcvrack.com/).

Installing.md

@@ -1,5 +1,6 @@
 # Installing & Running
 
+<a id="sysreq"></a>
 ## System Requirements
 
 VCV Rack is free software, so you may simply download and run the software to see if it works.
@@ -14,6 +15,7 @@ However, if Rack does not run or you are experiencing performance issues, make s
 - RAM: 1GB
 - Disk space: 1GB
 
+<a id="installing"></a>
 ## Installing Rack
 
 Download Rack on the [VCV Rack website](https://vcvrack.com/).
@@ -55,6 +57,7 @@ However, some plugin maintainer make plugin builds available in the "Releases" s
 Note: The "major" version number (e.g. the `1` in `v1.2.3`) must match the major version number of Rack. See [ABI/API Version](Version.html).
 
 
+<a id="running"></a>
 ## Running Rack
 
 ### Running on Mac

Issues.md

@@ -1,6 +1,6 @@
 # Bugs and Features
 
-VCV offers technical support of commercial VCV plugins by emailing contact@vcvrack.com.
+VCV offers technical support of commercial VCV plugins by emailing <contact@vcvrack.com>.
 
 For technical support of VCV Rack, open-source VCV plugins, and third-party plugins, refer to the correct category below.
 

KeyCommands.md

@@ -0,0 +1,38 @@
+# Key Commands
+
+*In this document, Ctrl should be replaced with Command (⌘) on Mac.*
+
+## Global commands
+
+Key commands documented in Rack's [menu bar](MenuBar.html) are not documented here.
+
+- **Enter** or **right-click on rack**: Launch the Module Browser to add modules to the rack.
+- **F1**: Open Rack manual in your browser.
+- **F3**: Show/hide CPU meter.
+- **F11**: Enter/exit fullscreen.
+- **Ctrl+0**: Set rack zoom level to 100%.
+- **Ctrl+-**: Zoom out.
+- **Ctrl+=**: Zoom in.
+- **Scroll**: Scroll rack vertically.
+- **Shift+scroll**: Scroll rack horizontally.
+- **Middle mouse button drag**: Pan rack view.
+- **Arrow keys**: Pan rack view. You can use Ctrl, Shift, or Ctrl+shift to change the speed of scrolling.
+- **Ctrl+V**: Pastes a new module at the cursor position, from the module context menu "Preset > Copy" or Ctrl+C.
+
+## Module commands
+
+You must hover your mouse over a module to issue key commands for it.
+Key commands documented in the module context menu are not documented here.
+
+- **Right click** on panel: Open module context menu.
+- **Click and drag** on panel: Drag module in the rack.
+- **Ctrl+click and drag** on panel: Force-drag module. This moves other modules in order to place the dragged module.
+- **Backspace** or **Delete**: Delete module from the rack. You can hold this key while moving your mouse to delete multiple modules.
+
+## Parameter commands
+
+A parameter can be a knob, slider, button, or other custom component that controls a module value.
+
+- **Click and drag vertically**: Adjust value. You can use Ctrl or Ctrl+shift to change the speed of adjustment.
+- **Right-click**: Open parameter context menu. You can enter an exact value into the text field.
+- **Double-click**: Reset to default value.

Makefile

@@ -6,7 +6,7 @@ BUILDDIR      = _build
 
 all: html
 
-run: html
+serve: html
 	http-server _build/html
 
 upload: html

Manifest.md

@@ -304,6 +304,15 @@ Serves only extremely basic functions, like inverting, max, min, multiplying by
 A one-line summary of the module's purpose.
 Displayed in the Module Browser tooltip.
 
+## `.modules[].keywords`
+*String. Optional.*
+
+String of words, aliases, and abbreviations describing the module to improve searchability in the VCV Library and Rack's module browser.
+It is *not* necessary to copy tags from `modules[].tags`.
+Not displayed to the user.
+
+Example: `"24dB 12dB V2164 LM13700 OTA multi-mode analog"`
+
 ## `modules[].manualUrl`
 *String. Optional.*
 

MenuBar.md

@@ -82,7 +82,7 @@ Due to [simultaneous multithreading](https://en.wikipedia.org/wiki/Simultaneous_
 
 ### Login
 Logs into your VCV account registered at [vcvrack.com](https://vcvrack.com/).
-Email [contact@vcvrack.com](mailto:contact@vcvrack.com) for account assistance.
+Email <contact@vcvrack.com> for account assistance.
 
 ### Update all
 Updates and downloads all new plugins and plugin versions added to your VCV account.

Migrate2.md

@@ -52,7 +52,3 @@ perl -i -pe 's/(\w+)_INPUT\b/INPUT_$1/g' src/*
 perl -i -pe 's/(\w+)_OUTPUT\b/OUTPUT_$1/g' src/*
 perl -i -pe 's/(\w+)_LIGHT\b/LIGHT_$1/g' src/*
 ```
-perl -i -pe 's/app::ABI/ABI/g' src/**/* include/**/*
-
-
-perl -i -pe 's/AudibleInstruments\.hpp/plugin.hpp/g' src/*

Panel.md

@@ -21,6 +21,7 @@ Design recommendations from VCV:
 	- Use an inverted background for output ports (see Fundamental VCO-1 panel above).
 	- Labels should succinctly state the purpose of knobs, switches, and ports.
 - Roughly follow the graphical density and text sizes of Fundamental modules.
+	- Text should be readable at 100% on a non-high-DPI monitor.
 
 
 Do not use other people's intellectual property (IP) without their permission.

QuickStart.md

@@ -1,32 +0,0 @@
-# Quick Start
-
-*TODO Update for v1*
-
-Once Rack is installed and launched *(see [Installing](Installing.html))*, you will see an empty rack with a toolbar.
-
-![Initial patch](images/initialpatch.png)
-
-Add a module by right-clicking on an empty space on the rack or by pressing `<enter>`.
-Select the [Core](Core.html) plugin and then Audio to connect Rack to an audio device on your computer.
-
-![Module Browser](images/modulebrowser.png)
-
-You can move the module by clicking and dragging an empty space on its panel.
-Select an audio driver and device by clicking on Audio's digital display.
-
-![Audio interface patch](images/audiopatch.png)
-
-Continue adding more modules, such as VCO-1 and Mixer from the Fundamental plugin.
-Connect a cable from the SIN output of the VCO-1 to the input of the Mixer by clicking and dragging from one of the ports.
-
-Connect another cable from the Mixer output to the first channel of Audio's "output" section, and add another cable to the second channel.
-You can stack multiple cables on output ports by dragging from an input to an output, or by Ctrl-clicking (Cmd-clicking on MacOS) from an output to an input.
-
-![First patch](images/firstpatch.png)
-
-Finally, adjust Mixer's first channel or main volume by clicking and dragging the fader or knob upward/downward.
-
-At this point, you are ready to learn the rest of the Fundamental modules to build your own unique patches.
-I personally recommend that you attempt to push the Fundamental modules to their limits before moving on to other official or third-party plugins.
-They are more capable than they might appear, and learning how to use them effectively will give you more power and understanding when installing more modules later.
-When you are ready, install more plugins using the [VCV Library](https://library.vcvrack.com/).

README.md

@@ -10,14 +10,14 @@ Your PR will be accepted if it is a net positive benefit to readers.
 
 ## Building
 
-Install [Sphinx](http://www.sphinx-doc.org/en/stable/) 1.8.1. Newer versions do not generate formulas and image tags properly.
+Install [Sphinx](http://www.sphinx-doc.org/en/stable/).
 
-	pip install sphinx==1.8.1
+	pip install sphinx
 	pip install sphinx_rtd_theme
 
-Install [recommonmark](https://github.com/rtfd/recommonmark) 0.4.0.
+Install [recommonmark](https://github.com/rtfd/recommonmark).
 
-	pip install recommonmark==0.4.0
+	pip install recommonmark
 
 Build with
 

_templates/layout.html

@@ -0,0 +1,12 @@
+{% extends "!layout.html" %}
+
+{% block extrahead %}{{ super() }}
+	<script async src="https://www.googletagmanager.com/gtag/js?id=AW-719768977"></script>
+	<script>
+	window.dataLayer = window.dataLayer || [];
+	function gtag(){dataLayer.push(arguments);}
+	gtag('js', new Date());
+	gtag('config', 'AW-719768977');
+	gtag('config', 'G-5BXGFPG2S3');
+	</script>
+{% endblock %}

conf.py

@@ -7,6 +7,7 @@ source_encoding = 'utf-8'
 
 extensions = [
     'sphinx.ext.mathjax',
+    'recommonmark',
 ]
 
 from recommonmark.parser import CommonMarkParser
@@ -94,7 +95,7 @@ epub_exclude_files = ['search.html']
 
 
 def setup(app):
-    app.add_stylesheet("overrides.css")
+    app.add_css_file("overrides.css")
     app.add_config_value('recommonmark_config', {
         'enable_auto_toc_tree': True,
         'auto_toc_tree_section': "Table of Contents",

index.rst

@@ -12,9 +12,11 @@ Edit this manual at https://github.com/VCVRack/manual.
 
    FAQ.md
    Installing.md
+   GettingStarted.md
    MenuBar.md
    Core.md
    Polyphony.md
+   KeyCommands.md
 
 .. toctree::
    :maxdepth: 1
@@ -42,3 +44,9 @@ Edit this manual at https://github.com/VCVRack/manual.
    Issues.md
    Communities.md
    About.md
+
+
+..
+   This somehow triggers Mathjax to be loaded on all Markdown pages.
+.. math::
+