rearrange how workflow events are presented

Author: xabbuh

workflow/usage.rst

@@ -148,7 +148,7 @@ like this:
     The marking store type could be "multiple_state" or "single_state".
     A single state marking store does not support a model being on multiple places
     at the same time.
-    
+
 .. tip::
 
     The ``type`` (default value ``single_state``) and ``arguments`` (default value ``marking``)
@@ -189,35 +189,53 @@ Each step has three events that are fired in order:
 * An event for the workflow concerned;
 * An event for the workflow concerned with the specific transition or place name.
 
-The following events are dispatched:
+When a state transition is initiated, the events are fired in the following order:
 
-* ``workflow.guard``
-* ``workflow.[workflow name].guard``
-* ``workflow.[workflow name].guard.[transition name]``
+``workflow.guard``
+    Validate whether the transition is allowed at all (:ref:`see below <workflow-usage-guard-events>`).
 
-* ``workflow.leave``
-* ``workflow.[workflow name].leave``
-* ``workflow.[workflow name].leave.[place name]``
+    The three events being fired are:
 
-* ``workflow.transition``
-* ``workflow.[workflow name].transition``
-* ``workflow.[workflow name].transition.[transition name]``
+    * ``workflow.guard``
+    * ``workflow.[workflow name].guard``
+    * ``workflow.[workflow name].guard.[transition name]``
 
-* ``workflow.enter``
-* ``workflow.[workflow name].enter``
-* ``workflow.[workflow name].enter.[place name]``
+``workflow.leave``
+    The object is about to leave a place.
 
-* ``workflow.announce``
-* ``workflow.[workflow name].announce``
-* ``workflow.[workflow name].announce.[transition name]``
+    The three events being fired are:
 
-When a state transition is initiated, the events are fired in the following order:
+    * ``workflow.leave``
+    * ``workflow.[workflow name].leave``
+    * ``workflow.[workflow name].leave.[place name]``
+
+``workflow.transition``
+    The object is going through this transition.
+
+    The three events being fired are:
+
+    * ``workflow.transition``
+    * ``workflow.[workflow name].transition``
+    * ``workflow.[workflow name].transition.[transition name]``
 
-- guard: Validate whether the transition is allowed at all (:ref:`see below <workflow-usage-guard-events>`);
-- leave: The object is about to leave a place;
-- transition: The object is going through this transition;
-- enter: The object entered a new place. This is the first event where the object' is marked as being in the new place;
-- announce: Triggered once for each workflow that now is available for the object.
+``workflow.enter``
+    The object entered a new place. This is the first event where the object
+    is marked as being in the new place.
+
+    The three events being fired are:
+
+    * ``workflow.enter``
+    * ``workflow.[workflow name].enter``
+    * ``workflow.[workflow name].enter.[place name]``
+
+``workflow.announce``
+    Triggered once for each workflow that now is available for the object.
+
+    The three events being fired are:
+
+    * ``workflow.announce``
+    * ``workflow.[workflow name].announce``
+    * ``workflow.[workflow name].announce.[transition name]``
 
 Here is an example how to enable logging for every time a the "blog_publishing" workflow leaves a place::
 
@@ -231,7 +249,7 @@ Here is an example how to enable logging for every time a the "blog_publishing"
         {
             $this->logger = $logger;
         }
-    
+
         public function onLeave(Event $event)
         {
             $this->logger->alert(sprintf(
@@ -242,7 +260,7 @@ Here is an example how to enable logging for every time a the "blog_publishing"
                 implode(', ', $event->getTransition()->getTos())
             ));
         }
-    
+
         public static function getSubscribedEvents()
         {
             return array(
@@ -253,14 +271,14 @@ Here is an example how to enable logging for every time a the "blog_publishing"
 
 .. _workflow-usage-guard-events:
 
-Guard events
+Guard Events
 ~~~~~~~~~~~~
 
-There are a special kind of events called "Guard events". Their event listeners 
-are invoked every time a call to ``Workflow::can``, ``Workflow::apply`` or 
+There are a special kind of events called "Guard events". Their event listeners
+are invoked every time a call to ``Workflow::can``, ``Workflow::apply`` or
 ``Workflow::getEnabledTransitions`` is executed. With the guard events you may
-add custom logic to decide what transitions that are valid or not. Here is a list 
-of the guard event names. 
+add custom logic to decide what transitions that are valid or not. Here is a list
+of the guard event names.
 
 * ``workflow.guard``
 * ``workflow.[workflow name].guard``