You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- `Automotive SPICE in opensource StrictDoc tool, with System Architecure ideas
24
+
<https://www.youtube.com/watch?v=k2MCFWvCs7E>`_
25
+
by Lukasz Juranek.
26
+
[/FREETEXT]
27
+
28
+
[/SECTION]
29
+
30
+
[SECTION]
31
+
TITLE: How did the SDoc text language become what it is?
32
+
33
+
[FREETEXT]
34
+
Shortly: The SDoc markup is a hybrid of TOML and YAML with some influence from HTML/XML and `ASN.1 <https://en.wikipedia.org/wiki/ASN.1>`_. Using each of these formats as-is, and also the JSON format, was considered but discarded during the design. The SDoc markup has been pretty stable since its inception but the flexibility of the TextX parser allows easy modifications of the language in case of future evolutions. Any feedback to the current design of the markup language is appreciated.
35
+
36
+
----
37
+
38
+
The main use case for SDoc is to model a structure of a technical document that consists of tens and hundreds of technical requirements. The following high-level requirements for the markup are therefore relevant:
39
+
40
+
- Encode documents of reasonable size (up to several hundreds or few thousands of A4-printed pages).
41
+
- Visualize large blocks of requirements text without too much markup noise.
42
+
- Support documents with nested (2-4 levels) or deeply nested structure (detailed technical specifications with up to 9-10 levels of chapter nesting).
43
+
- Support multiple fields for requirement meta information which makes a requirement look like "a text with some meta information around it".
44
+
45
+
SDoc format is inspired by several formats: TOML, YAML, ASN.1 and HTML/XML.
46
+
47
+
**TOML: Square bracket syntax**
48
+
49
+
From TOML, StrictDoc borrowed the ``[]`` bracket syntax to create the ``[REQUIREMENT]``, ``[SECTION]`` and other blocks but uses the YAML-like syntax for these blocks' fields, for example:
50
+
51
+
.. code-block::
52
+
53
+
[REQUIREMENT]
54
+
TITLE: Requirement ABC
55
+
STATEMENT: The system A shall do B when C.
56
+
57
+
**TOML/YAML: Arrays/dictionaries**
58
+
59
+
StrictDoc has a rudimentary support of arrays and dictionaries. For example, the syntax for defining the document's ``[GRAMMAR]`` resembles what would look like an array of records in YAML:
60
+
61
+
.. code-block::
62
+
63
+
[GRAMMAR]
64
+
ELEMENTS:
65
+
- TAG: REQUIREMENT
66
+
FIELDS:
67
+
- TITLE: UID
68
+
TYPE: String
69
+
REQUIRED: True
70
+
- TITLE: LEVEL
71
+
TYPE: String
72
+
REQUIRED: False
73
+
74
+
**Capitalization of reserved keywords from ASN.1**
75
+
76
+
From ASN.1, StrictDoc borrows the idea of having all reserved fields capitalized. This helps to visually distinguish between the grammar content and user content.
77
+
78
+
**Nested sections**
79
+
80
+
From HTML, the idea of opening and closing tags is taken to avoid any nesting that would otherwise be required to support the deeply nested documents with up to 6 or 8 levels, e.g., 1.1.1.1.1.1.1...
81
+
82
+
.. code-block::
83
+
84
+
[SECTION]
85
+
TITLE: Section 1
86
+
87
+
[SECTION]
88
+
TITLE: Section 1.1
89
+
90
+
...
91
+
92
+
[/SECTION]
93
+
94
+
[/SECTION]
95
+
96
+
Taking HTML or XML as-is didn't seem like a good option because of the heavy visual noise that is produced around the actual content by the surrounding tags.
97
+
98
+
**Multiline strings**
99
+
100
+
The support of multiline strings is arranged by a custom solution which helps to avoid any nesting of multiline text as well as to visually indicate the start and end parts of the multiline string in a visually unambiguous way. This is how the multiline string is declared:
101
+
102
+
.. code-block::
103
+
104
+
[REQUIREMENT]
105
+
TITLE: Requirement ABC
106
+
STATEMENT: >>>
107
+
The multiline requirement statement
108
+
without any nesting.
109
+
>>>
110
+
111
+
**Discarded options**
112
+
113
+
Taking TOML or YAML as-is didn't seem like a good option because these formats are designed to be used for configuration files or data serialization and not for large documents with hundreds of requirements. The most obvious problems for reusing either of TOML or YAML directly would have been with encoding the deeply nested documents and supporting readable and non-nested multiline strings (see also about the multiline strings below).
0 commit comments