[PATCH 1/4] eng: Update EARS syntax

[Chris Johns]

On 18/3/21 4:50 pm, Sebastian Huber wrote:
> On 18/03/2021 01:43, Chris Johns wrote:
> 
>> On 18/3/21 4:34 am, Sebastian Huber wrote:
>>> 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 +++++++++++++++++++-------------------
>> The following seems like a formal specification and the section is "How to". Is
>> the section really "Specification", that is specification of requirements?
> 
> This how-to section should help to write items of this type:
> 
> https://docs.rtems.org/branches/master/eng/req/items.html#spectypeactionrequirementitemtype
> 
> 
> Action requirement items are a generator for event-driven requirements.
> 

Ah ok and thanks. I misunderstood. The "User Action Requirements .." and "Use
CamelCase ... ". Maybe something softer for a how-to like ""Action Requirements
Item Types are used to specify ..."

>>
>>>   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>.
>> Does the special formatting imply something special, ie **While** etc?
> 
> Yes, this is the notation used to describe the EARS syntax:
> 
> https://alistairmavin.com/ears/
> 

Great. What if the sentence said ... "... written in the following EARS syntax:"?

>>
>>> -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
>> What do the '<' and '>' imply? Should `<pre-condition>` be used?
> 
> This was an attempt to explain the relationship between the EARS notation and
> the attributes of the item. I will try to make this more clear.
> 
>>
>>> +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.
>> If you inspect the language used in detail you have a <trigger> that is an
>> "action" of an "action requirement" however <trigger> is the only piece that has
>> any special annotation yet it depends on "action" and "action requirement". In
>> the current text "action requirement" is the section so that is OK but it does
>> not deal with "action".
> In the action code block of the item there may be a bit of code and not just a
> single function call.
> 
> In a follow up patch we have:
> 
> The trigger of the action requirement is defined by the link to an
> :ref:`SpecTypeInterfaceFunctionItemType` or an
> :ref:`SpecTypeInterfaceMacroItemType` item using the
> :ref:`SpecTypeInterfaceFunctionLinkRole`.
> 
> And:
> 
> .. code-block:: yaml
> 
>     links:
>     - role: interface-function
>       uid: ../if/create
>     test-action: |
>       ctx->status = rtems_timer_create( ctx->name, ctx->id );
> 
> The link to the :c:func:`rtems_timer_create` interface specification item with
> the ``interface-function`` link role defines the trigger.  The ``test-action``
> defines the trigger code for the validation test.   The validation test is
> defined in this item along with the specification.

OK I now see.

>>>   Use ``CamelCase`` for the pre-condition names, post-condition
>>>   names, and state names.  The more conditions a directive has, the shorter
>> And to highlight my point is "pre-condition" and "post-condition" actually
>> `<pre-condition> and <post-condition>?
> No, this text refers to the attributes of the action requirement item.
>>
>> Is the snake-case for the tags defined and mandated
> 
> You mean the item attribute keys?
> 
> https://docs.rtems.org/branches/master/eng/req/items.html#name
> 

Yes. It is a good thing I can read a regx :)

Thanks for the responses. It is looking good.

Chris