search

w3c / i18n-glossary

Definitions of terms used in W3C Internationalization documents.
https://w3c.github.io/i18n-glossary/
5 stars 4 forks source link

Ensure BikeShed users can reference the glossary #20

Closed aphillips closed 1 year ago

aphillips commented 1 year ago

Check that we're in Shepherd (see here) and ensure that our glossary items are exported, etc. appropriately.

annevk commented 1 year ago

In https://github.com/whatwg/url/issues/759 I found out that this was temporarily indexed at least through Reffy and has now been removed again.

I'd rather have terms like "surrogate" only defined by Infra and not in multiple places.

cc @dontcallmedom

dontcallmedom commented 1 year ago

to clarify, the I18N glossary is still indexed by reffy/webref - but the glossary no longer defines surrogate (removed in https://github.com/w3c/i18n-glossary/commit/38fc039aaf7de62cfe3c4d59f13f036a5957286c#diff-0eb547304658805aad788d320f10bf1f292797b5e6d745a3bf617584da017051L354)

annevk commented 1 year ago

Thanks! I wonder if that was even intentional.

https://w3c.github.io/i18n-glossary/#def_ascii_case-insensitive seems like the right approach for things like this, although the definition should not be exported for things that are defined already.

cc @r12a

r12a commented 1 year ago

Hum. Looks like i caused some unintended breakage there. I'll take another look at it, and adapt it to be like the ascii case insensitive entry. I'll also add some more thought to how we expect people to use the i18n glossary.

annevk commented 1 year ago

@r12a to be clear, the ASCII case-insensitive entry could use a small tweak as well. It shouldn't use "export" for the dfn. That's what causes the conflicts.

r12a commented 1 year ago

Ok. I'll look into that. We're about to discuss the glossary in tomorrow's i18n mtg anyway, with a view to adding many more terms to it, so this is good timing.

aphillips commented 1 year ago

I'd rather have terms like "surrogate" only defined by Infra and not in multiple places.

@annevk So you're suggesting that any term defined in our glossary that is also defined in Infra should not be exported by us and require our consumers to also consume Infra (when they use a term needed there)?

I will expand our glossary discussion in the agenda tomorrow to include this topic.

annevk commented 1 year ago

Yeah, in general pretty much all web standards need to depend on Infra due to algorithms and data structures defined therein and it would be unfortunate if that resulted in clashes.

tabatkins commented 1 year ago

Note that Bikeshed currently has a link-default preferring Infra versions of definitions over i18n-glossary versions of definitions (https://github.com/speced/bikeshed-data/blob/main/data/link-defaults.infotree#L68-L69) so in general clashes should silently resolve themselves. (You can explicitly specify that you want the i18n-glossary version if you want, tho.)

svgeesus commented 1 year ago

Are the I18n definitions normative?

I ask because the PNG spec has a normative requirement:

Encoders must convert characters that use local <a>legacy character encodings</a> to the appropriate encoding when storing text.)

which links to the 18n definition so is presumably getting this from Reffy.

This wording was suggested by @aphillips by the way. The problem we have is that the preprocessor (in this case ReSpec, not Bikeshed) warns:

Normative reference to non-normative term

as if all the I18n definitions are informative?

Spun out from

dontcallmedom commented 1 year ago

see a related ReSpec conversation of the same situation https://github.com/w3c/respec/issues/4295

aphillips commented 1 year ago

The I18N Glossary is a WG Note. Thus is cannot be formally normative.

Where Infra and the I18N glossary collide (have the same terms), Infra is normative and our glossary will point to Infra.

For the remainder of the terms ("legacy character encoding" is a good example), our terms are useful to link from specs rather than "importing"/re-creating a definition. @dontcallmedom calls out the previous discussion of this and he moved the check to the linter so it can be quashed (with a config block directive I think???):

lint: informative-dfn: false

I will update our instructions to match. I am not sure of Bikeshed's behavior in this regard.

aphillips commented 1 year ago

I have added this information and more instructions, including guidance about Infra, in PR #21

tabatkins commented 1 year ago

I... don't think Bikeshed does anything with the "normative" bool from the definitions right now. It certainly could and probably should, as a lint?

aphillips commented 1 year ago

I think this is fixed in my now-merged PR #21. I'm still working on the instructions though in #27. I will create a separate issue to track the Infra synchronization.