Documentation: List of DOCUMENT grammar elements does not specify where REQ_PREFIX belongs

[KlfJoat]

The StrictDoc grammar is positional. While that is kind of limiting, it's generally okay because the documentation makes it clear what elements go in which order.

But that's not the case for REQ_PREFIX, as I found out when I tried using it at the DOCUMENT level.

In the list of DOCUMENT grammar elements, REQ_PREFIX is not listed. So it's unclear where it goes in the order.

strictdoc/docs/strictdoc_01_user_guide.sdoc

Lines 503 to 530 in 590aaf1

	The following ``DOCUMENT`` fields are allowed:
	.. list-table:: SDoc grammar ``DOCUMENT`` fields
	:widths: 20 80
	:header-rows: 1
	* - **Field**
	- **Description**
	* - ``TITLE``
	- Title of the document (mandatory)
	* - ``UID``
	- Unique identifier of the document
	* - ``VERSION``
	- Current version of the document
	* - ``CLASSIFICATION``
	- Security classification of the document, e.g. Public, Internal,
	Restricted, Confidential
	* - ``ROOT``
	- Defines whether a document is a root object in a traceability graph. A root document is assumed to not have any parent requirements. The project statistics calculation will skip all root document's requirements when calculating the metric ``Non-root-level requirements not connected to any parent requirement``.
	* - ``OPTIONS``
	- Document configuration options

In the only 2 mentions of REQ_PREFIX in the documentation, it is shown as ordered immediately after the TITLE element of both the DOCUMENT section and SECTION... section.

strictdoc/docs/strictdoc_01_user_guide.sdoc

Lines 1908 to 1920 in 590aaf1

	.. code-block::
	[DOCUMENT]
	TITLE: Hello world doc
	REQ_PREFIX: MYDOC-
	A section-level requirement mask:
	.. code-block::
	[SECTION]
	TITLE: Section 2.
	REQ_PREFIX: LEVEL2-REQ-

So I placed it after TITLE for SECTION headings, and it worked. But I got an error when I put it after TITLE for the DOCUMENT heading. The grammar.py file shows that for DOCUMENT headings, it belongs between CLASSIFICATION and ROOT.

strictdoc/strictdoc/backend/sdoc/grammar/grammar.py

Lines 152 to 158 in 590aaf1

	DocumentConfig[noskipws]:
	('UID: ' uid = /{REGEX_UID}/ '\n')?
	('VERSION: ' version = SingleLineString '\n')?
	('CLASSIFICATION: ' classification = SingleLineString '\n')?
	('REQ_PREFIX: ' requirement_prefix = SingleLineString '\n')?
	('ROOT: ' (root = BooleanChoice) '\n')?
	('OPTIONS:' '\n'

Sure enough, that solved my problem.

Please update the documentation to match the grammar definition for usability purposes... or don't be quite so strict with element placement and order. (I know, unlikely, but it IS an acceptable resolution to my issue 😄 )

[stanislaw]

Hi @KlfJoat, thanks for reporting this. There are several issues here:

• I proposed a nice addition to Arpeggio parser that would guide you to find the fields order much quickly but unfortunately the patch was not accepted due to this case being too specific to StrictDoc: WIP: Optional feature: More verbose failed expression reporting textX/Arpeggio#114. (Arpeggio is a PEG parser behind textX.). If this was implemented, the error message for an incorrectly placed grammar field would show you which options you actually have when doing something incorrectly with the grammar.
• The requirements order is fixed due to the grammar which fixes the elements order and then the UI writes them in the order as configured.
• I think there is nothing serious that prevents us from relaxing the order for the document options. It is something that you could do relatively soon. I will give this some more thought and decide whether I do it, right now it seems reasonable.

The documentation fix is on the way: #1672 which should resolve the main topic of your report.