search

w3c / Guide

The Guidebook is the collected wisdom of the W3C Group Chairs, team contacts and other contributors.
https://www.w3.org/Guide/
25 stars 31 forks source link

Make I18N Glossary definitions okay in normative blocks #269

Open aphillips opened 3 days ago

aphillips commented 3 days ago

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 commented 3 days ago

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

plehegar commented 3 days ago

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 commented 3 days ago

cc @w3c/tilt

nigelmegitt commented 1 day ago

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 commented 17 hours ago

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 commented 3 hours ago

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.