Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Reformat non-normative text in specification #459
The current way that non-normative text is formatted in the specification (i.e. as both inline and seperate paragraphs in italics with bracketing) easily leads to the seperation between non-normative text and normative text getting lost. Additionally that way of formatting is not a good fit with the new formatting infrastructure.
I'd like to suggest to make all non-normative text separate paragraphs, with note admonitions for example, so that they are clearly seperated out (and formatting of multi-paragraph and advance content in non-normative parts easier to achieve).
E.g. using the note admonition (see http://asciidoc.org/userguide.html#X28) would look like this for a single paragraph:
or, using AttributeList:
And like this using adminition blocks for multi-paragraph text that can contain complex formatting:
That points to a problem of the document: Non-normative text should be droppable without loss to the defined semantics, otherwise it needs to be normative text.
So the solution would depend on each instance (turn it into normative text suitably altered, move it to a separate non-normative text block that repeats relevant parts of the table, or, if all else fails, have footnotes in the table referring to stuff in a non-normative block, ...).
In theory it should always be possible to remove all non-normative text from the document. The current approach leads to many of the conformance issues we are seeing.
Or in other words, the current normative parts are too weak, hence the reliance on too much non-normative text to explain the meaning of the normative parts...
At least in my experience... feel free to disagree.
And I’m not saying that this is not going to be a bit of work to get everything right, but I’d rather try to do something about this so that we have better chances at conformance meaning something.
PS: In many other standards only examples are considered non-normative, and more explanatory stuff is relegated to other documents for a reason ...