search

speced / respec

A tool for creating technical documents and web standards
https://respec.org/
Other
724 stars 389 forks source link

Question of normative vs. informative references #4295

Open johanneswilm opened 2 years ago

johanneswilm commented 2 years ago

We need some user help in this PR: https://github.com/w3c/input-events/pull/139

The I18N group told us to link for a specific definition into their spec. Respec says that that definition is not normative, but they say they have never had an issue with their spec not being normative enough. I've looked through the documentation, and

  1. I cannot find how to to make an informative reference to a single term in a normative part of a spec (I did figure out how to make an informative reference to an entire document).
  2. It seems to me that the reference should actually be normative and not just informative and so we'd need your advice on how we should proceed with that if I am right.
tidoust commented 2 years ago

On the notion of "normative enough", the official definition of normative for W3C specs is in the Patent Policy and it only applies to documents that are published on the Recommendation track. By this definition, documents published as Notes do not contain normative terms and statements. The Internationalization Glossary is authored with ReSpec. ReSpec adds an informative class to the <body> as a result. This is what makes all definitions it contains identified as "informative".

The W3C Process provides guarantees of stability (and reviews) for normative portions of documents published on the Recommendations track. There are no such guarantees for Notes and informative content. Nothing in the process prevents the Internationalization working group from issuing a new version of the glossary tomorrow without the definition you're trying to reference.

Now, in practice, the evaluation of whether a normative reference to an external term or specification is acceptable (i.e. "normative enough") is up to the Director when a spec transitions on the Recommendation track. The Director may well evaluate that it is appropriate to have, in a normative section, a normative reference to a term defined in a document that is not on the Recommendation track.

As far as I can tell, there is only one other browser spec right now that references the Internationalization Glossary normatively: Secure Payment Confirmation. That spec has not yet transitioned to Candidate Recommendation so I think that the Director has not yet reviewed that reference.

Back to the issue at hand, it seems fine to me that ReSpec issues a warning when an author references an informative term from within a normative section, but I agree that there should be a way to bypass this warning and have ReSpec generate:

johanneswilm commented 2 years ago

Thank you @tidoust . I've learned that in the W3C there are both rules and traditions and sometimes the two don't agree. So I think this is something that would be good for the I18N WG to review. We asked for their feedback in part also because we were asked to do so before moving further with the spec along the recomemndation track, so if their recommendations end up make us do things that make the spec be less likely to move further toward recommendation, then it seems like that needs to be resolved within the I18N WG.

@aphillips What do you think? Would it be possible to have a version of that glossary that follows these rules and thereby is guaranteed to be stable?

marcoscaceres commented 2 years ago

Thanks @tidoust! You summed it up beautifully. I was going to say the same. Yes, let's make the the i18n glossary a normative document. That would be similar to https://infra.spec.whatwg.org, which is also a kind of glossary (and useful algorithms).

marcoscaceres commented 2 years ago

@aphillips, as an aside, there might be some overlap between the i18n glossary and the Infra spec? https://infra.spec.whatwg.org/#code-points

It would be good to only have a single source of truth.

aphillips commented 2 years ago

We (I18N WG) discussed this in our teleconference this week.

@tidoust is right about the status of I18N-GLOSSARY, although as you call out spec authors should be able to use our glossary to reference defined terms.

Our thinking is that the definitions found in our glossary don't need to be normative, because in general they explain terminology--and they do so in a generalized manner. I18N is not chartered to publish REC-track documents at present and our glossary is updated too frequently to really be on that track in any case. (We do keep terms and their fragment IDs stable to ensure that the glossary can be used by many specifications.)

The term grapheme, which is at issue here, is being used in a normative way in this spec and thus needs to be formally defined in order to ensure clarity and interop for implementers. Terms like this could be defined in Infra, although we note that Infra is focused on a specific set of technologies.

@marcoscaceres There is bound to be some overlap between our glossary and the Infra spec, but our purposes are different. Our WG tends to default to using Infra definitions when normative functional definitions are needed (although there can be other sources, such as Unicode) and our glossary when non-normative term definitions are required.

@johanneswilm I think my original comment erred in pointing you solely to our glossary. What I was trying to do was to keep from creating a new definition for the term character, but my later comments about grapheme vs. grapheme cluster were circling around the fact that you need to define what implementers need to do here. Infra does not (currently) provide anything related to grapheme clusters, so your spec still needs to define what Input Events means by "grapheme". I'll make comments in w3c/input-events#139 to that effect and with guidance from our telecon discussion mentioned above.

johanneswilm commented 2 years ago

@aphillips Ok. Now given that there really is no disagreement on what the implementers should do and it's just a question of where a normative definition for the term is to live and this is something for the I18N group to determine, I think it would be the easiest if you could simply create a PR with the correct link to a definition or the definition itself and we will have it merged ASAP.