[PATCH 1/4] eng: Update EARS syntax

[Sebastian Huber]

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.
---
 eng/req/howto.rst       | 38 +++++++++++++++++++-------------------
 eng/req/req-for-req.rst | 30 ++++++++++++++++++++----------
 2 files changed, 39 insertions(+), 29 deletions(-)

diff --git a/eng/req/howto.rst b/eng/req/howto.rst
index 8481214..ee239d4 100644
--- a/eng/req/howto.rst
+++ b/eng/req/howto.rst
@@ -285,18 +285,18 @@ 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
-<ReqEngSyntax>`:
+requirements.  Such requirements should be written in the following
+:ref:`syntax <ReqEngSyntax>`:
 
-    *When* <optional preconditions> <trigger>, the <system name> shall
-    <system response>.
+    **While** <pre-condition>, **while** ..., **when** <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.
+The list of <pre-condition> clauses are the pre-conditions in a particular
+state of the action requirement.  The <trigger> is the action of the action
+requirement.  The post-conditions in a particular state 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
@@ -322,20 +322,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 +354,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 +375,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..b86236e 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,32 @@ 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 is included>, **where** ..., **while** <pre-condition>,
+    **while** ..., **when** <trigger>, the <system name> shall <system
+    response>.
+
+    **Where** <feature is included>, **where** ..., **while** <pre-condition>,
+    **while** ..., **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 +355,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:
-- 
2.26.2