clarify build instructions re: sc-dev discussion

Author: Nathan Ho

README.md

@@ -1,5 +1,7 @@
 This repository a series of examples demonstrating how to write UGens for [SuperCollider](https://github.com/supercollider/supercollider) (not to be confused with quarks, which are libraries for the language). The [Writing Unit Generators](http://doc.sccode.org/Guides/WritingUGens.html) helpfile is a comprehensive tutorial. Chapter 25 of [the SuperCollider Book](http://www.supercolliderbook.net/) is also a useful resource, although the build instructions are outdated.
 
+There is a lot of conflicting material out there for UGen building. This is the official repository and should be the most up to date.
+
 Beyond this repository, the reader is encouraged to look at [sc3-plugins](https://github.com/supercollider/sc3-plugins) for more complex, real-world examples.
 
 ## Directory
@@ -11,42 +13,38 @@ Beyond this repository, the reader is encouraged to look at [sc3-plugins](https:
 
 ## Compiling
 
-Make a directory for the `cmake` build files:
+This is how you build one of the examples in this directory. The examples are kept separate with duplicated code so that you can simply copy out a directory to start your own ugen. **Currently, this build system is missing two things: Windows and supernova. Sorry, we're working on it.**
+
+CMake dumps a lot of files into your working directory, so you should always start by creating the `build/` directory:
 
 ```shell
-plugin-example/01-BoringMixer/$ mkdir build && cd build
-plugin-example/01-BoringMixer/build/$ cmake -DSC_PATH=/path/to/sc3source/ ..
+example-plugins/01a-BoringMixer/$ mkdir build
+example-plugins/01a-BoringMixer/$ cd build
 ```
 
-Here, `/path/to/sc3source/` is the path to a directory of the SuperCollider *source code*. The source code version should match your SuperCollider app version. Slight differences will probably be tolerated, but if they're too far apart you will get an "API version mismatch" error when you boot the server.
+Next, we run CMake and tell it where the SuperCollider headers are to be found:
+
+```shell
+example-plugins/01a-BoringMixer/build/$ cmake -DSC_PATH=/path/to/sc3source/ ..
+```
 
-The path should contain a file at `include/plugin_interface/SC_PlugIn.h`. If you get a warning that `SC_PlugIn.h` could not be found, then `SC_PATH` is not set correctly.
+Here, `/path/to/sc3source/` is the path to a directory of the SuperCollider *source code* (NOT the app itself). The source code version should match your SuperCollider app version. Slight differences will probably be tolerated, but if they're too far apart you will get an "API version mismatch" error when you boot the server.
 
-If no `SC_PATH` is provided, the build system assumes the SuperCollider include files in `/usr/include/SuperCollider/`.
+The path should contain a file at `include/plugin_interface/SC_PlugIn.h`. If you get a warning that `SC_PlugIn.h` could not be found, then `SC_PATH` is not set correctly. If no `SC_PATH` is provided, the build system assumes the SuperCollider include files in `/usr/include/SuperCollider/`.
 
-After setting `SC_PATH`, simply build using `make`:
+CMake will remember your `SC_PATH`, so you only need to run that once. After that, simply build using `make`:
 
 ```shell
-plugin-example/01-BoringMixer/build/$ make
+example-plugins/01-BoringMixer/build/$ make
 ```
 
-If compilation succeeds, on OSX this will produce a "shared library" file ending in `.scx`, and on Linux `.so`.
+This will produce a "shared library" file ending in `.scx`. On Linux, the extension is `.so`.
 
 ## Installing
 
 You can install each folder -- or the entire repository -- as you would a quark: `Quarks.gui` => `Install a folder`.
 
-Alternatively, you can copy, move, or symbolic link the folder into your Extensions folder. You can find out which one that is by evaluating
-
-```
-Platform.userExtensionDir
-```
-
-from within SuperCollider. Alternatively, you may install the plugin(s) system-wide by copying to
-
-```
-Platform.systemExtensionDir
-```
+Alternatively, you can copy, move, or symbolic link the folder into your Extensions folder. You can find out which one that is by evaluating `Platform.userExtensionDir` in sclang. You can install the plugin(s) system-wide by copying to `Platform.systemExtensionDir`.
 
 ## Development workflow