Update docs

1 files changed, 136 insertions, 0 deletions

diff --git a/docs/basic-control.rst b/docs/basic-control.rst
new file mode 100644
index 0000000..f326a5d
--- /dev/null
+++ b/docs/basic-control.rst
@@ -0,0 +1,136 @@
+===========================================
+Basic attribute control and building states
+===========================================
+
+Once your fixtures are patched (see `<patching.rst>`_), you can set attributes
+sing ``at``.  For example, to set the intensity of ``my-dimmer`` to 100%::
+
+  (at my-dimmer 'intensity 100)
+
+If you leave out the attribute name, then ``intensity`` will be assumed::
+
+  (at my-dimmer 100)
+
+The available parameters are determined by the fixture definition (see
+`<new-fixture.rst>`_), and are referred to by their symbolic name (i.e. quote
+them with ``'``).  For example::
+
+  (at my-moving-light 'pan 32)
+  (at my-moving-light 'tilt 70)
+  (at my-moving-light 'zoom 60)
+
+Not all fixtures accept a single number.  For example, ``'colour`` (note: UK
+spelling) takes a colour object, which can be constructed using ``rgb`` or
+``cmy``.  Starlet (or rather,  the fixture definition code) is responsible for
+converting the colour to the native representation used by the fixture::
+
+  (at my-moving-light 'colour (rgb 80 23 25))
+
+You can set attributes for multiple fixtures at once::
+
+  (at spotCS spotSR spotSL 90)
+
+Or you can set attributes for a list of fixtures::
+
+  (define all-spots (list spotSL spotCS spotSR))
+  (at all-spots 90)
+
+You can mix individual fixtures and lists of fixtures.  However, you can only
+set one attribute (to one value) at a time.
+
+
+The selection
+=============
+
+When setting many attributes for one fixture, you can avoid typing the
+fixture name each time by using the selection.  To select a fixture, call
+``sel`` with the fixture(s) to select::
+
+  (sel my-dimmer)
+  (sel all-spots my-moving-light)
+
+If the fixture name is left out from subsequent calls to  ``at``, they will
+apply to the currently selected fixture(s).  To clear the selection, simply
+call ``(sel #f)`` or simply ``(sel)``::
+
+  (sel my-moving-light)
+  (at 100)
+  (at 'colour (rgb 80 23 25))
+  (at 'tilt 70)
+  (at 'pan 32)
+  (sel #f)
+
+The fixture display window (see `<fixture-display.rst>`_) will highlight the
+selection, and physical control devices (see `<physical-control.rst>`_) will
+affect the selected fixture(s).
+
+To see the contents of the selection, use ``(get-selection)``.
+
+
+State objects
+=============
+
+Attribute values must be stored within a state object.  When you set an
+attribute from the Guile REPL, the values will be stored in the programmer
+state.  You can examine the contents using ``state-source``, which returns
+the Scheme code corresponding to the state's contents::
+
+  (state-source programmer-state)
+
+You can also use ``print-state``, which just pretty-prints the output of
+``state-source``.  To reduce typing, you can use ``ps`` as a synonym for
+``programmer-state``::
+
+  (print-state ps)
+
+You can construct new states by wrapping your ``at`` forms inside
+``lighting-state``.  These state objects can be used inside cue lists
+(see `<cue-list.rst>`_), bound to variables etc::
+
+  (define my-state
+    (lighting-state
+      (at spotSR spotSL 50)
+      (at spotCS 100)))
+
+The programmer state has priority over everything else (e.g. cue list
+playbacks).  To avoid surprises, you should make sure that it's empty before
+trying to run a show.  The ``clear-state!`` procedure empties a state object
+of its contents, without deleting the state itself::
+
+  (clear-state! ps)
+
+There are some utility routines for handling states:
+
+* ``(state-empty? my-state)`` returns ``#t`` if ``my-state`` is empty,
+  otherwise ``#f``.
+* ``(remove-fixture-from-state! my-state spotCS)`` removes all attributes for
+  ``spotCS`` from ``my-state``.
+* ``(remove-fixtures-from-state! my-state (list spotCS spotSL))`` is the same,
+  but removes a list of fixtures from the state.
+* ``(remove-selection-from-programmer!)`` removes from the programmer any
+  attributes referring to fixtures which are currently selected.  It is
+  defined as follows::
+
+    (define (remove-selection-from-programmer!)
+      (remove-fixtures-from-state!
+        programmer-state
+        (get-selection)))
+
+
+Effects
+=======
+
+Attribute values aren't restricted to constants.  You can also provide a
+function, for example::
+
+  (let ((clock (make-clock)))
+    (at washM
+      (lambda ()
+        (* 50
+           (+ 1 (sin (* 2 (elapsed-time clock))))))))
+
+That's obvious quite complicated, so use the functions in module ``(starlet
+effects)`` instead.  For a sine wave once every 2 seconds (0.5 Hz) ranging
+between zero and 100%::
+
+  (at washM (sinewave 0.5 0 100))