Make I18N Glossary definitions okay in normative blocks

[aphillips]

I18N encourages the use of the I18N glossary for linking common terminology in specs vs. having to clone the definition locally (with all of the maintenance headaches that ensue). The glossary is published as a NOTE, so is not normative. Uses of this terminology do not generally affect normativity, but linking the terms improves understanding. When the term is used in a normative way, Infra is usually the host to the term and I18N works with WHATWG et al to keep from having any conflicts.

However, this means that references to the I18N glossary produce Respec warnings about “non-normative reference in a normative block”.

(Filing this issue per a conversation with @plehegar, will follow up with PRs)

[nigelmegitt]

My favourite solution to this, if possible, would be to publish the i18n glossary in a form that Respec considers normative.

[plehegar]

My favourite solution to this, if possible, would be to publish the i18n glossary in a form that Respec considers normative.

Without looking deep into respec, I would expect that the only normative acceptable form would be a CR/REC or a Statement? Which seems overkilll for this document.

[plehegar]

cc @w3c/tilt

[nigelmegitt]

Which seems overkilll for this document.

It seems exactly appropriate to me, since the desire is to be able to use these terms as normative definitions within RECs. If you want to be able to write testable specs against the definitions then they will be a core part of those specs, so either make them normative or have people copy them into a normative spec and add a note saying "we got these definitions from i18n glossary, these copies are frozen until/unless we update them to track ongoing improvements".

An alternative, that is mostly done in the glossary already, is to help spec writers by pointing them to the normative spec that defines the term. Then any glossary terms that are solely defined in the glossary are not usable as normative references. That seems fine, since mostly they're explaining concepts.

I just did some playing around and generated the Respec warning by including this in a normative section:

      <p>Reference to [=gregorian calendar=] defined in [[i18n-glossary]]</p>

And I tried but failed to find a way in Respec to mark the reference as being informative only, using something like the [[?FOO]] syntax. Perhaps a tweak to allow for terms to be referenced informatively only, even from normative sections, might help with this problem? (maybe this already exists but I couldn't work out the right syntax)

[plehegar]

the desire is to be able to use these terms as normative definitions within RECs.

My understanding is that those references would still count as informative, so the document would not contain normative definitions.

[nigelmegitt]

the desire is to be able to use these terms as normative definitions within RECs.

My understanding is that those references would still count as informative, so the document would not contain normative definitions.

That's dangerous though, isn't it? There's no markup or other way to indicate that an externally defined term used in a normative section is in fact informative only. You can put the text containing the term reference into an informative section, but that is not the use case for this issue - if it were an acceptable solution then it would have been done, and wouldn't generate the warning message.

[aphillips]

That's dangerous though, isn't it? There's no markup or other way to indicate that an externally defined term used in a normative section is in fact informative only. You can put the text containing the term reference into an informative section, but that is not the use case for this issue - if it were an acceptable solution then it would have been done, and wouldn't generate the warning message.

The challenge here is to create a mechanism that is useful without being onerous. The exported terms in the I18N glossary (there are unexported terms, which generally overlap with normative definitions found in Infra) are the correct I18N terms for a wide variety of things. Unfortunately, the I18N space is fairly dense with fussy jargon (🙈). We want specification writers to use the correct jargon and we want readers to not have to guess what the terms mean.

In cases where the term is used in a normative fashion, it is, as you suggest, important to have the term locally or in a normative reference. We could make the I18N glossary into such a normative document. This would greatly increase the friction on the I18N WG in terms of maintenance and upkeep (we have published updates to the document six times this year--that would have to be managed down significantly)

However, most of the time the reference is fleeting and has no bearing on the normativity of the statement, like mentioning that a format varies by locale or that the paragraph direction can have influence on aspects of the layout. The definitions are normative, from the point of view that we strive to make them complete and correct, although our definitions are often less formal than it is possible to make them.

Lots of specs have ignored the Respec warning in the past. We could invent markup for non-normative references, including appropriately different styling. If there were more than one example of documents like ours, I'd even suggest we pursue that. But it feels like the simpler course would be the old axiom: "the exception proves the rule in cases not excepted"

[nigelmegitt]

This would greatly increase the friction on the I18N WG in terms of maintenance and upkeep (we have published updates to the document six times this year--that would have to be managed down significantly)

If the definitions are being used normatively, friction is probably a valuable thing. If this were a Rec, with "allows changes" then you should be able to propose additions or changes in-place with a little less extra work for the group. (this is theoretical, and may depend on tooling in practice!)

[xfq]

Personally, I am not entirely opposed to the i18n glossary advancing to REC or CR status. However, I am concerned that much of its content may not directly influence conformance and cannot be reliably tested, making it non-normative in the traditional sense. For instance, (IANAL but) I believe the terms in the glossary does not have patent considerations. In many cases, if a working group intends to reference a term normatively, they can cite Infra or define a "testable" term within their own specification.