Update docs

1 files changed, 121 insertions, 103 deletions

diff --git a/README.md b/README.md
index a81b2f1..351cd8d 100644
--- a/README.md
+++ b/README.md
@@ -3,147 +3,165 @@ Starlet: Stage lighting control in Lisp
 
 Starlet is an experimental Lisp-based domain-specific language (DSL) for
 theatrical lighting control.  It's based on
-[Guile](https://www.gnu.org/software/guile/) and sends its DMX output via
-[OLA](https://openlighting.org) to almost any type of lighting control
-interface - DMX, sACN, Art-Net etc.  Starlet also undertands MIDI, enabling you
-to control lights and cues with physical faders, knobs and buttons.
+[Guile](https://www.gnu.org/software/guile/) and uses the
+[Open Lighting Architecture](https://openlighting.org) to connect with almost
+any type of lighting control interface - USB DMX dongles, sACN, Art-Net etc.
+Starlet also undertands MIDI, enabling you to control lights and cues with
+physical faders, knobs and buttons.
+
+Rather than adding "scripting" as an afterthought, Starlet puts the full power
+of the programming language in the spotlight, allowing you to *program* your
+lights.
+
+Starlet is explicitly designed for *theatrical* lighting control, with cue
+lists, playbacks and multi-part cues being the centre of attention.  Automatic
+pre-setting of attributes ("auto move while dark") is the default.
+
+
+Video demonstration
+-------------------
 
 Click for a video demonstration:
-[![Video demonstration](screenshot.png)](https://vimeo.com/520547229)
+[![Video demonstration](docs/screenshot.png)](https://vimeo.com/520547229)
 
-With Starlet, a cue list looks like this:
+
+Getting started
+---------------
+
+Read [INSTALL.md](INSTALL.md) for basic setup instructions.
+
+
+Quick tour
+----------
+
+Lighting fixtures are referred to by names, rather than numbers:
 
 ```
-(define my-cue-list
-  (cue-list
-
-   (cue 1
-        (lighting-state (at dim1 '100))
-                        (at mh1 'pan 25))
-        #:fade-up 3
-        #:fade-down 5)
-
-   (cue 2
-        (lighting-state (at dim1 '50)
-                        (at dim2 '100)
-                        (at mh1 'pan 50))
-        #:fade-up 3
-        #:fade-down 1
-        #:down-delay 3)
-
-   (cue 3
-        (lighting-state #f)  ; blackout
-        #:fade-down 2
-```
+;; Patch some fixtures
+(patch-fixture! washL <generic-dimmer> 18))
+(patch-fixture! washM <generic-dimmer> 19))
+(patch-fixture! washR <generic-dimmer> 20))
+(patch-fixture! footlights <generic-dimmer> 23))
+(patch-fixture! moverL <robe-dl7s-mode1> 1 #:universe 4))
+(patch-fixture! moverR <robe-dl7s-mode1> 101 #:universe 4))
 
-Creating a playback object and running a cue list looks like this:
+;; Turn the footlights on at full intensity
+(at footlights 100)
 
+;; Turn on both moving lights and set colour
+(at moverL moverR 60)
+(at moverL moverR 'colour (make-colour-rgb 45 10 0))
 ```
-(define pb (make-playback #:cue-list my-cue-list))
 
-(cut-to-cue-number! pb 1)
-(go! pb)
-(go! pb)
-(go! pb)  ; and so on
+The fixture names are normal Scheme variables.  You can do usual things such
+as creating lists:
+
+```
+(define front-wash (list washL washM washR))
+(at front-wash 100)
 ```
 
-Lighting states can be prepared separately and assigned to variables:
+A lighting state is a collection of attribute values, and can be associated
+with a variable name:
 
 ```
-(define spooky-dungeon
+(define home-state
   (lighting-state
-    (at dimmer1 20)
-    (at dimmer2 20)
-    (at moving-light 70)
-    (at moving-light 'red 100)
-    (at moving-light 'green 10)
-    (at moving-light 'blue 12)))
+     (at footlights 100)
+     (at front-wash 100)
+     (at moverL moverR 100)
+     (at moverL moverR 'tilt 45)
+     (at moverL 'pan -15)
+     (at moverR 'pan 15)))
 ```
 
-You can use pre-prepared states in cues, even if some minor modifications are
-needed.  This makes it really easy to understand the contents of a cue without
-having to interpret a screenful of numbers:
+A cue is formed by associating a lighting state with a *transition effect*,
+such as a crossfade or snap (zero-time crossfade).  A cue list is simply a list
+of cues:
 
 ```
-(cue 57
-     (lighting-state (apply-state spooky-dungeon)
-                     (at follow-spot 100))
-     #:fade-up 3
-     #:fade-down 3)
+(cue-list
+
+  (cue 0.5
+       ;; Tab warmers
+       (lighting-state
+         (at washL washR 30)
+         (at washM 40))
+       (snap))
+
+  (cue 0.8
+       ;; Blackout
+       (lighting-state)
+       (crossfade 6))  ;; 6 second fade
+
+  (cue 1
+       ;; Act 1, Scene 1
+       (lighting-state
+         (at front-wash 80)
+         (at moverL 'colour (make-colour-cmy 2700/127 0 0)))
+	 (at moverL 25)
+       (crossfade 3))
+
+  (cue 2
+       (lighting-state
+         (at washM 100))
+       (crossfade 3 4))   ;; Separate up/down fade times
+
+  (cue 2.5
+       (lighting-state
+         (apply-state home-state)
+	 (at moverR 100)
+       (crossfade 2)))
+
+  ....
 ```
 
-Multi-part cues are supported.  Simply specify the fade parameters and which
-fixtures should be in the part:
+To 'execute' a cue list, load it into a *playback* object:
 
 ```
-(cue 64
-     (lighting-state (apply-state indoor-act1-general)
-     #:fade-up 3
-     #:fade-down 3
-
-     (cue-part (dim3
-                dim4
-                dim8
-                (list moving-light 'pan 'tilt))
-               #:down-time 2
-               #:down-delay 1))
+(define pb (make-playback #:cue-list my-cue-list))
+
+(cut-to-cue-number! pb 1)
+(go! pb)
 ```
 
 
-Everything from a simple dimmers to wacky multi-parameter fixtures are
-supported.  New fixture classes can be defined using some simple Scheme code.
-Patching fixtures looks like this:
+Documentation index
+-------------------
 
-```
-(patch-fixture! dimmer1 <generic-dimmer> 1))
-(patch-fixture! dimmer2 <generic-dimmer> 3))
-(patch-fixture! balcony-backlight1 <generic-dimmer> 18))
-(patch-fixture! balcony-backlight2 <generic-dimmer> 19))
-(patch-fixture! footlights <generic-dimmer> 23))
-;; Universe numbering starts at zero, matching OLA
-(patch-fixture! moving-light <robe-dl7s-mode1> 1 #:universe 4))
-```
+* [Patching fixtures](docs/patching.rst)
+* [The fixture display tool](docs/fixture-display.rst)
+* More to come:
+  - Basic control of attributes, building states
+  - Cue lists
+  - Defining a new fixture type
+  - Using physical controls via MIDI
 
-Note that the names of the fixtures are just normal Scheme variables.  They can
-be anything you like, and you're encouraged to make the names more descriptive
-than logical channel numbers, where appropriate.
 
+(Non-)warranty
+--------------
 
-Getting started
----------------
+Starlet is an experiment in progress, and there are no guarantees of any kind
+of stability (non-crashiness, consistency of language etc). Don't rely on
+syntax and interfaces staying the same, i.e. don't "git pull" right before a
+show!  Nevertheless, Starlet is reliable enough for adventurous types to
+consider using it for real shows.  Here it is running a show in front of a live
+(paying!) audience in February 2022:
 
-1. Install and set up [OLA](https://openlighting.org) for your lighting
-   environment.
-2. Install [Guile](https://www.gnu.org/software/guile/), if it's not already
-   there.  Version 3 is required.
-3. Install Starlet:
-    `meson build`, `ninja -C build` and `sudo ninja -C build install`
-4. Start olad if it's not already running: `olad -l 3` (in a separate
-   terminal).
-5. Run `guile`.
-6. Once in the Guile REPL, import some Starlet modules:
-    `(use-modules (starlet scanout) (starlet state) (starlet fixture-library
-    generic dimmer))`
-7. Patch a fixture:
-    `(patch-fixture! mydimmer <generic-dimmer> 1 #:universe 2)`
-   Replace 1 and 2 with the DMX address and universe (respectively) of a real
-   dimmer.
-8. Turn the dimmer on with `(at mydimmer 100)`
-9. Look in the _examples_ and _docs_ folders for more advanced ideas.
+![Starlet in use](docs/show.jpg)
 
 
 Related projects
 ----------------
 
-There are many stage lighting software projects, but most of them seem to
-concentrate on "disco style" effects and chases whereas Starlet is aimed more
-towards theatre shows.  Here are some that I found especially interesting:
-
+Here are some related projects that I found especially interesting.
+Amazingly, Starlet is not the only project to be found in the almost absurdly
+specialised category of "Lisp-based stage lighting systems"!
 
-* [Fivetwelve-CSS](https://github.com/beyondscreen/fivetwelve-css) DMX lighting
-  control using CSS. [Watch this video](https://www.youtube.com/watch?v=ani_MOZt5_c)
 * [Afterglow](https://github.com/Deep-Symmetry/afterglow) Clojure live coding
   environment using OLA
+* [Fivetwelve-CSS](https://github.com/beyondscreen/fivetwelve-css) DMX lighting
+  control using CSS. [Watch this video](https://www.youtube.com/watch?v=ani_MOZt5_c)
 * [QLC+](https://qlcplus.org/) the most popular open-source lighting control
   program