Use one sentence per line

[zrgt]

Currently we have in our documentation multiple sentences in one line, like: The only thing that cannot be defined in the template itself is the unique ID of the submodel instance itself (it is not identical to the ID of the submodel template), as well as the property values, etc. Templates also define cardinalities, for example whether an element is optional or not. Submodel element lists typically contain more than one element: the template contains an exemplary element template; the other elements can be created by copy/paste from this template.

There is a recommendation from AsciiDoc community to handle the text as a source code and to use one sentence per line.

They list the following advantages by using this technique:

- It prevents reflows (meaning a change early in the paragraph won’t cause the remaining lines in the paragraph to reposition).
- You can easily swap sentences.
- You can easily separate or join paragraphs.
- You can comment out sentences or add commentary to them.
- You can spot sentences which are too long or sentences that vary widely in length.
- You can spot redundant (and thus mundane) patterns in your writing.

• Additionally we will get much more clear git diffs

Proposal: Convert current documents to the one sentence per line-format and enforce this standard in all future documents

[mristin]

I strongly second this approach.

[g1zzm0]

me three

[BirgitBoss]

• This needs to be documented in "how to maintain specification" or similar.
• It is not clear to me whether there is tooling available to change the files correspondingly? Or would this be manual work?
• You would like to add a github action for asciidoc validation before accepting a PR?

[BirgitBoss]

Decision 2024-07-19: approved