Update modal verbs sections (ASM-21)

christiangoedert commented 2 years ago

Update modal verbs sections according to the following table.

.Verbal forms for expressions of provisions
[%header, cols="20, 15, 65"]
|===
|Provision                  |Verbal form        |Definition
|Requirement                |shall, shall not   |A requirement conveys objectively verifiable criteria to be fulfilled and from which no deviation is permitted if conformance with the document is to be claimed.
|Recommendation             |should, should not |A recommendation conveys a suggested possible choice or course of action deemed to be particularly suitable without necessarily mentioning or excluding others.
|Permission                 |may                |A permission conveys consent or liberty (or opportunity) to do something.
|Possibility and capability |can, cannot        |A possibility conveys expected or conceivable material, physical or causal outcome. +
                                                 A capability conveys the ability, fitness, or quality necessary to do or achieve a specified thing.
|External constraint        |must               |An external constraint or obligation on the user of the document, for example laws of nature or particular conditions existing in some countries or regions, that is not stated as a provision of the document.
                                                 External constraints are not requirements of the document.
                                                 They are given for the information of the user.
|===

jmdska commented 2 years ago

Added/updated in commit https://github.com/asam-ev/asam-project-guide-content/commit/d20c5927308d0dcd109e94772be91c125c8cc278

christiangoedert commented 2 years ago

@jmdska please update the modal verbs section by the following:

=== Modal verbs

To ensure compliance with the {THIS_STANDARD} standard, users need to be able to distinguish between mandatory requirements, recommendations, permissions, as well as possibilities and capabilities.

The following rules for using modal verbs apply:

[#tab-modal-verbs]
.Rules for using modal verbs
[%header, cols=2*]
|===
|Provision |Verbal form
|*Requirements* +
Requirements shall be followed strictly in order to conform to the standard. Deviations are not allowed.
|shall +
shall not

|*Recommendations* +
Recommendations indicate that one possibility out of the several available is particularly suitable, without mentioning or excluding the other possibilities.
|should +
should not

|*Permissions* +
Permissions indicate a course of action permissible within the limits of {THIS_STANDARD} deliverables.
|may +
need not

|*Possibilities and capabilities* +
Verbal forms used to state possibilities or capabilities, whether technical, material, physical, etc.
|can +
cannot

|*Obligations and necessities* +
Verbal forms used to describe legal, organizational, or technical obligations and necessities that are not regulated or enforced by the {THIS_STANDARD} standard.
|must +
must not
|===

christiangoedert commented 2 years ago

[x] Please mention that this section is located in the Conventions and notations section.
[x] Please check if this version of the modal verbs is present in ASAM OpenDRIVE.
[x] Please check if the definitions of modal verbs in the ASAM Editorial Guide is aligned with the upper code block.

jmdska commented 2 years ago

Updated ASM-21, ASM-60 (shall/not), ASM-112 (should/not), ASM-113 (may /need not), ASM-114 (can/cannot) and added ASM-111 (must /not) in commit https://github.com/asam-ev/asam-project-guide-content/commit/5fb17dc5634e95763d12adf2bd5a073a05ce02c0 and updated ASAM OpenDRIVE in commit https://code.asam.net/simulation/opendrive-group/opendrive-standard/-/commit/4a7351cbc14305cc7a6ffe0c4f5e90815331468d

christiangoedert commented 2 years ago

The changes to the modal verbs section have been reverted and refined in commit a4f94c0af0f3d88946e227298877053f32aaeb30.

asam-ev / asam-project-guide

Update modal verbs sections (ASM-21) #91