search

w3c / aria-common

Shared files for the ARIA repositories
Other
8 stars 15 forks source link

Deprecating terms #48

Open marcoscaceres opened 4 years ago

marcoscaceres commented 4 years ago

I'm wondering if we can come up with a plan to deprecate the terms.html file. With ReSpec now supporting the ability to cross-reference terms "exported" to the Shepherd database, the terms.html should no longer be needed.

Instead, each spec should define and export its own terms.

LJWatson commented 4 years ago

This would, I believe, be more consistent with how definitions are handled in specs in general. It also seems that it would involve less duplication, which seems like a win too.

jnurthen commented 4 years ago

100% agree - but I don't have the bandwidth to do this right now. We can plan this in the 1.3 ARIA release timeframe.

jnurthen commented 4 years ago

@marcoscaceres can you add a link to documentation that explains how exported terms work. Thanks.

marcoscaceres commented 4 years ago

@jnurthen some detailed documentation at https://github.com/w3c/respec/wiki/data-export

However, it's as easy as just adding a data-export="" attribute on a dfn element.

<dfn data-export="">exported term</dfn>

And then from another spec, you just do:

<body data-cite="some-other-spec">
   <p>
      These are the same: [=exported term=] or <a>exported term</a>
   </p>
</body>
marcoscaceres commented 4 years ago

@jnurthen I can help get things started with accessible name, if you would like? @aarongustafson and I need some of those definitions for the Web Manifest spec - and could show serve as good examples for how to do the exports. We can also try to track down any broken references.

aarongustafson commented 4 years ago

I’d be happy to help with this as well. Would it make sense to start with migrating accessible name & description to that spec, adjusting the references in each of the current ARIA repos (and our own) and then removing them from the terms file? Doing it on a small scale like that could provide a good blueprint for the whole process. We could document the steps to provide a guide for the other terms to get migrated over time.

marcoscaceres commented 4 years ago

Sounds like a plan @aarongustafson.

jnurthen commented 4 years ago

Please be aware that all the terms are currently added to each spec using <div data-include="common/terms.html" data-oninclude="restrictReferences"></div> Once all references have been resolved then common/resolveReferences.js gets invoked. One of its functions then removes and terms which are not used in that spec (or in any of the terms used in that spec). I think moving a single reference outside this process is going to be a big task.

marcoscaceres commented 4 years ago

Part of this would be removing <div data-include="common/terms.html"> and eventually killing restrictReferences()... also not needed.

jnurthen commented 3 years ago

I'm not clear on how exactly terms get added to the shepherd DB. In order to do this (and test it out amongst our dependent specs) I'll need the terms in shepherd but I don't know exactly how to make this happen. Also - how to we get the correct version of an external spec to be referenced? For example core-aam 1.3 will need to reference definitions in wai-aria 1.3 and vice-versa. How do we force references to the correct spec versions using this mechanism?

marcoscaceres commented 3 years ago

I'm not clear on how exactly terms get added to the shepherd DB.

We are now using WebRef. It states that:

The contents of the repository are updated automatically every 6 hours (although note information about published /TR/ versions of specifications are updated only once per week)

@dontcallmedom might be able to answer any specific questions about how the data is harvested.

For example core-aam 1.3 will need to reference definitions in wai-aria 1.3 and vice-versa. How do we force references to the correct spec versions using this mechanism?

For, say, specific "core-aam 1.3" terms, you would do something like:

<section data-cite="core-aam-1.3 wai-aria-1.3">
   <p>In [[core-aam-1.3]] some [=special term=] is used, and so it this [=other term=].</p>
   <p>Similarly, this term from wai-aria 1.3 [=wai thing=] can then be referenced.</p>
</section>

To see more details/examples, please see the docs: https://github.com/w3c/respec/wiki/Auto-linking-external-references

marcoscaceres commented 3 years ago

Note, the core-aam-1.3 needs to be actually published to TR (as the exported terms are harvested from TR)... same with wai-aria-1.3. However, it should be fairly straight forward.

dontcallmedom commented 3 years ago

@webref collects definitions from specs listed in https://github.com/w3c/browser-specs every 6 hours for editors drafts, and every week for their equivalent TR versions (when they exist) - being published on TR is not a per-requisite for having definitions harvested.

The best way to check which terms have been harvested is through https://respec.org/xref/?term= - it assumes the terms are defined in specs using the proper respec conventions, including being marked as data-export

marcoscaceres commented 3 years ago

being published on TR is not a per-requisite for having definitions harvested.

Ah, yes! I forgot. It was misremembering as it was for Shepherd.