extend the reactor docs

doc/topics/reactor/index.rst

@@ -11,7 +11,8 @@ This system binds sls files to event tags on the master. These sls files then
 define reactions. This means that the reactor system has two parts. First, the
 reactor option needs to be set in the master configuration file.  The reactor
 option allows for event tags to be associated with sls reaction files. Second,
-these reaction files use highdata to define reactions to be executed.
+these reaction files use highdata (like the state system) to define reactions
+to be executed.
 
 Event System
 ============
@@ -32,7 +33,7 @@ Mapping Events to Reactor SLS Files
 
 The event tag and data are both critical when working with the reactor system.
 In the master configuration file under the reactor option, tags are associated
-with lists of reactor sls files (globs can be used for matching):
+with lists of reactor sls formulas (globs can be used for matching):
 
 .. code-block:: yaml
 
@@ -70,8 +71,58 @@ state.highstate. Similarly, a runner can be called:
 
     {% if data['data']['overstate'] == 'refresh' %}
     overstate_run:
-      runner.state.overstate
+      runner.state.over
     {% endif %}
 
 This example will execute the state.overstate runner and initiate an overstate
 execution.
+
+Understanding the Structure of Reactor Formulas
+===============================================
+
+While the reactor system uses the same data structure as the state system, this
+data does not translate the same way to operations. In state formulas 
+information is mapped to the state functions, but in the reactor system
+information is mapped to a number of available subsystems on the master. These
+systems are the `LocalClient` and the `Runners`. The `state declaration` field
+takes a reference to the function to call in each interface. So to trigger a
+salt-run call the `state declaration` field will start with `runner`, followed
+by the runner function to call. This means that a call to what would be on the
+command line `salt-run manage.up` will be `runner.manage.up`. An example of
+this in a reactor formula would look like this:
+
+.. code-block:: yaml
+
+    manage_up:
+      runner.manage.up
+
+If the runner takes arguments then they can be specified as well:
+
+.. code-block:: yaml
+
+    overstate_dev_env:
+      runner.state.over:
+        - env: dev
+
+Executing remote commands maps to the `LocalClient` interface which is used by
+the `salt` command. This interface more specifically maps to the `cmd_async`
+method inside of the `LocalClient` class. This means that the arguments passed
+are being passed to the `cmd_async` method, not the remote method. The field
+starts with `cmd` to use the `LocalClient` subsystem. The result is that to
+execute a remote command it looks like this:
+
+.. code-block:: yaml
+
+    clean_tmp:
+      cmd.cmd.run:
+        - tgt: '*'
+        - arg:
+          - rm -rf /tmp/*
+
+The `arg` option takes a list of arguments as they would be presented on the
+command line, so the above declaration is the same as running this salt
+command:
+
+    salt \* cmd.run 'rm -rf /tmp/*'
+
+