Skip to content

docs: clarify that single-line fields are not rendered by RST/LINK parser #2505

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 13, 2025
Merged

docs: clarify that single-line fields are not rendered by RST/LINK parser #2505

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 36 additions & 6 deletions docs/strictdoc_01_user_guide.sdoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1548,6 +1548,39 @@ In this example REQ-1 is the parent of REQ-2 and REQ-2 refines REQ-1.

[[/SECTION]]

[[SECTION]]
MID: b25de974c19746be8eff551919e6d6e1
UID: SECTION-UG-Single-vs-multiline-fields
TITLE: Single vs multiline fields

[TEXT]
MID: affdbd758a2b44c2af9f3d61fe4414c2
STATEMENT: >>>
For each node field, StrictDoc supports both single-line and multiline fields.

Example:

.. code-block::

[NODE]
TITLE: Single-line field
STATEMENT: >>>
Multiline field.
<<<

The following summarizes the current StrictDoc convention for using single-line vs. multiline fields:

In the default and most common use case, single-line fields are used for meta-information such as ``MID``, ``UID``, ``TITLE``, ``TAGS``, etc. Multiline fields are used for the actual document or requirement content such as ``STATEMENT``, ``RATIONALE``, ``COMMENT``, and similar fields.

Single-line fields are parsed as plain text, not as RST. To render RST or to have ``[LINK: ...]`` recognized as HTML, the field must be multiline.

By convention, each node contains one primary multiline ``STATEMENT`` field (or an equivalent). All fields before this main statement field should be single-line fields storing meta-information, and all fields after the statement field should typically be multiline content.

There is an ongoing discussion on GitHub about formalizing the single-line and multiline convention in the SDoc format: https://github.com/strictdoc-project/strictdoc/discussions/2221. User feedback is welcome.
<<<

[[/SECTION]]

[[SECTION]]
MID: 57df0956302f4c728f6b35606320b660
UID: UG_COMPOSABLE_DOCUMENTS
Expand Down Expand Up @@ -1741,7 +1774,7 @@ user interface as well as other export formats.

All fields before the content field are considered meta information. Meta information
fields are assumed to be single-line. The content field and all following fields
accept single-line and multiline strings.
accept single-line and multiline strings. See [LINK: SECTION-UG-Single-vs-multiline-fields] for more details.

.. note::

Expand Down Expand Up @@ -2161,18 +2194,15 @@ TITLE: Links
[TEXT]
MID: 8b07c82f462348a58c3ab81be4db753d
STATEMENT: >>>
Elements that have an UID can be referenced from section text using a ``[LINK: <UID>]`` tag.
To reference a section that has an UID, use ``[LINK: <Section UID>]`` tag.
Likewise, a requirement can be referenced with ``[LINK: <Requirement UID>]``.
Elements that have a UID can be referenced from any node’s multiline field using a ``[LINK: <UID>]`` tag.

Example:

The following link references a section: [LINK: SDOC_UG_LINKS_AND_ANCHORS].

.. note::

Adding a ``LINK`` tag will only work from the section text.
In the requirement fields, the LINK tag will not be recognized.
Adding a LINK tag only works when it is placed in multiline fields written with ``>>>...<<<``. Single-line fields do not support RST syntax or tags such as ``[LINK:...]``. See also: [LINK: SECTION-UG-Single-vs-multiline-fields].
<<<

[[/SECTION]]
Expand Down
Loading