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.

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

Reformat non-normative text in specification #459

Open
pmai opened this Issue Oct 28, 2018 · 2 comments

Comments

Projects
None yet
2 participants
@pmai
Collaborator

pmai commented Oct 28, 2018

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:

NOTE: This is non-normative text

or, using AttributeList:

[NOTE]
This is an example note.

And like this using adminition blocks for multi-paragraph text that can contain complex formatting:

[NOTE]
.A NOTE admonition block
=====================================================================
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens.

. Fusce euismod commodo velit.
. Vivamus fringilla mi eu lacus.
  .. Fusce euismod commodo velit.
  .. Vivamus fringilla mi eu lacus.
. Donec eget arcu bibendum
  nunc consequat lobortis.
=====================================================================

@pmai pmai added this to the FMI 3.0 milestone Oct 28, 2018

@pmai pmai self-assigned this Oct 28, 2018

@t-sommer

This comment has been minimized.

Collaborator

t-sommer commented Oct 28, 2018

Non-normative, inlined text is used excessively throughout the document. How do we handle non-normative text in tables for example?

@pmai

This comment has been minimized.

Collaborator

pmai commented Oct 28, 2018

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 ...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment