diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..0e259d4 --- /dev/null +++ b/LICENSE @@ -0,0 +1,121 @@ +Creative Commons Legal Code + +CC0 1.0 Universal + + CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE + LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN + ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS + INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES + REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS + PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM + THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED + HEREUNDER. + +Statement of Purpose + +The laws of most jurisdictions throughout the world automatically confer +exclusive Copyright and Related Rights (defined below) upon the creator +and subsequent owner(s) (each and all, an "owner") of an original work of +authorship and/or a database (each, a "Work"). + +Certain owners wish to permanently relinquish those rights to a Work for +the purpose of contributing to a commons of creative, cultural and +scientific works ("Commons") that the public can reliably and without fear +of later claims of infringement build upon, modify, incorporate in other +works, reuse and redistribute as freely as possible in any form whatsoever +and for any purposes, including without limitation commercial purposes. +These owners may contribute to the Commons to promote the ideal of a free +culture and the further production of creative, cultural and scientific +works, or to gain reputation or greater distribution for their Work in +part through the use and efforts of others. + +For these and/or other purposes and motivations, and without any +expectation of additional consideration or compensation, the person +associating CC0 with a Work (the "Affirmer"), to the extent that he or she +is an owner of Copyright and Related Rights in the Work, voluntarily +elects to apply CC0 to the Work and publicly distribute the Work under its +terms, with knowledge of his or her Copyright and Related Rights in the +Work and the meaning and intended legal effect of CC0 on those rights. + +1. Copyright and Related Rights. A Work made available under CC0 may be +protected by copyright and related or neighboring rights ("Copyright and +Related Rights"). Copyright and Related Rights include, but are not +limited to, the following: + + i. the right to reproduce, adapt, distribute, perform, display, + communicate, and translate a Work; + ii. moral rights retained by the original author(s) and/or performer(s); +iii. publicity and privacy rights pertaining to a person's image or + likeness depicted in a Work; + iv. rights protecting against unfair competition in regards to a Work, + subject to the limitations in paragraph 4(a), below; + v. rights protecting the extraction, dissemination, use and reuse of data + in a Work; + vi. database rights (such as those arising under Directive 96/9/EC of the + European Parliament and of the Council of 11 March 1996 on the legal + protection of databases, and under any national implementation + thereof, including any amended or successor version of such + directive); and +vii. other similar, equivalent or corresponding rights throughout the + world based on applicable law or treaty, and any national + implementations thereof. + +2. Waiver. To the greatest extent permitted by, but not in contravention +of, applicable law, Affirmer hereby overtly, fully, permanently, +irrevocably and unconditionally waives, abandons, and surrenders all of +Affirmer's Copyright and Related Rights and associated claims and causes +of action, whether now known or unknown (including existing as well as +future claims and causes of action), in the Work (i) in all territories +worldwide, (ii) for the maximum duration provided by applicable law or +treaty (including future time extensions), (iii) in any current or future +medium and for any number of copies, and (iv) for any purpose whatsoever, +including without limitation commercial, advertising or promotional +purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each +member of the public at large and to the detriment of Affirmer's heirs and +successors, fully intending that such Waiver shall not be subject to +revocation, rescission, cancellation, termination, or any other legal or +equitable action to disrupt the quiet enjoyment of the Work by the public +as contemplated by Affirmer's express Statement of Purpose. + +3. Public License Fallback. Should any part of the Waiver for any reason +be judged legally invalid or ineffective under applicable law, then the +Waiver shall be preserved to the maximum extent permitted taking into +account Affirmer's express Statement of Purpose. In addition, to the +extent the Waiver is so judged Affirmer hereby grants to each affected +person a royalty-free, non transferable, non sublicensable, non exclusive, +irrevocable and unconditional license to exercise Affirmer's Copyright and +Related Rights in the Work (i) in all territories worldwide, (ii) for the +maximum duration provided by applicable law or treaty (including future +time extensions), (iii) in any current or future medium and for any number +of copies, and (iv) for any purpose whatsoever, including without +limitation commercial, advertising or promotional purposes (the +"License"). The License shall be deemed effective as of the date CC0 was +applied by Affirmer to the Work. Should any part of the License for any +reason be judged legally invalid or ineffective under applicable law, such +partial invalidity or ineffectiveness shall not invalidate the remainder +of the License, and in such case Affirmer hereby affirms that he or she +will not (i) exercise any of his or her remaining Copyright and Related +Rights in the Work or (ii) assert any associated claims and causes of +action with respect to the Work, in either case contrary to Affirmer's +express Statement of Purpose. + +4. Limitations and Disclaimers. + + a. No trademark or patent rights held by Affirmer are waived, abandoned, + surrendered, licensed or otherwise affected by this document. + b. Affirmer offers the Work as-is and makes no representations or + warranties of any kind concerning the Work, express, implied, + statutory or otherwise, including without limitation warranties of + title, merchantability, fitness for a particular purpose, non + infringement, or the absence of latent or other defects, accuracy, or + the present or absence of errors, whether or not discoverable, all to + the greatest extent permissible under applicable law. + c. Affirmer disclaims responsibility for clearing rights of other persons + that may apply to the Work or any use thereof, including without + limitation any person's Copyright and Related Rights in the Work. + Further, Affirmer disclaims responsibility for obtaining any necessary + consents, permissions or other rights required for any use of the + Work. + d. Affirmer understands and acknowledges that Creative Commons is not a + party to this document and has no duty or obligation with respect to + this CC0 or use of the Work. diff --git a/README.md b/README.md new file mode 100644 index 0000000..bd1149c --- /dev/null +++ b/README.md @@ -0,0 +1,470 @@ +# Outsider’s Guide to the W3C + +This is an FAQ for people who may not yet even be [involved in the W3C](https://www.w3.org/get-involved/) at all — but also for W3C [Working Group](#working-groups) participants (and even Working Group Chairs) who may not be familiar with all intricacies of the W3C process. + +## What can W3C do for me? + +## What can I get from W3C? + +## How can I use the W3C? + +If there’s a problem you want to solve for people using the web — then, here’s what the W3C can do for you: + +* [You can use W3C services to document a web problem that needs solving (and use cases/requirements)](#how-can-i-document-a-web-problem-lacking-solutions) +* [You can use W3C services to propose a new web feature that solves a problem (use cases/requirements)](#how-can-i-propose-a-new-web-feature) +* [You can use W3C services to create a spec for a new web feature](#how-can-i-create-a-spec-for-a-new-web-feature) +* [You can get a w3.org URL for your spec, and autopublish updates to it at that URL](#how-can-i-get-a-w3org-url-for-my-spec) +* [You can get the strongest-possible Royalty-Free Licensing Commitments for your spec](#how-can-i-get-royalty-free-licensing-commitments) +* [You can make a “living standard” from your spec](#how-can-i-make-a-living-standard-from-my-spec) +* [You can have your spec formally endorsed by the W3C](#how-can-i-get-formal-w3c-endorsement-for-my-spec) + +### How can I document a web problem lacking solutions? + +### How can I document use cases and requirements? + +If there’s a problem you want to solve for people using the web, here’s how you can document it: + +1. Open the [Problem template](https://github.com/w3c/strategy/issues/new?assignees=&labels=problem&projects=&template=00-Problem.yml) form in the issue tracker of the [W3C Strategy team’s GitHub repo](https://github.com/w3c/strategy). +2. Fill out that form, succinctly describing the problem you want to solve, along with some use cases ([example](https://lists.w3.org/Archives/Public/public-webapps/2012JulSep/0835.html)). +3. Submit that form. + That will create a new issue in the [W3C Strategy issue tracker](https://github.com/w3c/strategy/issues). +4. Share the link to your issue (on social media and in other places), and encourage others to comment. + +The presence of that issue in the [W3C Strategy issue tracker](https://github.com/w3c/strategy/issues) will cause it to shortly thereafter get included in the [W3C Strategy Funnel](https://github.com/w3c/strategy/projects/2), and may even eventually lead to a W3C Working Group being formed to tackle the problem. + +### How can I propose a new web feature? + +If there’s a problem you want to solve for people using the web *and* you have a proposal for a new web feature which will solve that problem — here’s how you can propose it: + +1. Open the [Exploration template](https://github.com/w3c/strategy/issues/new?assignees=&labels=problem&projects=&template=00-Problem.yml) form in the issue tracker of the [W3C Strategy team’s GitHub repo](https://github.com/w3c/strategy). +2. Fill out that form, succinctly describing the new web feature you’d like to propose. +3. Submit that form. + That will create a new issue in the [W3C Strategy issue tracker](https://github.com/w3c/strategy/issues). +4. Share the link to your issue (on social media and in other places), and encourage others to comment. + +The presence of that issue in the [W3C Strategy issue tracker](https://github.com/w3c/strategy/issues) will cause it to shortly thereafter get included in the [W3C Strategy Funnel](https://github.com/w3c/strategy/projects/2), and may even eventually lead to a W3C Working Group being formed to work on it. + +### How can I create a spec for a new web feature? + +If you have a solution in mind for a problem you want to solve for people using the web, this section explains how you can get a spec created that defines a new standard web feature that will solve that problem for people. + +### How can I get a w3.org URL for my spec? + +1. First [get a Working Group created](#how-to-create-a-new-wg) created for your spec. +2. Publish a [FPWD](#what-are-fpwds) into [the w3.org/TR spec-publication space](#what-is-tr-space) — to trigger the first [Exclusion Opportunity](#exclusion-opportunities). + +### How can I auto-update my spec at its w3.org URL? + +Foo bar baz + +### How can I get Royalty-Free Licensing Commitments? + +Regardless of whether your goal is to make a spec into a so-called “living standard” or else to get the Recommendation label added to a spec, you start out by following these steps: + +1. If you don’t already have a [Working Group](#working-groups), then first [get a Working Group created](#how-to-create-a-new-wg) created for your spec. +2. Publish a [FPWD](#what-are-fpwds) into [the w3.org/TR spec-publication space](#what-is-tr-space) — to trigger the first [Exclusion Opportunity](#exclusion-opportunities). +3. Continue to [autopublish](#autopublishing) updated [Working Drafts](#what-are-working-drafts) into [the w3.org/TR spec-publication space](#what-is-tr-space) and to communicate closely with implementors and others to get the details right. +4. When your group believes a spec is ready to be fully implemented — and ready to be thoroughly tested (by having a [suite of tests](https://github.com/web-platform-tests/wpt/) to test against) — then, follow the process to get the Working Draft warning label dropped from a spec, and to get the [CR](#candidate-recommendation) label added, and publish the first [Snapshot](#what-are-snapshots) for it. + + 60 days after you publish that first [Snapshot](#what-are-snapshots), you will have [secured Royalty-Free Licensing Commitments](#how-can-i-get-royalty-free-licensing-commitments) for *all* [normative](#normative-requirements) features defined in that [Snapshot](#what-are-snapshots). +5. Work closely with implementors to produce multiple implementations of the spec, and to develop tests. + +### How can I make a “living standard” from my spec? + +If your goal is to make a spec into a [“living standard”](#living-standards), first [secure RF Licensing Commitments for your spec](#how-can-i-get-royalty-free-licensing-commitments); then: + +1. Continue working with implementors and other contributors, and on tests — and, as you iteratively refine the spec contents — [autopublish](#autopublishing) the updated contents as [“CR Drafts”](#when-to-do-cr-drafts) into [the w3.org/TR publication space](#what-is-tr-space). +2. At some regular cadence (say, once every 6 months) *and* if any [substantive spec changes](#substantive-changes) were made during that time period, [republish a new Snapshot](#how-can-i-get-royalty-free-licensing-commitments) so that a new [Exclusion Opportunity](#exclusion-opportunities) will be triggered. +3. As you receive bug/issue reports and pull requests for your spec over time, continue to perpetually [maintain](#spec-maintenance) it by repeating steps 1 and 2 above over time. + +### How can I get formal W3C endorsement for my spec? + +If your goal is to get your spec formally endorsed by the W3C — that is, to get it labeled as a [W3C Recommendation](#recommendation) — first [secure Royalty-Free Licensing Commitments for your spec](#how-can-i-get-royalty-free-licensing-commitments), and then: + +1. Assess whether the spec has multiple implementations (or is otherwise deemed sufficiently implemented). +2. When your group can show that the spec has multiple implementations (or is otherwise deemed sufficiently implemented), do an Advisory Committee review to get formal endorsement from the W3C and its Members. + +## What can I do if I’m not a Working Group participant? + +Even if you’re not a Working Group participant (and even if your employer’s not a W3C Member), you can do a lot: + +### Can I get a W3C account? + +### Can I get a “W3C member” logo in my GitHub profile? + +Yes. Here’s how: + +1. Go to [https://www.w3.org/account/request/](https://www.w3.org/account/request/) to create your W3C account. +2. Go to [https://www.w3.org/users/myprofile/connectedaccounts/](https://www.w3.org/users/myprofile/connectedaccounts/) to connect your GitHub and W3C accounts. + +The W3C logo will then show in the **Organizations** part of your GitHub profile — indicating you’re a member of the [W3C GitHub org](https://github.com/w3c/) (even if you’re not part of any Working Group, and even if your company’s not a W3C Member). + +### Can I sign RF agreements? + +Yes. The W3C’s [automated contribution-management mechanism](https://w3c.github.io/repo-management.html) allows you (in some but not all cases) to make [RF Licensing Commitments](#rf-licensing-commitments) for any [substantive change](#substantive-changes) you contribute to any Working Group spec by way of a [pull request](#can-i-contribute-spec-prs) — even if you’re not a participant in the Working Group, and even if your company isn’t a W3C Member. + +### Can I document problems? + +Yes. If there’s a web-user problem you want to solve, [you can document it](#how-can-i-document-a-web-problem-lacking-solutions) (along with use cases/requirements). + +### Can I propose features? + +Yes. If there’s a problem you want to solve for web users, [you can propose a new web feature](#how-can-i-propose-a-new-web-feature) to solve it. + +### Can I create specs? + +Yes. You can create a spec even if you’re not part of any Working Group, and even if you’re not a W3C Member. + +### Can I review specs? + +Yes. The W3C strongly encourages and facilitates [wide review](#wide-review) — and seeks to provide the widest-possible opportunities for review from the widest-possible set of reviewers. Here’s how you can take part: + +1. Find a W3C Working Group spec that you can review and comment on — by taking any of the following steps: + * Go to the [W3C News](https://www.w3.org/news/) page or to [public-review-announce archive](https://lists.w3.org/Archives/Public/public-review-announce/) and browse through the latest “Call for Wide Review” and “First Public Working Draft” announcements. + * [Subscribe](mailto:public-review-announce-request@w3.org?subject=subscribe) to the mailing list to which all “Call for Wide Review” and “First Public Working Draft” announcements are posted — so you’ll get e-mail notifications whenever new announcements are made. +2. Review the actual spec, and raise issues or pull requests or post comments. + + Every “Call for Wide Review” and “First Public Working Draft” announcement has a link to an actual Working Group spec — and every Working Group spec has a link to the group’s [W3C GitHub repo](https://github.com/orgs/w3c/repositories?type=source) and issue tracker and/or a [mailing list for comments](#can-i-access-mailing-lists). So, you can do any of the following: + * [Raise issues](#can-i-raise-issues) in the group issue tracker — for questions/comments, or for spec problems that need fixing. + * [Create a pull request](#can-i-contribute-spec-prs) with an actual spec patch — to propose changes you want merged into a spec. + * [E-mail the group’s mailing list](#can-i-access-mailing-lists) — if you have questions/comments or find spec problems that need fixing. + +### Can I raise issues? + +Yes. Working Groups have [W3C GitHub repos](https://github.com/orgs/w3c/repositories?type=source) with issue trackers where you can raise issues with questions or comments on a spec — or when you find a spec problem that need fixing. + +### Can I contribute spec PRs? + +Yes. Working Groups have [W3C GitHub repos](https://github.com/orgs/w3c/repositories?type=source) to which you can submit patches you want merged into specs. + +For [substantive patches](#substantive-changes), an [automated mechanism](https://w3c.github.io/repo-management.html) enables you (in some but not all cases) to make [RF Licensing Commitments](#rf-licensing-commitments) — even if you’re not part of any Working Group, and even if your company isn’t a W3C Member. + +### Can I access mailing lists? + +Yes. See the [W3C mailing-list archives](https://lists.w3.org/Archives/Public/). All Working Groups do their work in public; they have mailing lists with public archives that you can read, and you are welcome both to subscribe to Working Group mailing lists, and also to post messages to the lists (with questions or comments, or to report spec problems that need fixing, etc.) + +### Can I freely join any CG? + +Yes. You can [join](https://www.w3.org/community/about/faq/#how-do-i-join-a-group) any of the current [140+ Community Groups](https://www.w3.org/community/groups/) organized around specific technologies/topics: + +1. Browse the [sortable list of all 140+ W3C Community Groups (CGs)](https://www.w3.org/community/groups/) that currently exist. +2. Find a CG you’d like to join, and then on the homepage of that CG, press the **Join this group** button. + +### Can I create a new CG? + +## Community Groups + +[W3C Community Groups (CGs)](https://www.w3.org/community/about/faq/) are open, self-organized groups that by design are unregulated by the W3C — for people to get together in and use without restrictions for any purposes they choose, including to develop specs. + +### How open are CGs? + +Unlike [Working Groups](#working-groups) — which to join generally require your employer to be a W3C Member organization — CGs are open to all. You can [freely join any CG you want to](#can-i-freely-join-any-cg) — and you can even [create a new CG](#can-i-create-a-new-cg) if you want to. + +### WICG? + +The [WICG](https://wicg.io/) is a particularly special W3C Community Group specifically for [incubating](https://wicg.github.io/admin/charter.html#goals) new web-platform features. + +You can browse the [list of 120+ active incubations](https://wicg.io/#incubations), and you can even [create a proposal](https://wicg.io/#proposals) for a new incubation. + +## Working Groups + +This section contains information about Working Groups. + +### Why a Working Group? + +### Why not just a CG? + +It’s entirely possible to [maintain](#spec-maintenance) a spec in just a [Community Group](#community-groups) or the [WICG](#wicg) — or even with just a GitHub repo alone — without ever needing to have a [Working Group](#working-groups) for it. But here are the things you *can’t* do in a Community Group or in the WICG or with just a GitHub repo alone, and that you instead do need to have a Working Group for: + +* [You can get a w3.org URL for your spec, and autopublish updates to it at that URL](#how-can-i-get-a-w3org-url-for-my-spec) +* [You can get the strongest-possible Royalty-Free Licensing Commitments for your spec](#how-can-i-get-royalty-free-licensing-commitments) +* [You can have your spec formally endorsed by the W3C](#how-can-i-get-formal-w3c-endorsement-for-my-spec) + +### How to create a new WG? + +To have a new W3C Working Group created, follow these steps: + +1. [Develop a spec for a new standard web feature](#how-can-i-create-a-spec-for-a-new-web-feature). +2. Write a [draft Working Group charter](https://w3c.github.io/charter-drafts/charter-template.html) for a new W3C Working Group to work on your spec: + 1. Fork and clone the [https://github.com/w3c/charter-drafts](https://github.com/w3c/charter-drafts) repo, and then within your local clone: + 2. Create a new `foo-wg-charter.html` (or whatever name) file by copying the [W3C charter template](https://github.com/w3c/charter-drafts/blob/gh-pages/charter-template.html). + 3. Fill out the parts of that template in your `foo-wg-charter.html` file. + 4. Save your `foo-wg-charter.html` file and use `git add` to add it to your clone. + 5. Push the `foo-wg-charter.html` file change to your fork. + 6. Open a [PR](https://github.com/w3c/charter-drafts/compare) to merge your `foo-wg-charter.html` file into the [https://github.com/w3c/charter-drafts](https://github.com/w3c/charter-drafts) repo. +3. File a formal request that the W3C consider launching a new W3C Working Group based on your draft charter: + 1. Open the [Charter development and review form](https://github.com/w3c/strategy/issues/new?assignees=&labels=charter&projects=&template=04-Chartering.md&title=%5Bwg%2F%3Cshortname%3E%5D+%5Bname%5D+Group+Charter) in the issue tracker of the [W3C Strategy team repo](https://github.com/w3c/strategy). + 2. Fill out that form, with a link to your draft-charter pull request from step #2 above. + 3. Submit that form. + + That will create a new issue in the [W3C Strategy issue tracker](https://github.com/w3c/strategy/issues), where you can have a discussion about your draft charter with people from the W3C Strategy team and others. + +From there on — if your request for a new W3C Working Group ends up being accepted — the logistics for the actual creation of the new Working Group will be handled by the W3C staff. + +## Editor’s Drafts + +Anywhere you see *Editor’s Draft*, substitute ***Canonical Version***, ***Up-to-Date Version***, or ***Non-Obsolete Version***. + +> [!IMPORTANT] +> Most critically, for implementors: substitute ***“The* only *spec version that implementors should* ever *read”***. + +### Editor’s Draft = *canonical* version to always read/use + +A so-called “editor’s draft” of a spec is actually the ***canonical source*** **version** of the spec: The version including the latest changes made to the source for the spec in its source-control (GitHub) repo. That makes it the one you should use if you want to be sure you’re reading the most-up-to-date spec text — not already-obsolete spec text. + +> [!IMPORTANT] +> If you’re an implementor working on an implementing of a spec, it’s *essential* to only work from the so-called “editor’s draft”; otherwise, if you use a version published elsewhere, you may implement old spec that has subsequently changed in the canonical spec since whenever that other version happened to be published. + +The way to know whether what you’re reading is actually the canonical version is: It’ll *usually* be explicitly subtitled with the literal label ***Editor’s Draft***. But also: It’s the version you find *outside the [the w3.org/TR publication space](#what-is-tr-space)*. + +> [!NOTE] +> Canonical versions (Editor’s Drafts) of Working Group specs *usually* have `https://w3c.github.io/` URLs. + +## Working Drafts + +This section contains information about Working Drafts. + +### What are Working Drafts? + +“Working Draft” is what a spec gets labeled with while a group is still “working” on getting it to the point that they believe it’s ready to be fully implemented — and ready to be thoroughly tested (by having a [suite of tests](https://github.com/web-platform-tests/wpt/) to test against) — and before it’s ready to receive [Royalty-Free Licensing Commitments](#what-are-rf-licensing-commitments). + +So, you can think of any Working Draft as being stamped with a giant ***“Use only with caution”*** warning, signaling that the spec very likely still has some significant deficiencies — but that it *certainly* does have one very important deficiency, which is: ***[RF Licensing Commitments](#what-are-rf-licensing-commitments) for the features in the spec have not yet been secured***. + +> [!IMPORTANT] +> RF commitments can ***only*** be secured by publishing [Snapshots](#what-are-snapshots). 👉 [Why not just publish WDs?](#why-not-just-publish-wds) + +### What are FPWDs? + +The first time a spec is published [at a w3.org/TR URL](#what-is-tr-space), **First Public Working Draft (FPWD)** is the label it gets. + +The W3C widely [announces every single FPWD](https://lists.w3.org/Archives/Public/public-review-announce/) — including, often, by posting a news item both directly on the [https://www.w3.org/](https://www.w3.org/) homepage and on the [W3C News](https://www.w3.org/news/) page. Along with the general *“Here’s something new!”* value of each such an FWPD announcement, it also has another very important purpose, which is: To give a heads-up to everyone that the FPWD publication triggers a 150-day [Exclusion Opportunity](#exclusion-opportunities) for the spec. + +## Spec maintenance + +If you create a spec for a new feature for the web, plan on continuing to maintain that spec for the rest of your life (no joke) and/or plan to hand it over to others who will agree to continuing to maintain it after you move on. + +### Why spec maintenance? + +Ensuring interoperability among multiple implementations of a spec is, in practice, an ongoing process the never really ends — and that requires iteratively making refinements to the spec over time. Sometimes outright bugs are found in existing spec text, sometimes ambiguities in need of clarification, and sometimes just simple typos. + +But *all* of those cases require you to do continuing maintenance of the spec. And the way you do *that* is by having a place where others can report spec issues they find, and can submit spec patches. That typically means using a GitHub repo or something similar — with an issue tracker and a mechanism for users to submit patches. + +It’s like maintaining an open-source software application or library: Even after you release a “stable” version — and even in the case where you may *never* end up adding any features to it, or never making any API changes — you still continue to make updates to it, as users find bugs, contribute patches with code refinements, and so on. + +## Autopublishing + +This section contains information about “autopublishing” at the W3C. + +### Why do “autopublishing”? + +You should set up “autopublishing” for your specs (using [W3C “Echidna”](https://github.com/w3c/echidna/wiki)), so that up each time you merge commits to the source for your spec, your spec updates will be automatically published into [the w3.org/TR space](#what-is-tr-space). + +You can set it up using the [spec-prod](https://w3c.github.io/spec-prod/) GitHub Action, or [Bikeshed’s built-in support](https://speced.github.io/bikeshed/#cli-echidna), or [any other available tools](https://github.com/w3c/echidna/wiki#sub-projects-and-related-tools). + +## RF Licensing Commitments + +This section contains information about Royalty-Free Licensing Commitments. + +### What are RF Licensing Commitments? + +In plain terms, RF Licensing Commitments ensure that your spec can be freely implemented by anyone, so no one will ever need to pay royalties to anyone else in order to ship/sell products that have the features from your spec. + +In legal terms: A Royalty-Free Licensing Commitment is a binding legal commitment to license under the [W3C Royalty-Free License](https://www.w3.org/policies/patent-policy/#def-RF) any [Essential Claims](https://www.w3.org/policies/patent-policy/#essential-claims) that haven’t been excluded during an [Exclusion Opportunity](#exclusion-opportunities) for a spec. + +Among various standards-development organizations (SDOs), the W3C has essentially the strongest-possible RF policy — and publishing a spec at the W3C ensures it’ll secure the strongest-possible RF Licensing Commitments. + +## Living standards + +This section has information about **[maintaining](#spec-maintenance)** so-called “living standards” or “evergreen standards” at the W3C. + +### W3C “living standards”? + +Yes. For any of your group’s specs that are [receiving RF Licensing Commitments](#how-can-i-get-royalty-free-licensing-commitments), your group can continue to perpetually [autopublish](#autopublishing) and ***[maintain](#spec-maintenance)*** that spec as a so-called “living standard” or “evergreen standard” — without any requirement to necessarily ever get [formal endorsement of the spec from the W3C and its Members](#how-can-i-get-formal-w3c-endorsement-for-my-spec). + +#### Perpetually-maintained working-group specs + +In other words, that “unendorsed by the W3C and its Members but perpetually [maintained](#spec-maintenance) by the working group” spec never “transitions” or “advances” any further through the W3C spec-labeling (maturity) process. + +So the literal term *“perpetually maintained working-group spec”* would be a more accurate label for such specs. + +### Why publish CRs? + +### Why not just publish WDs? + +The reason you’d want your spec labeled [“CR”](#candidate-recommendation) — rather than keeping it labeled [“Working Draft”](#working-drafts) forever — is this: + +***The *only* way to secure [Royalty-Free Licensing Commitments](#how-can-i-get-royalty-free-licensing-commitments) is by publishing with the [“CR”](#candidate-recommendation) label.*** + +To state that same fact in few more words: + +* Specs labeled with [“CR”](#candidate-recommendation) are [Patent Review Drafts](#patent-review-draft), while specs labeled as Working Draft are *not*. +* Publishing with the [“CR”](#candidate-recommendation) label secures [RF Commitments](#how-can-i-get-royalty-free-licensing-commitments); publishing with the Working Draft label does *not*. +* While publishing with the FPWD label *does* trigger an [Exclusion Opportunity](#exclusion-opportunities), that *does not* trigger [RF Commitments](#how-can-i-get-royalty-free-licensing-commitments). RF Commitments can in practice *only* be secured after publishing with the [“CR”](#candidate-recommendation) label. + +## “Normative” requirements? + +*Normative requirements* are any requirements that match the following definition [from the W3C Patent Policy](https://www.w3.org/policies/patent-policy/#dfn-norm): + +> *The normative portions of the Specification shall be deemed to include only architectural and interoperability requirements. Optional features in the RFC 2119 sense are considered normative unless they are specifically identified as informative. Implementation examples or any other material that merely illustrate the requirements of the Specification are informative, rather than normative.* + +That is, normative requirements are essentially any spec statements made using the [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) keywords *“must”, “must not”, “required”, “shall”, “shall not”, “should”, “should not”, “recommended”, “may”,* and *“optional”*. + +## “Substantive” changes? + +A *substantive change* to a spec is any deletion or addition or modification to [normative requirements](#normative-requirements) in the spec that might invalidate anyone’s previous review or implementation of those [normative requirements](#normative-requirements). + +Substantive changes include any of the following classes of changes: + +* changes that “make conforming data, processors, or other conforming agents become non-conforming” +* changes that “make non-conforming data, processors, or other agents become conforming” +* changes that “clear up an ambiguity or under-specified part of the spec in such a way that data, a processor, or an agent whose conformance was once unclear becomes clearly either conforming or non-conforming” +* changes that “add new functionality, such as new elements, new APIs, new rules, etc.” + +Substantive changes may expose a spec to new [Essential Claims](https://www.w3.org/policies/patent-policy/#essential-claims) — so, after any substantive changes are made to a spec, it should be [(re)published as a Snapshot](#how-can-i-get-royalty-free-licensing-commitments) so that a new [Exclusion Opportunity](#exclusion-opportunities) will be triggered. + +## What is a “Technical Report”? + +## What is “TR”? + +Anywhere you see or hear the term *Technical Report* or *TR*, substitute the term ***W3C Publication***. So, for example, you can read the beginning of the *W3C Technical Reports* section in the Process doc as: + +> #### *W3C Publications* +> +> *The W3C Publication development process is the set of steps and requirements followed by W3C Working Groups to standardize Web technology. The W3C Publication development process…* + +And you can read the heading of the *Types of Technical Reports* section as: + +> #### *Types of Publications* + +## What is “TR space”? + +*“TR space”* means [https://www.w3.org/TR](https://www.w3.org/TR) — it’s the area of the w3.org site under which the W3C publishes specs. So any time you see or hear *TR space*, substitute *W3C specs space* or *W3C publications space*. + +In other words, imagine that the [https://www.w3.org/TR](https://www.w3.org/TR) URL is instead actually the following URL: + +#### [https://w3.org/specs](https://w3.org/specs) + +In fact, if you want, you can actually already *use* that URL instead. Try it. Currently it (sorta) redirects to [https://www.w3.org/TR](https://www.w3.org/TR) — but maybe someday, things will be the other way around instead! + +## Recommendation Track? + +Anywhere you see or hear the term *Recommendation Track*, substitute the term ***Standards Track***. So, for example, you can read the beginning of the *The W3C Recommendation Track* section in the Process doc as: + +> #### *The Standards Track* +> +> *Working Groups create specifications and guidelines to complete the scope of work envisioned by a Working Group's charter. These W3C Publications undergo cycles of revision and review…* + +And you can read the beginning of the *Types of Technical Reports* section as: + +> #### *Types of Publications* +> +> *This chapter describes the formal requirements for publishing and maintaining a W3C Standard…* +> +> #### *Standards* +> +> *Working Groups develop W3C Publications on the W3C Standards Track in order to produce normative specifications or guidelines as standards for the Web. The Standards Track process incorporates…* + +## Candidate Recommendation? + +Everywhere you see *Candidate Recommendation*, substitute ***Working Group Specification*** — in this sense: + +1. The spec is just a *WG*-owned/endorsed spec — *not* a *W3C*-owned/endorsed one (that’s what a [REC](#recommendation) is). +2. The spec meets criteria for dropping the Working Draft warning label — criteria such as: + 1. [Consensus](#consensus) has been achieved within the group for dropping the Working Draft warning label. + 2. [Wide review](#wide-review) has been conducted thoroughly. + 3. [Implementation interest](https://whatwg.org/stages#terminology) has been clearly expressed by at least two implementors. + 4. [WPT tests](https://github.com/web-platform-tests/wpt) (or equivalent) are already written for all features in the spec. + 5. [Implementation bugs](https://github.com/whatwg/meta/blob/main/MAINTAINERS.md#handling-pull-requests) have been filed in the project bug/issue trackers of all target implementations. + 6. [An MDN issue](https://github.com/whatwg/meta/blob/main/MAINTAINERS.md#handling-pull-requests) has been filed, describing the docs that would need to be written for the spec. +3. The spec has either secured [RF Licensing Commitments](#how-can-i-get-royalty-free-licensing-commitments) or is at most 60 days away from securing them. + +That’s because initiating the process for dropping the Working Draft warning label is what you can/should do with a spec when your group believes it’s ready to be fully implemented — and ready to be thoroughly tested, with tests ready — and you want to secure [Royalty-Free Licensing Commitments](#how-can-i-get-royalty-free-licensing-commitments) for the spec. + +> [!NOTE] +> In the label *Candidate Recommendation*, you can think of the word *Candidate* as meaning *eligible*; that is, it indicates your spec is *eligible* for evaluation against the requirements for getting the Recommendation label — even if your Working Group has no *intention* to go through the process of getting it labeled as such. + +And if you *already* have multiple implementations (and a test suite) for a spec still labeled Working Draft, you probably should have already started the [steps for securing Royalty-Free Licensing Commitments](#how-can-i-get-royalty-free-licensing-commitments). + +### What are Snapshots? + +CR Snapshots are static date-stamped versions of the state of a spec — of all *features* [normatively defined](#normative-requirements) in a spec — *at a particular point in time*, intended solely for patent review toward a goal of securing [RF Commitments](#how-can-i-get-royalty-free-licensing-commitments). + +So, everywhere you see *Candidate Recommendation Snapshot*, substitute ***Patent Review Snapshot***. + +You typically publish new patent-review Snapshots at some regular cadence — for example, once every 6 months — *if* any [substantive spec changes](#substantive-changes) were made to the spec during the intervening time period. + +60 days after publishing a particular Snapshot, you secure [RF Commitments](#how-can-i-get-royalty-free-licensing-commitments) for *all* [normative](#normative-requirements) features it defines. + +> [!IMPORTANT] +> Due to their nature, **Snapshots are essentially disposable** and should never be used for any purpose at all after their related [RF Licensing Commitments](#rf-licensing-commitments) have been secured. That is, 60 days after it is published, a particular Snapshot effectively becomes completely obsolete for any purpose at all. +> +> In particular: **Implementors should *never* use Snapshot text as the basis from which they implement.** +> +> The reason for that is: In the intervening 60 days after that Snapshot was published, changes may have been made to spec text defining [normative requirements](#normative-requirements) for implementations of particular features — which means the state of the spec text in that Snapshot is possibly (or likely) already obsolete. +> +> Snapshots should also never be used for purposes such as feature versioning or feature profiling. + +### When to do Snapshots? + +When your group believes a spec is fully ready to be implemented — and ready for thorough testing — then, follow the [steps for securing Royalty-Free Licensing Commitments](#how-can-i-get-royalty-free-licensing-commitments), and [publish the first Snapshot](#how-can-i-get-royalty-free-licensing-commitments) for it. + +Then, at some regular cadence (say, once every 6 months) *and* if any [substantive changes](#substantive-changes) were made during that period, [republish a new Snapshot](#how-can-i-get-royalty-free-licensing-commitments) — solely in order to secure [RF Licensing Commitments](#rf-licensing-commitments) on those changes. + +### When to do CR *“Drafts”*? + +As you work with implementors and contributors and on tests — and, as you iteratively refine the spec contents — (re)publish the updated contents as [“Candidate Recommendation” (“CR”) “Drafts”](#when-to-do-cr-drafts) into [the w3.org/TR space](#what-is-tr-space). + +## Patent Review Draft? + +Anywhere you see or hear the term *Patent Review Draft*, you can in practice substitute *[Snapshot](#what-are-snapshots)*. Patent Review Drafts — [Snapshots](#candidate-recommendation) — are the stage at which [Royalty-Free Licensing Commitments](#rf-licensing-commitments) are actually are secured. + +### Exclusion Opportunities? + +An [Exclusion Opportunity](https://www.w3.org/policies/patent-policy/#sec-exclusion-with) is **limited-time chance** to exclude specific [Essential Claims](https://www.w3.org/policies/patent-policy/#essential-claims) from any [RF Commitments](#rf-licensing-commitments). + +There are two spec labels (publishing “stages”) which trigger an Exclusion Opportunity: [FPWD](#what-are-fpwds) and [CR](#candidate-recommendation). + +> [!IMPORTANT] +> The W3C Patent Policy mandates *[disclosure requirements](#disclosure-requirements)* — and: +> +> * The [disclosure requirements](#disclosure-requirements) for a particular Working Group begin at the moment when the creation of the group is first announced — that is, when the first Call for Participation for the group is announced. +> * All [disclosure requirements](#disclosure-requirements) are *ongoing*; specifically, they are in effect both before any [Patent Review Draft](#patent-review-draft) happens to be published, and also at all times after. + +### Disclosure Requirements? + +The term *“disclosure requirement”* refers to the obligation the [W3C Patent Policy](https://www.w3.org/policies/patent-policy/) places on W3C Members to disclose any knowledge of a patent believed to contain any [Essential Claim](https://www.w3.org/policies/patent-policy/#essential-claims) with respect to a particular spec. + +> [!IMPORTANT] +> Disclosure of any Essential Claims is an **ongoing obligation** — even though [Exclusion Opportunities](#exclusion-opportunities) are time-limited. + +The disclosure obligation is explicitly triggered any time a new version of a spec is published in [the w3.org/TR spec-publication space](#what-is-tr-space) — but also, to quote verbatim from [the relevant part of the W3C Patent Policy document](https://www.w3.org/policies/patent-policy/#sec-disclosure-timing): + +> *The [disclosure](https://www.w3.org/policies/patent-policy/#disclosure) obligation is an ongoing obligation that begins with the Call for Participation… In any case, disclosure as soon as practically possible is required.* + +## Recommendation? + +Everywhere you see the term *Recommendation* or *W3C Recommendation* on its own (rather than in *Candidate Recommendation*) substitute ***W3C Standard*** — in the sense of being a spec that: + +1. Has multiple existing interoperable implementations. +2. Has received the endorsement of the W3C and its Members. + +That’s because getting a spec labeled as a Recommendation is what you can do with it if your group can show it has multiple implementations (or may otherwise be deemed sufficiently implemented), and you want the spec to go through full W3C Advisory Committee review to receive formal endorsement from the W3C and its Members. + +However, even if your group *can* demonstrate a particular spec has been sufficiently implemented, you are not *required* to go through the process for getting it labeled as a W3C Recommendation. + +If your group decides you *don’t* want to have the spec formally endorsed by the W3C and its Members, you can instead choose to continue to ***[maintain](#spec-maintenance)*** it: by keeping it labeled with [“CR”](#candidate-recommendation) and [perpetually keeping it up to date](#living-standards). + +## Wide review? + +The principle of seeking out the widest-possible opportunities for review from the widest-possible set of reviewers. + +* Accessibility +* Security +* Privacy +* Internationalization + +* TAG + +## Consensus? + +Don’t disenfranchise. diff --git a/_config.yml b/_config.yml new file mode 100644 index 0000000..4f6900c --- /dev/null +++ b/_config.yml @@ -0,0 +1,2 @@ +markdown: kramdown +remote_theme: pages-themes/hacker@v0.2.0 diff --git a/_layouts/default.html b/_layouts/default.html new file mode 100644 index 0000000..c0c7ee4 --- /dev/null +++ b/_layouts/default.html @@ -0,0 +1,25 @@ + + + + + + + + + {% include head-custom.html %} + +{% seo %} + + + +
+ +
+ {{ content }} +
+
+ + + + + diff --git a/assets/css/style.scss b/assets/css/style.scss new file mode 100644 index 0000000..68d74cc --- /dev/null +++ b/assets/css/style.scss @@ -0,0 +1,112 @@ +--- +--- + +@import "{{ site.theme }}"; +body { + font-size: 16px; + font-family: -apple-system,BlinkMacSystemFont,"Segoe UI","Noto Sans",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"; +} +.toc.toc-right { + /* + * transform: translateX(0); + */ + right: calc((100% - 48rem - 4rem)/2); +} +.toc.toc-right { + /* + * transform: translateX(100%); + */ + right: 0; +} +.toc { + /* + * transform: translateX(0); + */ +} +.toc { + height: 100%; + width: 327px; + transform: translateX(0); +} +.transition--300 { + transition: all 300ms ease-in-out; +} +.is-position-fixed { + position: fixed !important; + top: 0; +} +.z-1 { + z-index: 1; +} +.pt5 { + padding-top: 4rem; +} +.pa4 { + padding: 2rem; +} +.absolute { + position: absolute; +} +.relative { + position: relative; +} +article, aside, footer, header, nav, section { + display: block; +} +* { + box-sizing: border-box; +} +.toc-list-item { + list-style: url("https://sideshowbarker.github.io/w3c-faq/assets/images/bullet.png") !important; +} +.toc > .toc-list:first-child > li:first-child { + list-style: none !important; +} +.toc-list { + padding-left: 16px !important; +} +.is-active-link::before { + color: rgb(184, 233, 90) !important; + } +.is-active-link { + color: rgb(184, 233, 90) !important; + text-shadow: rgba(0, 0, 0, 0.1) 0px 1px 1px, rgba(86, 111, 15, 0.1) 0px 0px 5px, rgba(86, 111, 15, 0.1) 0px 0px 10px !important; +} +section { + max-width: 859px; +} +h1 { + margin-top: 32px; + border-bottom: 1px dashed #b5e853; + padding-bottom: 16px; +} +h2, h3 { + margin: 60px 0 6px; +} +h3 { + margin-top: 32px; +} +h2 + h2, h3 + h3 { + margin-top: 0px !important; +} +h2 + p, h3 + p { + margin-top: 8px; +} +h1, h2, h3 { + line-height: 1.1; +} +blockquote { + margin-left: 3px; + border-left: .25em solid rgb(184, 233, 90) !important; + border-left-color: rgb(184, 233, 90) !important; +} +blockquote p:first-of-type::first-line { + color: magenta; +} +a { + text-decoration: none; +} +code { + font-size: 15px; + color: orange !important; +} diff --git a/assets/css/tocbot.css b/assets/css/tocbot.css new file mode 100644 index 0000000..0c747c0 --- /dev/null +++ b/assets/css/tocbot.css @@ -0,0 +1 @@ +.toc{overflow-y:auto}.toc>.toc-list{overflow:hidden;position:relative}.toc>.toc-list li{list-style:none}.toc-list{margin:0;padding-left:10px}a.toc-link{color:currentColor;height:100%}.is-collapsible{max-height:1000px;overflow:hidden;transition:all 300ms ease-in-out}.is-collapsed{max-height:0}.is-position-fixed{position:fixed !important;top:0}.is-active-link{font-weight:700}.toc-link::before{background-color:#eee;content:" ";display:inline-block;height:inherit;left:0;margin-top:-1px;position:absolute;width:2px}.is-active-link::before{background-color:#54bc4b}/*# sourceMappingURL=tocbot.css.map */ diff --git a/assets/images/bullet.png b/assets/images/bullet.png new file mode 100644 index 0000000..0614eb6 Binary files /dev/null and b/assets/images/bullet.png differ diff --git a/assets/js/anchor.min.js b/assets/js/anchor.min.js new file mode 100644 index 0000000..5ac814d --- /dev/null +++ b/assets/js/anchor.min.js @@ -0,0 +1,9 @@ +// @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt Expat +// +// AnchorJS - v5.0.0 - 2023-01-18 +// https://www.bryanbraun.com/anchorjs/ +// Copyright (c) 2023 Bryan Braun; Licensed MIT +// +// @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt Expat +!function(A,e){"use strict";"function"==typeof define&&define.amd?define([],e):"object"==typeof module&&module.exports?module.exports=e():(A.AnchorJS=e(),A.anchors=new A.AnchorJS)}(globalThis,function(){"use strict";return function(A){function u(A){A.icon=Object.prototype.hasOwnProperty.call(A,"icon")?A.icon:"",A.visible=Object.prototype.hasOwnProperty.call(A,"visible")?A.visible:"hover",A.placement=Object.prototype.hasOwnProperty.call(A,"placement")?A.placement:"right",A.ariaLabel=Object.prototype.hasOwnProperty.call(A,"ariaLabel")?A.ariaLabel:"Anchor",A.class=Object.prototype.hasOwnProperty.call(A,"class")?A.class:"",A.base=Object.prototype.hasOwnProperty.call(A,"base")?A.base:"",A.truncate=Object.prototype.hasOwnProperty.call(A,"truncate")?Math.floor(A.truncate):64,A.titleText=Object.prototype.hasOwnProperty.call(A,"titleText")?A.titleText:""}function d(A){var e;if("string"==typeof A||A instanceof String)e=[].slice.call(document.querySelectorAll(A));else{if(!(Array.isArray(A)||A instanceof NodeList))throw new TypeError("The selector provided to AnchorJS was invalid.");e=[].slice.call(A)}return e}this.options=A||{},this.elements=[],u(this.options),this.add=function(A){var e,t,o,i,n,s,a,r,l,c,h,p=[];if(u(this.options),0!==(e=d(A=A||"h2, h3, h4, h5, h6")).length){for(null===document.head.querySelector("style.anchorjs")&&((A=document.createElement("style")).className="anchorjs",A.appendChild(document.createTextNode("")),void 0===(h=document.head.querySelector('[rel="stylesheet"],style'))?document.head.appendChild(A):document.head.insertBefore(A,h),A.sheet.insertRule(".anchorjs-link{opacity:0;text-decoration:none;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}",A.sheet.cssRules.length),A.sheet.insertRule(":hover>.anchorjs-link,.anchorjs-link:focus{opacity:1}",A.sheet.cssRules.length),A.sheet.insertRule("[data-anchorjs-icon]::after{content:attr(data-anchorjs-icon)}",A.sheet.cssRules.length),A.sheet.insertRule('@font-face{font-family:anchorjs-icons;src:url(data:n/a;base64,AAEAAAALAIAAAwAwT1MvMg8yG2cAAAE4AAAAYGNtYXDp3gC3AAABpAAAAExnYXNwAAAAEAAAA9wAAAAIZ2x5ZlQCcfwAAAH4AAABCGhlYWQHFvHyAAAAvAAAADZoaGVhBnACFwAAAPQAAAAkaG10eASAADEAAAGYAAAADGxvY2EACACEAAAB8AAAAAhtYXhwAAYAVwAAARgAAAAgbmFtZQGOH9cAAAMAAAAAunBvc3QAAwAAAAADvAAAACAAAQAAAAEAAHzE2p9fDzz1AAkEAAAAAADRecUWAAAAANQA6R8AAAAAAoACwAAAAAgAAgAAAAAAAAABAAADwP/AAAACgAAA/9MCrQABAAAAAAAAAAAAAAAAAAAAAwABAAAAAwBVAAIAAAAAAAIAAAAAAAAAAAAAAAAAAAAAAAMCQAGQAAUAAAKZAswAAACPApkCzAAAAesAMwEJAAAAAAAAAAAAAAAAAAAAARAAAAAAAAAAAAAAAAAAAAAAQAAg//0DwP/AAEADwABAAAAAAQAAAAAAAAAAAAAAIAAAAAAAAAIAAAACgAAxAAAAAwAAAAMAAAAcAAEAAwAAABwAAwABAAAAHAAEADAAAAAIAAgAAgAAACDpy//9//8AAAAg6cv//f///+EWNwADAAEAAAAAAAAAAAAAAAAACACEAAEAAAAAAAAAAAAAAAAxAAACAAQARAKAAsAAKwBUAAABIiYnJjQ3NzY2MzIWFxYUBwcGIicmNDc3NjQnJiYjIgYHBwYUFxYUBwYGIwciJicmNDc3NjIXFhQHBwYUFxYWMzI2Nzc2NCcmNDc2MhcWFAcHBgYjARQGDAUtLXoWOR8fORYtLTgKGwoKCjgaGg0gEhIgDXoaGgkJBQwHdR85Fi0tOAobCgoKOBoaDSASEiANehoaCQkKGwotLXoWOR8BMwUFLYEuehYXFxYugC44CQkKGwo4GkoaDQ0NDXoaShoKGwoFBe8XFi6ALjgJCQobCjgaShoNDQ0NehpKGgobCgoKLYEuehYXAAAADACWAAEAAAAAAAEACAAAAAEAAAAAAAIAAwAIAAEAAAAAAAMACAAAAAEAAAAAAAQACAAAAAEAAAAAAAUAAQALAAEAAAAAAAYACAAAAAMAAQQJAAEAEAAMAAMAAQQJAAIABgAcAAMAAQQJAAMAEAAMAAMAAQQJAAQAEAAMAAMAAQQJAAUAAgAiAAMAAQQJAAYAEAAMYW5jaG9yanM0MDBAAGEAbgBjAGgAbwByAGoAcwA0ADAAMABAAAAAAwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAH//wAP) format("truetype")}',A.sheet.cssRules.length)),h=document.querySelectorAll("[id]"),t=[].map.call(h,function(A){return A.id}),i=0;i\]./()*\\\n\t\b\v\u00A0]/g,"-").replace(/-{2,}/g,"-").substring(0,this.options.truncate).replace(/^-+|-+$/gm,"").toLowerCase()},this.hasAnchorJSLink=function(A){var e=A.firstChild&&-1<(" "+A.firstChild.className+" ").indexOf(" anchorjs-link "),A=A.lastChild&&-1<(" "+A.lastChild.className+" ").indexOf(" anchorjs-link ");return e||A||!1}}}); +// @license-end \ No newline at end of file diff --git a/assets/js/script.js b/assets/js/script.js new file mode 100644 index 0000000..3799ba1 --- /dev/null +++ b/assets/js/script.js @@ -0,0 +1,27 @@ +document.querySelector("h1").textContent = "An Outsider’s Guide to the W3C"; +const replaceOnDocument = (pattern, string, {target = document.body} = {}) => { + // Handle `string` — see the last section + [ + target, + ...target.querySelectorAll("*:not(script):not(noscript):not(style)") + ].forEach(({childNodes: [...nodes]}) => nodes + .filter(({nodeType}) => nodeType === Node.TEXT_NODE) + .forEach((textNode) => textNode.textContent = textNode.textContent.replace(pattern, string))); +}; +replaceOnDocument(/\[!IMPORTANT\]/g, "👋 Important: "); +replaceOnDocument(/\[!NOTE\]/g, "👉 Note: "); + +anchors.options.placement = 'left'; +document.addEventListener('DOMContentLoaded', function(event) { anchors.add(); }); + +tocbot.init({ + // Where to render the table of contents. + tocSelector: '.js-toc', + // Where to grab the headings to build the table of contents. + contentSelector: '.js-toc-content', + // Which headings to grab inside of the contentSelector element. + headingSelector: 'h1, h2, h3, h4', + // For headings inside relative or absolute positioned containers within content. + hasInnerContainers: true, + orderedList: false, +}); diff --git a/assets/js/tocbot.min.js b/assets/js/tocbot.min.js new file mode 100644 index 0000000..c142b53 --- /dev/null +++ b/assets/js/tocbot.min.js @@ -0,0 +1 @@ +(()=>{var e={539:(e,t,n)=>{var o,l,r;l=[],void 0===(r="function"==typeof(o=function(e){"use strict";const t=!!(e&&e.document&&e.document.querySelector&&e.addEventListener);if("undefined"==typeof window&&!t)return;const o=n(496);return e.tocbot=o,o}(void 0!==n.g?n.g:window||n.g))?o.apply(t,l):o)||(e.exports=r)},496:(e,t,n)=>{"use strict";function o(e){var t,n=[].forEach,o=[].some,l=document.body,r=!0,i=" ";function s(t,o){var l,r,a,u=o.appendChild((l=t,r=document.createElement("li"),a=document.createElement("a"),e.listItemClass&&r.setAttribute("class",e.listItemClass),e.onClick&&(a.onclick=e.onClick),e.includeTitleTags&&a.setAttribute("title",l.textContent),e.includeHtml&&l.childNodes.length?n.call(l.childNodes,(function(e){a.appendChild(e.cloneNode(!0))})):a.textContent=l.textContent,a.setAttribute("href",e.basePath+"#"+l.id),a.setAttribute("class",e.linkClass+i+"node-name--"+l.nodeName+i+e.extraLinkClasses),r.appendChild(a),r));if(t.children.length){var d=c(t.isCollapsed);t.children.forEach((function(e){s(e,d)})),u.appendChild(d)}}function c(t){var n=e.orderedList?"ol":"ul",o=document.createElement(n),l=e.listClass+i+e.extraListClasses;return t&&(l=(l=l+i+e.collapsibleClass)+i+e.isCollapsedClass),o.setAttribute("class",l),o}function a(t){var n=0;return null!==t&&(n=t.offsetTop,e.hasInnerContainers&&(n+=a(t.offsetParent))),n}function u(e,t){return e&&e.className!==t&&(e.className=t),e}function d(t){return t&&-1!==t.className.indexOf(e.collapsibleClass)&&-1!==t.className.indexOf(e.isCollapsedClass)?(u(t,t.className.replace(i+e.isCollapsedClass,"")),d(t.parentNode.parentNode)):t}return{enableTocAnimation:function(){r=!0},disableTocAnimation:function(t){var n=t.target||t.srcElement;"string"==typeof n.className&&-1!==n.className.indexOf(e.linkClass)&&(r=!1)},render:function(e,n){var o=c(!1);if(n.forEach((function(e){s(e,o)})),null!==(t=e||t))return t.firstChild&&t.removeChild(t.firstChild),0===n.length?t:t.appendChild(o)},updateToc:function(s){var c;c=e.scrollContainer&&document.querySelector(e.scrollContainer)?document.querySelector(e.scrollContainer).scrollTop:document.documentElement.scrollTop||l.scrollTop,e.positionFixedSelector&&function(){var n;n=e.scrollContainer&&document.querySelector(e.scrollContainer)?document.querySelector(e.scrollContainer).scrollTop:document.documentElement.scrollTop||l.scrollTop;var o=document.querySelector(e.positionFixedSelector);"auto"===e.fixedSidebarOffset&&(e.fixedSidebarOffset=t.offsetTop),n>e.fixedSidebarOffset?-1===o.className.indexOf(e.positionFixedClass)&&(o.className+=i+e.positionFixedClass):o.className=o.className.replace(i+e.positionFixedClass,"")}();var f,m=s;if(r&&null!==t&&m.length>0){o.call(m,(function(t,n){return a(t)>c+e.headingsOffset+10?(f=m[0===n?n:n-1],!0):n===m.length-1?(f=m[m.length-1],!0):void 0}));var h=t.querySelector("."+e.activeLinkClass),p=t.querySelector("."+e.linkClass+".node-name--"+f.nodeName+'[href="'+e.basePath+"#"+f.id.replace(/([ #;&,.+*~':"!^$[\]()=>|/\\@])/g,"\\$1")+'"]');if(h===p)return;var C=t.querySelectorAll("."+e.linkClass);n.call(C,(function(t){u(t,t.className.replace(i+e.activeLinkClass,""))}));var g=t.querySelectorAll("."+e.listItemClass);n.call(g,(function(t){u(t,t.className.replace(i+e.activeListItemClass,""))})),p&&-1===p.className.indexOf(e.activeLinkClass)&&(p.className+=i+e.activeLinkClass);var v=p&&p.parentNode;v&&-1===v.className.indexOf(e.activeListItemClass)&&(v.className+=i+e.activeListItemClass);var S=t.querySelectorAll("."+e.listClass+"."+e.collapsibleClass);n.call(S,(function(t){-1===t.className.indexOf(e.isCollapsedClass)&&(t.className+=i+e.isCollapsedClass)})),p&&p.nextSibling&&-1!==p.nextSibling.className.indexOf(e.isCollapsedClass)&&u(p.nextSibling,p.nextSibling.className.replace(i+e.isCollapsedClass,"")),d(p&&p.parentNode.parentNode)}}}}n.r(t),n.d(t,{_buildHtml:()=>s,_headingsArray:()=>a,_options:()=>f,_parseContent:()=>c,_scrollListener:()=>u,destroy:()=>h,init:()=>m,refresh:()=>p});const l={tocSelector:".js-toc",contentSelector:".js-toc-content",headingSelector:"h1, h2, h3",ignoreSelector:".js-toc-ignore",hasInnerContainers:!1,linkClass:"toc-link",extraLinkClasses:"",activeLinkClass:"is-active-link",listClass:"toc-list",extraListClasses:"",isCollapsedClass:"is-collapsed",collapsibleClass:"is-collapsible",listItemClass:"toc-list-item",activeListItemClass:"is-active-li",collapseDepth:0,scrollSmooth:!0,scrollSmoothDuration:420,scrollSmoothOffset:0,scrollEndCallback:function(e){},headingsOffset:1,throttleTimeout:50,positionFixedSelector:null,positionFixedClass:"is-position-fixed",fixedSidebarOffset:"auto",includeHtml:!1,includeTitleTags:!1,onClick:function(e){},orderedList:!0,scrollContainer:null,skipRendering:!1,headingLabelCallback:!1,ignoreHiddenElements:!1,headingObjectCallback:null,basePath:"",disableTocScrollSync:!1,tocScrollOffset:0};function r(e){var t=e.duration,n=e.offset,o=location.hash?l(location.href):location.href;function l(e){return e.slice(0,e.lastIndexOf("#"))}document.body.addEventListener("click",(function(r){var i;"a"!==(i=r.target).tagName.toLowerCase()||!(i.hash.length>0||"#"===i.href.charAt(i.href.length-1))||l(i.href)!==o&&l(i.href)+"#"!==o||r.target.className.indexOf("no-smooth-scroll")>-1||"#"===r.target.href.charAt(r.target.href.length-2)&&"!"===r.target.href.charAt(r.target.href.length-1)||-1===r.target.className.indexOf(e.linkClass)||function(e,t){var n,o,l=window.pageYOffset,r={duration:t.duration,offset:t.offset||0,callback:t.callback,easing:t.easing||function(e,t,n,o){return(e/=o/2)<1?n/2*e*e+t:-n/2*(--e*(e-2)-1)+t}},i=document.querySelector('[id="'+decodeURI(e).split("#").join("")+'"]')||document.querySelector('[id="'+e.split("#").join("")+'"]'),s="string"==typeof e?r.offset+(e?i&&i.getBoundingClientRect().top||0:-(document.documentElement.scrollTop||document.body.scrollTop)):e,c="function"==typeof r.duration?r.duration(s):r.duration;function a(e){o=e-n,window.scrollTo(0,r.easing(o,l,s,c)),o0&&(!(c=n(s))||i!==c.headingLevel);)c&&void 0!==c.children&&(s=c.children),a--;i>=e.collapseDepth&&(r.isCollapsed=!0),s.push(r)}(r,t.nest),t}),{nest:[]})},selectHeadings:function(t,n){var o=n;e.ignoreSelector&&(o=n.split(",").map((function(t){return t.trim()+":not("+e.ignoreSelector+")"})));try{return t.querySelectorAll(o)}catch(e){return console.warn("Headers not found with selector: "+o),null}}}}(f),h();const t=function(e){try{return e.contentElement||document.querySelector(e.contentSelector)}catch(t){return console.warn("Contents element not found: "+e.contentSelector),null}}(f);if(null===t)return;const n=v(f);if(null===n)return;if(a=c.selectHeadings(t,f.headingSelector),null===a)return;const m=c.nestHeadingsArray(a).nest;if(f.skipRendering)return this;s.render(n,m),u=g((function(e){s.updateToc(a),!f.disableTocScrollSync&&function(e){var t=e.tocElement||document.querySelector(e.tocSelector);if(t&&t.scrollHeight>t.clientHeight){var n=t.querySelector("."+e.activeListItemClass);if(n){var o=t.scrollTop,l=o+t.clientHeight,r=n.offsetTop,s=r+n.clientHeight;rl-e.tocScrollOffset-i&&(t.scrollTop+=s-l+e.tocScrollOffset+2*i)}}}(f);const t=e&&e.target&&e.target.scrollingElement&&0===e.target.scrollingElement.scrollTop;(e&&(0===e.eventPhase||null===e.currentTarget)||t)&&(s.updateToc(a),f.scrollEndCallback&&f.scrollEndCallback(e))}),f.throttleTimeout),u(),f.scrollContainer&&document.querySelector(f.scrollContainer)?(document.querySelector(f.scrollContainer).addEventListener("scroll",u,!1),document.querySelector(f.scrollContainer).addEventListener("resize",u,!1)):(document.addEventListener("scroll",u,!1),document.addEventListener("resize",u,!1));let p=null;d=g((function(e){f.scrollSmooth&&s.disableTocAnimation(e),s.updateToc(a),p&&clearTimeout(p),p=setTimeout((function(){s.enableTocAnimation()}),f.scrollSmoothDuration)}),f.throttleTimeout),f.scrollContainer&&document.querySelector(f.scrollContainer)?document.querySelector(f.scrollContainer).addEventListener("click",d,!1):document.addEventListener("click",d,!1)}function h(){const e=v(f);null!==e&&(f.skipRendering||e&&(e.innerHTML=""),f.scrollContainer&&document.querySelector(f.scrollContainer)?(document.querySelector(f.scrollContainer).removeEventListener("scroll",u,!1),document.querySelector(f.scrollContainer).removeEventListener("resize",u,!1),s&&document.querySelector(f.scrollContainer).removeEventListener("click",d,!1)):(document.removeEventListener("scroll",u,!1),document.removeEventListener("resize",u,!1),s&&document.removeEventListener("click",d,!1)))}function p(e){h(),m(e||f)}const C=Object.prototype.hasOwnProperty;function g(e,t,n){let o,l;return t||(t=250),function(){const r=n||this,i=+new Date,s=arguments;o&&i{for(var o in t)n.o(t,o)&&!n.o(e,o)&&Object.defineProperty(e,o,{enumerable:!0,get:t[o]})},n.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),n.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t),n.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},n(539)})(); \ No newline at end of file