RFC: Improving the handling of single-line and multi-line strings in StrictDoc

[stanislaw]

This issue is not critical, but it sometimes creates confusion for both StrictDoc users and developers. It also adds extra development work in some cases.

Related tickets:

• UI: Cannot save element with SingleChoice field #1900
• Bug: GUI writes SingleChoice/MultipleChoice field values as multi-line #2224

StrictDoc currently has only one String type. It does not have separate types for single-line and multi-line strings. Instead, it uses a rule based on the order of fields in a grammar element.

Current rule:
Every grammar element must have one content field called STATEMENT, DESCRIPTION, or CONTENT.

• Fields before the content field are meta fields. These should be single-line.
• The content field and all fields after it can be single-line or multi-line.

This rule helps StrictDoc decide how to display the fields. Meta fields are shown in a single-line format (like a table). Content fields are shown in a block format (multi-line).

Current order rule

StrictDoc checks fields in this order to find the content field:
TITLE → STATEMENT → DESCRIPTION → CONTENT

If none of these fields are found, StrictDoc shows an error and exits.

Example of field syntax

SDoc supports two ways to write strings:

• Single-line syntax: TITLE: Foo
• Multi-line syntax: STATEMENT: >>>\n ... \n<<<

But you can still write multi-line text in a single-line format (e.g., RATIONALE: BAZ).

[REQUIREMENT]
TITLE: Foo
STATEMENT: >>>
BAR
<<<
RATIONALE: BAZ

---

TL;DR

Main question:
Can we find a better way to decide if a field is a meta field or a content field, instead of using the current field order rule?

---

Pros of the current rule

P1) Once a user learns the rule, it's easy to write documents that follow it.
Most documents will include either of {STATEMENT, DESCRIPTION, CONTENT}, or at least a TITLE.

---

Problems with the current rule

P1) Compatibility with other tools
This rule is unique to StrictDoc. Other formats like Excel or ReqIF may not follow the same field order.

P2) Mismatch with typed formats
Some formats support string types directly. For example, ReqIF supports:

• String: used for short, single-line text
• XHTML: used for longer, multi-line text

Example from ReqIF:

<ATTRIBUTE-VALUE-STRING THE-VALUE="Short text here">
  <DEFINITION>
    <ATTRIBUTE-DEFINITION-STRING-REF>PERF-REQ-TXT</ATTRIBUTE-DEFINITION-STRING-REF>
  </DEFINITION>
</ATTRIBUTE-VALUE-STRING>

<ATTRIBUTE-VALUE-XHTML>
  <DEFINITION>
    <ATTRIBUTE-DEFINITION-XHTML-REF>_25YvEMkyEee5A_N9aQFa1w</ATTRIBUTE-DEFINITION-XHTML-REF>
  </DEFINITION>
  <THE-VALUE>
    <xhtml:div>
      Line 1
      Line 2
      Line 3
    </xhtml:div>
  </THE-VALUE>
</ATTRIBUTE-VALUE-XHTML>

StrictDoc has to guess where to place each field (above or below the content field), which is not ideal.

P3) Mixing of two different ideas
StrictDoc currently combines two ideas:

• whether a string is single- or multi-line
• whether a field is meta or content

This is too implicit and can cause confusion.

P4) Edge cases not supported
If a document doesn’t have any of the known fields (STATEMENT, DESCRIPTION, CONTENT, TITLE), StrictDoc fails. This can happen with custom or experimental documents.

---

Ideas for Improving SDoc

Each idea solves some of the problems, but also has trade-offs.

CH1) Add two new types: SinglelineString and MultilineString

• Keep the existing String type.
• Add two new types for better control and better mapping to ReqIF.
• This removes the need to guess based on field order.

CH2) Enforce strict syntax rules for strings

• Always require >>> <<< for multi-line text.
• Single-line strings must not use >>> <<<.
• Makes parsing easier and avoids confusion.

See also from #1900 (comment):

@haxtibal already suggested that the single/multiline fields could be placed below the statement field but be always treated as single-line fields. This could be a good option for overcoming this limitation.

CH3) Add a META: True field property

• Allow grammar authors to mark fields as meta fields explicitly.
• Removes the need for position-based rules.

---

If we do nothing

If we keep the current behavior:

• For formats like Excel, treat all fields as content (non-meta) by default.
  Let the user specify which fields should be treated as meta. This is not implemented yet.

• For ReqIF, use this rule:

  • String → meta fields (go above the content)
  • XHTML → content fields (go below the content)

---

Any feedback is appreciated.

[philippatsirgiotis]

I agree that this issue not ideal and can cause confusion (as evidenced by my issue #2224).

I lean towards CH1 and CH2. Having explicit single and multi line string types (CH1) would make things much clearer and allow the StrictDoc to more meaningfully report errors. Congruence with ReqIF is a bonus too. That said, I’m unsure how CH2 would behave in GUI-driven scenarios like the one in my issue, where a field entered after the STATEMENT in the UI is saved in a way that changes how it’s interpreted.

CH3 feels less compelling to me. The distinction between "meta" and "content" fields adds a layer of complexity that doesn’t seem necessary from the user perspective.

[stanislaw]

cc @haxtibal @thseiler @nicpappler

[philippatsirgiotis]

One additional thought: the current implementation also feels quite restrictive if you want to control the ordering of fields within a requirement. Since field order affects how fields are interpreted (i.e. meta vs content), it limits flexibility - especially if there's a reason to place certain fields earlier or later for readability or consistency.

[haxtibal]

The distinction between "meta" and "content" fields [...]

I'd also like to consider this distinction first. What's the meaning behind "meta" and "content"? Is this just a matter of presentation (table row vs. block, hidden vs. visible), or is there more to it?

Regarding presentation

Meta fields are shown in a single-line format (like a table)

In the example of DO178, STATUS is a meta field. But the layout is "STATUS:", then line break, then "Active". That's not a table row, because a table row would not have a line break, but two cells in a row. @stanislaw Can you explain what you mean with "table"? I see how a table row would make sense (it saves vertical space), but seems we don't have it yet.

XHTML: used for longer, multi-line text [...] Always require >>> <<< for multi-line text.

@stanislaw When you say "multi-line", may it be you actually mean "markup"? Multi-line in my understanding is ordinary unicode text that happens to contain one ore multiple \n. We wouldn't need multiple types for it. Markup on the other hand is a different beast. We have to invoke a renderer, have to know whether to escape or not control sequences, and have to know which markup and flavor it is. If you mean markup, then I understand why you want different types (I'd just call it Markup, not MultilineString).

Regarding content

Every grammar element must have one content field

Does it still hold that there should be only one content field? We had multiple cases where it was not obvious which field to choose as the content field. For example, "threat" element may have fields "description" and "mitigation", where both are equally important.

That said, I'd probably add a CH4:

• Introduce 3 categories of fields: META, CONTENT, MULTIINSTANCE
• Add type Markup: We'd then have String, Markup, SingleChoice, MultiChoice. Note how category and type are two unrelated concepts.
• Don't automatically reorder/group fields when displayed, but follow order of definition from grammar (address @philippatsirgiotis s 2nd comment)
• Meta means "This field is unimportant enough that it may be automatically hidden, or may be displayed in condensed form (like table row) in responsive UIs or dedicated views like the traceability graph".
  • It's marked as META: in grammar.
  • Meta fields may be of any type (string with or without \n, choice). But maybe don't allow markup (if this complicates the UI too much).
• Content means "This field has top importance and will always be displayed in any view"
  • Doesn't need annotation in grammar (it's the default)
  • There may be multiple content fields.
  • If we export to a different format that forces us to have a single content field, squash em.
  • Content fields may be of any type (string, markup, choice, ...)
• Multi instance generalizes the concept of comments. It means "There can be multiple entries for this field".
  • It's marked as MULTI: in grammar.
  • Multi instance fields can have any type (string, markup, choice, ...) in grammar. But all entries must then stick to the type that was selected by grammar.