From f7405d27f2e197315259366ca95fef0125ce4b53 Mon Sep 17 00:00:00 2001
From: Christian Flothmann <christian.flothmann@xabbuh.de>
Date: Sun, 18 Jun 2017 16:16:59 +0200
Subject: [PATCH] rearrange how workflow events are presented

---
 workflow/usage.rst | 81 ++++++++++++++++++++++++++++------------------
 1 file changed, 50 insertions(+), 31 deletions(-)

diff --git a/workflow/usage.rst b/workflow/usage.rst
index 4f87191d1f1..014560cec7d 100644
--- a/workflow/usage.rst
+++ b/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,49 +189,68 @@ 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 dispatched 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>`).
+
+    The three events being dispatched are:
+
+    * ``workflow.guard``
+    * ``workflow.[workflow name].guard``
+    * ``workflow.[workflow name].guard.[transition name]``
+
+``workflow.leave``
+    The object is about to leave a place.
+
+    The three events being dispatched are:
 
-* ``workflow.leave``
-* ``workflow.[workflow name].leave``
-* ``workflow.[workflow name].leave.[place name]``
+    * ``workflow.leave``
+    * ``workflow.[workflow name].leave``
+    * ``workflow.[workflow name].leave.[place name]``
 
-* ``workflow.transition``
-* ``workflow.[workflow name].transition``
-* ``workflow.[workflow name].transition.[transition name]``
+``workflow.transition``
+    The object is going through this transition.
 
-* ``workflow.enter``
-* ``workflow.[workflow name].enter``
-* ``workflow.[workflow name].enter.[place name]``
+    The three events being dispatched are:
 
-* ``workflow.announce``
-* ``workflow.[workflow name].announce``
-* ``workflow.[workflow name].announce.[transition name]``
+    * ``workflow.transition``
+    * ``workflow.[workflow name].transition``
+    * ``workflow.[workflow name].transition.[transition name]``
 
-When a state transition is initiated, the events are fired in the following order:
+``workflow.enter``
+    The object entered a new place. This is the first event where the object
+    is marked as being in the new place.
 
-- 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.
+    The three events being dispatched 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 dispatched 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::
 
     use Psr\Log\LoggerInterface;
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     use Symfony\Component\Workflow\Event\Event;
-    
+
     class WorkflowLogger implements EventSubscriberInterface
     {
         public function __construct(LoggerInterface $logger)
         {
             $this->logger = $logger;
         }
-    
+
         public function onLeave(Event $event)
         {
             $this->logger->alert(sprintf(
@@ -242,7 +261,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 +272,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``