Update README for v3

ref #788

README.md

@@ -19,11 +19,11 @@ Scale Workshop can play any kind of microtonal scale, such as equal temperaments
 
 ### Can I play and hear my scale?
 
-Yes, the built-in synth allows you to play your scales within the web browser. If your browser supports web MIDI then you can use a connected MIDI device to play notes. Otherwise you can use your computer keyboard (e.g. a QWERTY keyboard) as an isomorphic keyboard controller to hear your scales. You can also play on a touch device using the 'Touch Keyboard' feature.
+Yes, the built-in synth allows you to play your scales within the web browser. If your browser supports web MIDI then you can use a connected MIDI device to play notes. Otherwise you can use your computer keyboard (e.g. a QWERTY keyboard) as an isomorphic keyboard controller to hear your scales. You can also play on a touch device using the 'Virtual Keyboard' feature.
 
 ### Can I use my computer keyboard as a piano
 
-Yes, go to the Synth tab and select *Piano-style layers* as the *Keyboard mode*. There are two options: ASDF for white keys and QWERTY for black keys **or** QWERTY for white keys and digits for black keys with another set of keys an octave lower starting from ZXCV with ASDF as the black keys. There's also a third option for keyboards that have an extra key between the left shift and Z. When using *Piano-style layers* make sure that the number of key colors matches the size of your scale. Some scale generators such as *Moment of Symmetry* allow you to auto-generate the key colors.
+Yes, go to the Synth tab and select *Piano-style layers* as the *Keyboard mode*. There are two options: ASDF for white keys and QWERTY for black keys **or** QWERTY for white keys and digits for black keys with another set of keys an octave lower starting from ZXCV with ASDF as the black keys. There's also a third option for keyboards that have an extra key between the left shift and Z. When using *Piano-style layers* make sure that you have defined colors for the intervals in your scale (e.g. `700. white`). Some scale generators such as *Moment of Symmetry* allow you to auto-generate the key colors.
 
 ### Can I use Scale Workshop to tune up other synths?
 
@@ -39,15 +39,82 @@ Scale data should be entered in to the large text field labeled ‘Scale data’
 * To specify an interval in cents, include a . in the line e.g. `701.9` or `1200.`
 * To specify n steps out of m-EDO, write it in the format `n\m`
 * To specify arbitrary EDJI values, write it in the format `n\m<p/q>`
-* To specify a decimal ratio, include a , in the line e.g. `1,5` or `3,14159`
+* To specify a decimal ratio, include an `e` n the line e.g. `1.5e` or `14e-1`
 * To specify a [monzo](https://en.xen.wiki/w/Monzo) enclose the exponents inside a square bracket and a closing angle bracket e.g. `[-1 1 0>`
-* You can combine intervals using + e.g. `4/3 + 1.23`
+* To specify an [FJS](https://en.xen.wiki/w/Functional_Just_System) interval spell out the quality (`M` for major), the degree (`3` for third) and the inflections (`^5` for 5-over) e.g. `M3^5`
+* To specify an [FJS](https://en.xen.wiki/w/Functional_Just_System) absolute pitch spell out the nominal (e.g. `E`), the accidental (`b` for flat), the octave (e.g. `4`) and the inflection (`v5` for 5-under) e.g. `Eb4v5`
+* You can stack fractions using `*` e.g. `32/27 * 81/80`
+* To go the other way use `%` e.g. `27/16 % 81/80`
+* You can stack cents, equal temperaments, monzos and FJS using `+` e.g. `7\12 + 1.96`
+* Yo go the other way use `-` e.g. `P5 - 1.96`
+* To mix fractions and cents use `*~` and `%~` e.g. `4/3 *~ 1.23`
 
 No need to enter `0.` or `1/1` on the first line as your scale is automatically assumed to contain this interval.
 
 The interval on the final line is assumed to be your interval of equivalence (i.e. your octave or pseudo-octave a.k.a. equave).
 
-Don't add any other weird data to a line. Don't try to mix decimals with ratios (e.g. `2/1.5`). Scale Workshop will try to gracefully ignore any rubbish that you put in, but it's very possible that weird stuff will happen.
+### How do I add comments?
+
+Everything between `(*` and `*)` is ignored:
+
+```ocaml
+(* This is my comment about this scale *)
+3/2
+2 (* Plain numbers are fractions: This is 2/1 not 2.0c *)
+```
+
+### How do I attach labels to the intervals?
+
+Use strings of characters surrounded by wither single or double quotes:
+
+```ocaml
+9/8 "my tone"
+3/2 'fif'
+P8 "The most perfect of octaves ♥"
+```
+
+### How do I add colors to the intervals?
+
+Use CSS colors or RGB values:
+
+```ocaml
+10/9 yellow
+4/3 #fae123 "my fourth"
+1200. 'my octave' #fff
+```
+
+### How do I reduce my fractions?
+
+Tell Scale Workshop to simplify the fractions with a `simplify` command at the bottom of the scale or `defer simplify` at the top:
+
+```ocaml
+defer simplify
+
+9/8
+10/8
+11/8
+12/8
+13/8
+14/8
+15/8
+16/8
+```
+
+### How do I keep my scale organized as I build it?
+
+Tell Scale Workshop to sort everything and coalesce nearby intervals (here less than 10 cents apart) with a `defer organize(10.)` at the top:
+
+```ocaml
+(* Sort the result and coalesce nearby intervals. *)
+defer organize(10.)
+
+(* These intervals are automatically octave-reduced and inserted in the correct order. *)
+11
+1/11
+
+(* Complex intervals are eliminated if there's a simpler fraction within 10 cents. *)
+eulerGenus(3*3*3 * 5*5 * 7, 3*5)
+```
 
 ### Can I copy and paste the contents of a Scala file (.scl) directly into the 'Scale data' field?
 
@@ -64,19 +131,19 @@ However you can always use duplicate lines in your tuning in order to skip any k
 
 ### Can I undo/redo?
 
-Use your browser's Back/Forward navigation buttons to undo/redo changes to your tuning.
+Use the ↺ button near the "Scale data" header to undo and the ↻ button to redo changes to your tuning.
 
 ### How can I share my tunings with a collaborator?
 
 Use *Export current settings > Share scale* found on the third column of the *Build Scale* tab. The given URL can be copied and pasted to another person. When they open the link they will see a Scale Workshop page with your scale already tuned in.
 
 ### How can I save my work for later?
 
-You can bookmark the current page to save your work for later. This works because your tuning data is stored within the bookmarked URL.
+Share the scale URL to yourself through *Export current settings > Share scale*. **Warning**: Compared to Scale Workshop 2 bookmarking the current URL doesn't work anymore and only takes you to the front page.
 
-### When I export a tuning, I get a weird filename, why?
+### When I export a tuning, I get nothing, why?
 
-Exporting a file with the correct filename is not supported in Safari (iOS and macOS). You can try to use Firefox, Chrome or Opera instead.
+File export from Safari (iOS and macOS) does not work. Cause unknown. You can try to use Firefox, Chrome or Opera instead.
 
 ### Can I run this software offline?
 
@@ -95,6 +162,7 @@ Please [create a bug report](https://github.com/xenharmonic-devs/scale-workshop/
 * Stable releases are at https://scaleworkshop.plainsound.org/
 * Slow-cycle stable releases are at https://sevish.com/scaleworkshop/
 * Nightly snapshots are deployed to https://scaleworkshop.lumipakkanen.com/
+* Version 3 release candidates are at https://sw3.lumipakkanen.com/
 
 #### Archived versions
 * Version 2.1.0 https://sevish.com/scaleworkshop-dev/
@@ -202,7 +270,10 @@ MIT, see [LICENCE](LICENSE) for details.
 
 ## Related projects
 
+* The domain-specific language including tempering utilities [sonic-weave](https://github.com/xenharmonic-devs/sonic-weave)
 * MOS scales generated using [moment-of-symmetry](https://github.com/xenharmonic-devs/moment-of-symmetry)
-* Scales tempered using [temperaments](https://github.com/xenharmonic-devs/temperaments)
 * MIDI I/O using [xen-midi](https://github.com/xenharmonic-devs/xen-midi)
 * Basic utilities from [xen-dev-utils](https://github.com/xenharmonic-devs/xen-dev-utils)
+* Lattice tools [ji-lattice](https://github.com/xenharmonic-devs/ji-lattice)
+* Synth for making sound [sw-synth](https://github.com/xenharmonic-devs/sw-synth)
+* Keyboard layout [isomorphic-qwerty](https://github.com/xenharmonic-devs/isomorphic-qwerty)