eng: Update EARS syntax

The document used the EARS syntax from 2009 which slightly changed in
2016, see "Listens Learned (8 Lessons Learned Applying EARS)".  The
optional pre-conditions moved to the state-driven pattern.  This refined
syntax fits better to the action requirements.

Update #3715.

2 files changed, 64 insertions, 41 deletions

diff --git a/eng/req/howto.rst b/eng/req/howto.rst
index 8481214..8d146a3 100644
--- a/eng/req/howto.rst
+++ b/eng/req/howto.rst
@@ -283,30 +283,41 @@ an :ref:`SpecTypeInterfaceForwardDeclarationItemType` item.
 Action Requirements
 -------------------
 
-Use :ref:`SpecTypeActionRequirementItemType` items to specify and validate
-directive calls.  Action requirements are a generator for event-driven
-requirements which should be written in the following :ref:`syntax
+:ref:`SpecTypeActionRequirementItemType` items may be used to specify and
+validate directive calls.  They are a generator for event-driven requirements.
+Event-driven requirements should be written in the following :ref:`syntax
 <ReqEngSyntax>`:
 
-    *When* <optional preconditions> <trigger>, the <system name> shall
-    <system response>.
-
-The <optional preconditions> are the pre-conditions of the action requirement.
-The <trigger> is the action of the action requirement.  The post-conditions
-should provide a list of the <system name> shall <system response> clauses.
-Each transition in the transition map is an event-driven requirement composed
-of the pre-condition states, the action, and the post-condition states defined
-by the map entry.
-
-Use ``CamelCase`` for the pre-condition names, post-condition
-names, and state names.  The more conditions a directive has, the shorter
-should be the names.  The transition map may be documented as a table and more
-conditions need more table columns.  Use item attribute references in the
-``text`` attributes.  This allows context-sensitive substitutions.
-
-Link the action requirement item to an :ref:`SpecTypeInterfaceFunctionItemType`
-or an :ref:`SpecTypeInterfaceMacroItemType` item using the
-:ref:`SpecTypeInterfaceFunctionLinkRole`.
+    **While** <pre-condition 0>, **while** <pre-condition 1>, ..., **while**
+    <pre-condition *n*>, **when** <trigger>, the <system name> shall <system
+    response>.
+
+The list of *while* <pre-condition *i*> clauses for *i* from 1 to *n* in the
+EARS notation is generated by *n* pre-condition states in the action
+requirement item, see the ``pre-condition`` attribute in the
+:ref:`SpecTypeActionRequirementItemType`.
+
+The <trigger> in the EARS notation is defined for an action requirement item by
+the link to an :ref:`SpecTypeInterfaceFunctionItemType` or an
+:ref:`SpecTypeInterfaceMacroItemType` item using the
+:ref:`SpecTypeInterfaceFunctionLinkRole`.  The code provided by the
+``test-action`` attribute defines the action code which should invoke the
+trigger directive in a particular set of pre-condition states.
+
+Each post-condition state of the action requirement item generates a <system
+name> shall <system response> clause in the EARS notation, see the
+``post-condition`` attribute in the :ref:`SpecTypeActionRequirementItemType`.
+
+Each entry in the transition map is an event-driven requirement composed of the
+pre-condition states, the trigger defined by the link to a directive, and the
+post-condition states.  The transition map is defined by a list of
+:ref:`SpecTypeActionRequirementTransition` descriptors.
+
+Use ``CamelCase`` for the pre-condition names, post-condition names, and state
+names in action requirement items.  The more conditions a directive has, the
+shorter should be the names.  The transition map may be documented as a table
+and more conditions need more table columns.  Use item attribute references in
+the ``text`` attributes.  This allows context-sensitive substitutions.
 
 Pre-Conditions
 ^^^^^^^^^^^^^^
@@ -322,20 +333,20 @@ syntax for directive object identifier parameters:
         test-code: |
           ctx->id = 0xffffffff;
         text: |
-          The ${../if/directive:/params[0]/name} parameter shall not be
+          While the ${../if/directive:/params[0]/name} parameter is not
           associated with a thing.
       - name: ClassA
         test-code: |
           ctx->id = ctx->class_a_id;
         text: |
-          The ${../if/directive:/params[0]/name} parameter shall be associated with a
-          class A thing.
+          While the ${../if/directive:/params[0]/name} parameter is associated
+          with a class A thing.
       - name: ClassB
         test-code: |
           ctx->id = ctx->class_b_id;
         text: |
-          The ${../if/directive:/params[0]/name} parameter shall be associated with a
-          class B thing.
+          While the ${../if/directive:/params[0]/name} parameter is associated
+          with a class B thing.
       test-epilogue: null
       test-prologue: null
 
@@ -354,13 +365,13 @@ the following syntax for directive pointer parameters:
         test-code: |
           ctx->id = &ctx->id_value;
         text: |
-          The ${../if/directive:/params[3]/name} parameter shall reference an
+          While the ${../if/directive:/params[3]/name} parameter references an
           object of type ${../../type/if/id:/name}.
       - name: 'Null'
         test-code: |
           ctx->id = NULL;
         text: |
-          The ${../if/directive:/params[3]/name} parameter shall be
+          While the ${../if/directive:/params[3]/name} parameter is
           ${/c/if/null:/name}.
       test-epilogue: null
       test-prologue: null
@@ -375,12 +386,12 @@ Use the following syntax for other directive parameters:
         test-code: |
           ctx->name = NAME;
         text: |
-          The ${../if/directive:/params[0]/name} parameter shall be valid.
+          While the ${../if/directive:/params[0]/name} parameter is valid.
       - name: Invalid
         test-code: |
           ctx->name = 0;
         text: |
-          The ${../if/directive:/params[0]/name} parameter shall be invalid.
+          While the ${../if/directive:/params[0]/name} parameter is invalid.
       test-epilogue: null
       test-prologue: null
 
diff --git a/eng/req/req-for-req.rst b/eng/req/req-for-req.rst
index 9225e95..0c05ed6 100644
--- a/eng/req/req-for-req.rst
+++ b/eng/req/req-for-req.rst
@@ -171,9 +171,9 @@ Syntax
 
 Use the Easy Approach to Requirements Syntax (:term:`EARS`) to formulate
 requirements.  A recommended reading list to get familiar with this approach is
-:cite:`Mavin:2009:EARS`, :cite:`Mavin:2010:BigEars`, and
-:cite:`Mavin:2016:LLEARS`.  Please also have a look at the EARS quick reference
-sheet :cite:`Uusitalo:2012:EARS`.  The sentence types are:
+:cite:`Mavin:2009:EARS`, :cite:`Mavin:2010:BigEars`,
+:cite:`Mavin:2016:LLEARS`, and `Alisair Mavin's web site
+<https://alistairmavin.com/ears/>`_.  The patterns are:
 
 * Ubiquitous
 
@@ -181,22 +181,34 @@ sheet :cite:`Uusitalo:2012:EARS`.  The sentence types are:
 
 * Event-driven
 
-    *When* <optional preconditions> <trigger>, the <system name> shall <system response>.
+    **When** <trigger>, the <system name> shall <system response>.
 
 * State-driven
 
-    *While* <in state>, the <system name> shall <system response>.
+    **While** <pre-condition>, the <system name> shall <system response>.
 
 * Unwanted behaviour
 
-    *If* <optional preconditions> <trigger>, *then* the <system name> shall <system response>.
+    **If** <trigger>, **then** the <system name> shall <system response>.
 
 * Optional
 
-    *Where* <feature>, the <system name> shall <system response>.
+    **Where** <feature is included>, the <system name> shall <system response>.
 
-The optional sentence type should be only used for application configuration
-options.  The goal is to use the *enabled-by* attribute to enable or disable
+* Complex
+
+    **Where** <feature 0 is included>, **where** <feature 1 is included>, ...,
+    **where** <feature *n* is included>, **while** <pre-condition 0>, **while**
+    <pre-condition 1>, ..., **while** <pre-condition *m*>, **when** <trigger>,
+    the <system name> shall <system response>.
+
+    **Where** <feature 0 is included>, **where** <feature 1 is included>, ...,
+    **where** <feature *n* is included>, **while** <pre-condition 0>, **while**
+    <pre-condition 1>, ..., **while** <pre-condition *m*>, **if** <trigger>,
+    **then** the <system name> shall <system response>.
+
+The optional pattern should be only used for application configuration
+options.  The goal is to use the ``enabled-by`` attribute to enable or disable
 requirements based on configuration parameters that define the RTEMS artefacts
 used to build an application executable (header files, libraries, linker command
 files).  Such configuration parameters are for example the architecture, the
@@ -345,7 +357,7 @@ Justification of Requirements
 -----------------------------
 
 Each requirement shall have a rationale or justification recorded in a
-dedicated section of the requirement file.  See *rationale* attribute for
+dedicated section of the requirement file.  See ``rationale`` attribute for
 :ref:`ReqEngSpecificationItems`.
 
 .. _ReqEngValidation: