[PATCH 1/4] eng: Update EARS syntax

[Chris Johns]

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?

>  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?

> -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?

> +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".

>  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>?

Is the snake-case for the tags defined and mandated

Chris