Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Deprecating terms #48

Open
marcoscaceres opened this issue Jun 23, 2020 · 14 comments
Open

Deprecating terms #48

marcoscaceres opened this issue Jun 23, 2020 · 14 comments
Assignees
@michael-n-cooper

Comments

@marcoscaceres
Copy link
Member

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
Copy link

LJWatson commented Jun 23, 2020 via email

@jnurthen
Copy link
Member

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.

@michael-n-cooper michael-n-cooper self-assigned this Jun 23, 2020
@jnurthen
Copy link
Member

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

@marcoscaceres
Copy link
Member Author

@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
Copy link
Member Author

@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
Copy link

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
Copy link
Member Author

Sounds like a plan @aarongustafson.

@jnurthen
Copy link
Member

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
Copy link
Member Author

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

@jnurthen
Copy link
Member

jnurthen commented Mar 2, 2021

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
Copy link
Member Author

marcoscaceres commented Mar 3, 2021 •
edited
Loading

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
Copy link
Member Author

marcoscaceres commented Mar 3, 2021 •
edited
Loading

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
Copy link
Member

@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
Copy link
Member Author

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.

@jnurthen jnurthen mentioned this issue Mar 31, 2021
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@michael-n-cooper michael-n-cooper

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@aarongustafson @dontcallmedom @marcoscaceres @jnurthen @michael-n-cooper @LJWatson