Consistent use of the 'informative' class

[pchampin]

Sorry, I know this is late for raising issues :-/

The use of the 'informative' class in the syntax document is not totally consistent, and in some places, badly ambiguous. Generally speaking, I would expect non-normativeness to propagate downward to subsections., especially because there is no "this section is normative" mention to override non-normative-ness.

• §1 is marked as informative, but §1.4 and §1.7 are not (and, IICC, must be considered normative). I think it would be clearer to move §1.4 and §1.7 in another top-level section (in 1.0, Terminology was §2, after an informative §1).

• §3 is marked as informative, and so are its subsections, except for §3.4.

  • If §3.4 is supposed to be informative (my faboured interpretation), it should be explicitly marked as such, for the sake of consistency with its sibbling sections;
  • otherwise, I think we should not mark §3 as informative, and move its introdictory text into its own informative subsection.

• 4 is not marked as informative, although all its subsections are marked as informative, and it contain some introductory text, which IMHO should not be interpreted as normative. Also, all subsubsections (except for 4.1.4, for nor good reason) are marked as informative, which I think is redundant. I suggest adding the 'informative' class to §4, and removing it from §4..

I will make a PR to to this effect in the evenening (French timezone).

[iherman]

I certainly believe we should be consistent and we aren't.

• I believe the only normative sections are §8, §9, and §10. I do not think §1.4 and §1.7 are; they are part of the introduction and help the reader to navigate into §8 and §9, but the definitions are only normative in those.

• Although you are right that the 'informative' qualification is automatically valid for subsection by default, I do prefer to have that term added to each subsection. It is mostly done but, indeed, not only §4 should be set as informative, but that remark should also be present in §4.1.4. And yes, §3.4 should indeed be marked informative as well.

Whether we adopt this style (ie, marking subsections as informative) is our choice but we should indeed be consistent.

Thanks!

[pchampin]

I do not think §1.4 and §1.7 are; they are part of the introduction and help the reader to navigate into §8 and §9

I tend to agree with you about §1.7. On the other hand §1.4 contains the definitions of JSON-LD specific terms, which are linked to by all mentions of those terms in all documents... And both are explicitly marked as normative (`class="normative").

Although you are right that the 'informative' qualification is automatically valid for subsection by default, I do prefer to have that term added to each subsection.

I agree for 2nd-level subsections (X.Y), and my intention was to keep it there. However, I think that keeping it on deeper sections (X.Y.Z and even X.Y.Z.T) is too verbose...

Second thought: some of the 2nd-level sections are pretty long, so it is probably better to keep the mention at each level...

[gkellogg]

§1 is marked as informative, but §1.4 and §1.7 are not (and, IICC, must be considered normative). I think it would be clearer to move §1.4 and §1.7 in another top-level section (in 1.0, Terminology was §2, after an informative §1).

IIRC, we discussed this in 1.0, and determined that informative sections can contain normative sections. Note that, at least in the case of §1.4, it is marked with class="normative", but it doesn't say so in the resulting text. Sections are normative unless marked as informative, and this goes for sub-sections as well.

I believe the only normative sections are §8, §9, and §10. I do not think §1.4 and §1.7 are; they are part of the introduction and help the reader to navigate into §8 and §9, but the definitions are only normative in those.

That's not how the sections are marked, and term definitions are considered normative, to the degree that they make normative statements. For example, id map makes a normative statement.

I don't think §1.7 actually makes any normative statements, so it could be marked as normative. All these keywords should be repeated in the §9 Grammar section. We could remove normative statements from §1.4 and make sure they are described in §9, thus making the introduction entirely informative.

We should (I will) mark everything other than §8-10 explicitly informative.

[gkellogg]

I tend to agree with you about §1.7. On the other hand §1.4 contains the definitions of JSON-LD specific terms, which are linked to by all mentions of those terms in all documents... And both are explicitly marked as normative (`class="normative").

We could resolve this by making sure that every term definition which makes normative statements has a reference explicitly to the grammar section ("normative requirements are described in xxx), which would then be the sole location for normative statements. The reference would allow follow-your-nose.