Merge lp:~clint-fewbar/upstart-cookbook/clarify-complex-start-stop into lp:upstart-cookbook

[Clint Byrum]

This rewrites the section to be more comprehensible and better reflect the way that complex conditions are handled.

[lp:~clint-fewbar/upstart-cookbook/clarify-complex-start-stop]

130. By Clint Byrum on 2012-01-27

bolding important phrase

=== modified file 'upstart_cookbook.rst'
--- upstart_cookbook.rst	2012-01-19 18:36:17 +0000
+++ upstart_cookbook.rst	2012-01-27 07:15:29 +0000
@@ -7172,18 +7172,20 @@
 ---------------------------------------
 
 
-The ``and`` and ``or`` operators allowed with ``start on`` and ``stop on`` do
-not work intuitively: operands to the right of either operator are only
-evaluated once and state information is then discarded. This can lead to jobs
-with complex ``start on`` or ``stop on`` conditions not behaving as expected
+The ``and`` and ``or`` operators allowed with ``start on`` and ``stop on``
+do not work intuitively: operands to the right of either operator are only
+evaluated when the specified event is emitted. This can lead to jobs with
+complex ``start on`` or ``stop on`` conditions not behaving as expected
 when restarted. For example, if a job specifies the following condition::
 
   start on A and (B or C)
 
-When "``A``" and "``B``" become true, the condition is satisfied so the job
-will be run. However, if the job ends and subsequently "``A``" and "``C``"
-become true, the job will *not* be re-run even though the condition is
-satisfied.
+When the events "``A``" and "``B``" are processed, the condition is
+satisfied so the job will be run. If the job fails to start, or is stopped
+later, there is no guarantee that "``A``" will be emitted again, and the
+fact that it happened before **is not known to upstart**. Meanwhile,
+"``C``" or "``B``" may ocurr, and the job will *not* be transitioned
+back to a start goal, until "``A``" is emitted again.
 
 Advice
 ~~~~~~