Some docs on runners

doc/ref/runners/index.rst

@@ -31,6 +31,81 @@ invoked with the following command:
 
     # salt-run test.foo
 
+Runners have several options for controlling output.
+
+Any ``print`` statement in a runner is automatically also
+fired onto the master event bus where. For example:
+
+.. code-block:: python
+
+    def a_runner(outputter=None, display_progress=False):
+        print('Hello world')
+        ...
+
+The above would result in an event fired as follows:
+
+.. code-block:: bash
+
+    Event fired at Tue Jan 13 15:26:45 2015
+    *************************
+    Tag: salt/run/20150113152644070246/print
+    Data:
+    {'_stamp': '2015-01-13T15:26:45.078707',
+     'data': 'hello',
+      'outputter': 'pprint'}
+
+
+A runner may also send a progress event, which is displayed to the user during
+runner execution and is also passed across the event bus if the ``display_progress``
+argument to a runner is set to True.
+
+A custom runner may send its own progress event by using the
+``__jid_event_.fire_event()`` method as shown here:
+
+.. code-block:: python
+
+    if display_progress:
+        __jid_event__.fire_event({'message': 'A progress message', 'progress')
+
+The above would produce output on the console reading: ``A progress message``
+as well as an event on the event similar to:
+
+.. code-block:: bash
+
+    Event fired at Tue Jan 13 15:21:20 2015
+    *************************
+    Tag: salt/run/20150113152118341421/progress
+    Data:
+    {'_stamp': '2015-01-13T15:21:20.390053',
+     'message': "A progress message"}
+
+A runner could use the same approach to send an event with a customized tag
+onto the event bus by replacing the second argument (``progress``) with
+whatever tag is desired. However, this will not be shown on the command-line
+and will only be fired onto the event bus.
+
+Synchronous vs. Asynchronous
+----------------------------
+
+A runner may be fired asychronously which will immediately return control. In
+this case, no output will be display to the user if ``salt-run`` is being used
+from the command-line. If used programatically, no results will be returned.
+If results are desired, they must be gathered either by firing events on the
+bus from the runner and then watching for them or by some other means.
+
+.. note::
+
+    When running a runner in asyncronous mode, the ``--progress`` flag will
+    not deliver output to the salt-run CLI. However, progress events will
+    still be fired on the bus.
+
+In synchronous mode, which is the default, control will not be returned until
+the runner has finished executing.
+
+
+
+
+
 To add custom runners, put them in a directory and add it to
 :conf_master:`runner_dirs` in the master configuration file.