Issue #1565: Behaviour on internally-raised events described

plugins/org.yakindu.sct.doc.user/src/user-guide/statechart_language.textile

@@ -878,14 +878,23 @@ p=. Reaction effect syntax
 
 Example: When a transition or local reaction specified as @ev1 [x > 3] / x += 1; notify(x); raise ev2@ is executed, it increments variable _x_ by 1, calls the _notify_ operation with _x_ as parameter, and raises event _ev2_.
 
+
 h4(#raising-and-processing-an-event). Raising and processing an event
 
-For the syntax of event raising, see "Raising an event":#raising-an-event.
-For the syntax of event declaration, see "Events":#events.
+For the syntax of event raising, see section ""Raising an event"":#raising-an-event.
+For the syntax of event declaration, see section ""Events"":#events.
+
+When a reaction raises an event, the subsequent behaviour of the state machine is highly dependent on the execution scheme, selected by either the "@CycleBased":#statechart_language_cyclebased (default) or the "@EventDriven":#statechart_language_eventdriven annotation. In short:
+* In the _cycle-based execution scheme_, the raised event will be added to the events that are processed by the current run-to-completion step. However, it will only be visible "downstream" in the run cycle, i.e. active states that have not yet been executed can take the event into account. When the run cycle is completed, the event will cease to exist. It can thus not be processed in any subsequent run-to-completion step.
+* In the _event-driven execution scheme_, the raised event will be added to an event queue. As a consequence, it will not be visible "downstream" in the current run cycle. Instead, the event will trigger a run cycle on its own. In that run-to-completion step, it will be visible everywhere.
+
+The following sections will give a more in-depth view on these different behaviours.
 
-When a reaction raises an event, please consider two important points:
-* The event exists in the current run-to-completion step (RTC) only and thus can be dealt with during the rest of that particular RTC only.
-* Orthogonal regions are executed sequentially and in a deterministic order.
+h5(#processing_an_event_in_the_cycle-based_execution_scheme). Processing an event in the cycle-based execution scheme
+
+As explained above, an event that has been raised using the "_raise_ statement":#raising-an-event exists in the current run-to-completion step only and thus can be dealt with during the rest of that particular run-to-completion step only.
+
+Please also note that orthogonal regions are executed sequentially and in a deterministic order.
 
 This has remarkable consequences on where an event is "visible" and where it is not. Let's say we have a state machine at a certain point in time where _n_ orthogonal regions are active. The regions _r<sub>i</sub>_ have a defined execution order: _r<sub>1</sub>_ → _r<sub>2</sub>_ → … → _r<sub>n-1</sub>_ → _r<sub>n</sub>_.
 
@@ -916,7 +925,16 @@ p(#fig_region-priorities).
 
 p=. Region priorities
 
-Not being able to raise an event and process it in "earlier" regions is a restriction you can overcome using variables. The idea is to set a "communication variable" to a certain value in a region that is processed "later". During the next RTC the earlier region could act on the variables value.
+Not being able to raise an event and process it in "earlier" regions is a restriction you can overcome using variables. The idea is to set a "communication variable" to a certain value in a region that is processed "later". During the next RTC the earlier region could act on the variables value. Another option – and in many cases the better on, is to change to the event-driven execution scheme.
+
+h5(#processing_an_event_in_the_event-driven_execution_scheme). Processing an event in the event-driven execution scheme
+
+As explained above, an event that has been raised using the "_raise_ statement":#raising-an-event is appended to an event queue, and thus it is not visible in the current run-to-completion step (RTC). Since in the event-driven execution scheme an RTC always processes a single event at a time, only the event that caused the RTC to execute in the first place remains visible "downstream" in the current RTC.
+
+The raised event will, however, trigger an RTC on its own. In that RTC, it will be visible to all regions, no matter of their execution order. The execution order as explained in the preceeding section still applies, but it is of less importance in the event-driven approach.
+
+
+
 
 h2(#types). Types