Skip to content

Commit

Permalink
rephrase
Browse files Browse the repository at this point in the history
  • Loading branch information
@tabatkins
tabatkins committed Oct 31, 2024
1 parent 78c2626 commit 6cae8cf
Show file tree
Hide file tree
Showing 2 changed files with 30 additions and 25 deletions.
7 changes: 5 additions & 2 deletions docs/index.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3860,9 +3860,12 @@ pointing to the test covering some nearby text.
If all or most of your tests have a common path prefix,
you can specify it in [=WPT Path Prefix=] metadata,
and then leave it off of all the individual test lines.
This also triggers Bikeshed to complain if it knows of any tests under that prefix
that don't show up in your spec.

An explicit <dfn element-attr for="wpt, wpt-rest">pathprefix</dfn> attribute
can also provide the path prefix,
and will override the metadata if specified.
can also provide the path prefix for a single <{wpt}> block,
overriding the metadata if specified.

<div class=example>
If the preceding example used [=WPT Path Prefix=],
Expand Down
48 changes: 25 additions & 23 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1488,9 +1488,9 @@
}
}
</style>
<meta content="Bikeshed version e716a693a, updated Mon Oct 21 15:59:55 2024 -0700" name="generator">
<meta content="Bikeshed version 3686d71cf, updated Fri Oct 25 15:50:59 2024 -0700" name="generator">
<link href="https://speced.github.io/bikeshed/" rel="canonical">
<meta content="e716a693ae20f5d13bce97741ac3cabcd4970a84" name="revision">
<meta content="3686d71cf70b4e396c75979cdc74abe37801a2f6" name="revision">
<meta content="dark light" name="color-scheme">
<style>/* Boilerplate: style-autolinks */
.css.css, .property.property, .descriptor.descriptor {
Expand Down Expand Up @@ -5830,7 +5830,7 @@ <h2 class="heading settled" data-level="11" id="testing"><span class="secno">11.
the canonical way to test new features and ensure interoperability
is to contribute the testsuite to the <a href="https://wpt.fyi/about">Web Platform Tests</a> project.
Bikeshed has some useful tools to interact with WPT information.</p>
<h3 class="heading settled dfn-paneled" data-dfn-type="element" data-export data-level="11.1" data-lt="wpt" id="wpt-element"><span class="secno">11.1. </span><span class="content"> Annotating Specs with Tests: the <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element③">wpt</a></code> element</span><a class="self-link" href="#wpt-element" id="ref-for-wpt-element②②"></a></h3>
<h3 class="heading settled dfn-paneled" data-dfn-type="element" data-export data-level="11.1" data-lt="wpt" id="wpt-element"><span class="secno">11.1. </span><span class="content"> Annotating Specs with Tests: the <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element③">wpt</a></code> element</span><a class="self-link" href="#wpt-element" id="ref-for-wpt-element②③"></a></h3>
<p>When writing tests,
you can sometimes link to the section of the spec that you’re testing,
to make it easier to review.
Expand Down Expand Up @@ -5860,12 +5860,14 @@ <h3 class="heading settled dfn-paneled" data-dfn-type="element" data-export data
<p>If all or most of your tests have a common path prefix,
you can specify it in <a data-link-type="dfn" href="#metadata-wpt-path-prefix" id="ref-for-metadata-wpt-path-prefix">WPT Path Prefix</a> metadata,
and then leave it off of all the individual test lines.
An explicit <dfn class="dfn-paneled" data-dfn-for="wpt, wpt-rest" data-dfn-type="element-attr" data-export id="element-attrdef-wpt-pathprefix"><code>pathprefix</code></dfn> attribute
can also provide the path prefix,
and will override the metadata if specified.</p>
This also triggers Bikeshed to complain if it knows of any tests under that prefix
that don’t show up in your spec.</p>
<p>An explicit <dfn class="dfn-paneled" data-dfn-for="wpt, wpt-rest" data-dfn-type="element-attr" data-export id="element-attrdef-wpt-pathprefix"><code>pathprefix</code></dfn> attribute
can also provide the path prefix for a single <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element⑥">wpt</a></code> block,
overriding the metadata if specified.</p>
<div class="example" id="example-123bb00c">
<a class="self-link" href="#example-123bb00c"></a> If the preceding example used <a data-link-type="dfn" href="#metadata-wpt-path-prefix" id="ref-for-metadata-wpt-path-prefix①">WPT Path Prefix</a>,
the <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element⑥">wpt</a></code> element could be shorter:
the <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element⑦">wpt</a></code> element could be shorter:
<pre class="highlight"><c- p>&lt;</c-><c- f>pre</c-> <c- e>class</c-><c- o>=</c-><c- s>metadata</c-><c- p>></c->
WPT Display: open
WPT Path Prefix: /foo-spec/
Expand All @@ -5891,56 +5893,56 @@ <h3 class="heading settled dfn-paneled" data-dfn-type="element" data-export data
</div>
<p>For debugging purposes,
a single <dfn class="dfn-paneled" data-dfn-type="element" data-export data-lt="wpt-rest" id="elementdef-wpt-rest"><code>&lt;wpt-rest></code></dfn> element can be used in a spec,
which will act like a <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element⑦">wpt</a></code> element containing all the tests under the current path prefix
that aren’t already specified in a <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element⑧">wpt</a></code> element.
which will act like a <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element⑧">wpt</a></code> element containing all the tests under the current path prefix
that aren’t already specified in a <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element⑨">wpt</a></code> element.
As this defeats Bikeshed’s ability to tell you when you’re missing any tests,
Bikeshed will emit a warning as long as a <code><a data-link-type="element" href="#elementdef-wpt-rest" id="ref-for-elementdef-wpt-rest">wpt-rest</a></code> element is in use.</p>
<p>Bikeshed’s knowledge of valid tests allows some useful checks:</p>
<ul>
<li data-md>
<p>If <a data-link-type="dfn" href="#metadata-wpt-path-prefix" id="ref-for-metadata-wpt-path-prefix②">WPT Path Prefix</a> is specified,
then any tests under that prefix that aren’t specified in a <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element⑨">wpt</a></code> element
then any tests under that prefix that aren’t specified in a <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①⓪">wpt</a></code> element
will trigger a fatal error,
so you’ll be alerted when new tests are added.</p>
<li data-md>
<p>If you specify a path that doesn’t exist
(or <em>no longer</em> exists due to tests being moved or deleted),
it will trigger a fatal error.</p>
<p>This check can be disabled for a given <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①⓪">wpt</a></code> element
<p>This check can be disabled for a given <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①①">wpt</a></code> element
by giving it the <dfn class="dfn-paneled idl-code" data-dfn-for="wpt" data-dfn-type="attribute" data-export id="dom-wpt-skip-existence-check"><code>skip-existence-check</code></dfn> boolean attribute.
This allows you to point to private tests,
such as those in browser-specific repos,
without receiving errors about those tests missing
from the main WPT repository.</p>
</ul>
<p>By default, <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①①">wpt</a></code> elements don’t display in the output document;
<p>By default, <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①②">wpt</a></code> elements don’t display in the output document;
they’re intended to annotate the source file to help with spec authoring,
and trigger Bikeshed’s checks.
If you want to produce a test-annotated version of the output,
specify the <a data-link-type="dfn" href="#metadata-wpt-display" id="ref-for-metadata-wpt-display">WPT Display</a> metadata with the value "open" or "closed";
all of the <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①②">wpt</a></code> elements will become usefully-formatted lists of their contained tests,
all of the <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①③">wpt</a></code> elements will become usefully-formatted lists of their contained tests,
with links to <a href="https://wpt.fyi">wpt.fyi</a>,
the live test on <a href="https://w3c-test.org">w3c-test.org</a>,
and the source code on <a href="https://github.com/web-platform-tests/wpt">GitHub</a>.
The difference between "open" and "closed" is that
with the former, all <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①③">wpt</a></code> elements are initially displayed in a collapsed state
with the former, all <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①④">wpt</a></code> elements are initially displayed in a collapsed state
to avoid getting in the way of reading the document,
while "open" causes them to be expanded initially.
In either case, the use can interactively collapse or expand each element.</p>
<figure>
<img height="195" src="images/wpt-display-open.png" srcset="images/wpt-display-open.png 2x" width="600">
<figcaption> When <code>WPT Display: open</code> is set,
the <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①④">wpt</a></code> element turns into a "TESTS" block. </figcaption>
the <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①⑤">wpt</a></code> element turns into a "TESTS" block. </figcaption>
</figure>
<figure>
<img height="104" src="images/wpt-display-closed.png" srcset="images/wpt-display-closed.png 2x" width="600">
<figcaption> When <code>WPT Display: closed</code> is set,
the <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①⑤">wpt</a></code> element also turns into a "TESTS" block,
the <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①⑥">wpt</a></code> element also turns into a "TESTS" block,
but it is initially collapsed. </figcaption>
</figure>
<p class="note" role="note"><span class="marker">Note:</span> For compatibility with earlier versions of Bikshed,
"inline" is accepted as a synonym of "open".</p>
<p>When the <a data-link-type="element-attr" href="https://html.spec.whatwg.org/multipage/interaction.html#attr-hidden" id="ref-for-attr-hidden">hidden</a> attribute is set on the <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①⑥">wpt</a></code> element,
<p>When the <a data-link-type="element-attr" href="https://html.spec.whatwg.org/multipage/interaction.html#attr-hidden" id="ref-for-attr-hidden">hidden</a> attribute is set on the <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①⑦">wpt</a></code> element,
Bikeshed will take the tests listed in that element into account,
but exclude them from the output,
even when producing a test-annotated version.</p>
Expand All @@ -5953,12 +5955,12 @@ <h3 class="heading settled dfn-paneled" data-dfn-type="element" data-export data
In such cases,
listing the tests in a <code class="highlight"><c- p>&lt;</c-><c- f>wpt</c-> <c- e>hidden</c-><c- p>></c-></code> element silences the warnings,
without adding anything irrelevant to the output.</p>
<p>Information about a set of tests described in a <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①⑦">wpt</a></code> element
<p>Information about a set of tests described in a <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①⑧">wpt</a></code> element
can be provided to the reader
by writing it in the <a data-link-type="element-attr" href="https://html.spec.whatwg.org/multipage/dom.html#attr-title" id="ref-for-attr-title">title</a> attribute of the <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①⑧">wpt</a></code> element.
by writing it in the <a data-link-type="element-attr" href="https://html.spec.whatwg.org/multipage/dom.html#attr-title" id="ref-for-attr-title">title</a> attribute of the <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①⑨">wpt</a></code> element.
This will be inserted in the output as an introductory paragraph
before the test list.
A <a data-link-type="element-attr" href="https://html.spec.whatwg.org/multipage/dom.html#attr-lang" id="ref-for-attr-lang">lang</a> or <a data-link-type="element-attr" href="https://html.spec.whatwg.org/multipage/dom.html#attr-dir" id="ref-for-attr-dir">dir</a> set on the <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element①⑨">wpt</a></code> element
A <a data-link-type="element-attr" href="https://html.spec.whatwg.org/multipage/dom.html#attr-lang" id="ref-for-attr-lang">lang</a> or <a data-link-type="element-attr" href="https://html.spec.whatwg.org/multipage/dom.html#attr-dir" id="ref-for-attr-dir">dir</a> set on the <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element②⓪">wpt</a></code> element
will apply to the introductory paragraph if there is one.</p>
<div class="example" id="example-1076be64">
<a class="self-link" href="#example-1076be64"></a>
Expand All @@ -5977,15 +5979,15 @@ <h3 class="heading settled dfn-paneled" data-dfn-type="element" data-export data
<p>The test block in the example above would be rendered as follows:</p>
<figure> <img alt="A WPT element with a list of tests, preceded by an introductory paragraph" height="168" src="images/tests-with-intro.png" srcset="images/tests-with-intro.png 2x" width="624"> </figure>
</div>
<p>If multiple <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element②⓪">wpt</a></code> follow each other in the source,
<p>If multiple <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element②①">wpt</a></code> follow each other in the source,
with nothing between them other than whitespace,
they will be fused together in the output,
visually taking less space than if they remained as separate elements.
This will work even
if they have different <a data-link-type="element-attr" href="#element-attrdef-wpt-pathprefix" id="ref-for-element-attrdef-wpt-pathprefix">pathprefix</a> or <a data-link-type="element-attr" href="https://html.spec.whatwg.org/multipage/dom.html#attr-title" id="ref-for-attr-title①">title</a> attributes.
When merging elements with <a data-link-type="element-attr" href="https://html.spec.whatwg.org/multipage/dom.html#attr-title" id="ref-for-attr-title②">title</a> attributes,
the tests listed in each element will be preceded by the relevant introductory paragraph,
and visually separated from tests listed in different <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element②①">wpt</a></code> elements.</p>
and visually separated from tests listed in different <code><a data-link-type="element" href="#wpt-element" id="ref-for-wpt-element②②">wpt</a></code> elements.</p>
<p class="note" role="note"><span class="marker">Note:</span> More tools and options for integrating with WPT will be developed in the future.</p>
<h3 class="heading settled" data-level="11.2" id="updating-tests"><span class="secno">11.2. </span><span class="content">Updating Lists of Tests</span><a class="self-link" href="#updating-tests"></a></h3>
<p>If Bikeshed reports that a test doesn’t exist,
Expand Down Expand Up @@ -7497,7 +7499,7 @@ <h2 class="no-num no-ref heading settled" id="issues-index"><span class="content
"railroad-terminal": {"dfnID":"railroad-terminal","dfnText":"Terminal","external":false,"refSections":[],"url":"#railroad-terminal"},
"railroad-zeroormore": {"dfnID":"railroad-zeroormore","dfnText":"ZeroOrMore","external":false,"refSections":[{"refs":[{"id":"ref-for-railroad-zeroormore"}],"title":"13.1. The Diagram Language"}],"url":"#railroad-zeroormore"},
"soft-boolish": {"dfnID":"soft-boolish","dfnText":"soft boolish","external":false,"refSections":[{"refs":[{"id":"ref-for-soft-boolish"},{"id":"ref-for-soft-boolish\u2460"}],"title":"4. Metadata"}],"url":"#soft-boolish"},
"wpt-element": {"dfnID":"wpt-element","dfnText":"11.1. \nAnnotating Specs with Tests: the wpt element","external":false,"refSections":[{"refs":[{"id":"ref-for-wpt-element"},{"id":"ref-for-wpt-element\u2460"},{"id":"ref-for-wpt-element\u2461"}],"title":"4. Metadata"},{"refs":[{"id":"ref-for-wpt-element\u2462"},{"id":"ref-for-wpt-element"},{"id":"ref-for-wpt-element\u2463"},{"id":"ref-for-wpt-element\u2464"},{"id":"ref-for-wpt-element\u2465"},{"id":"ref-for-wpt-element\u2466"},{"id":"ref-for-wpt-element\u2467"},{"id":"ref-for-wpt-element\u2468"},{"id":"ref-for-wpt-element\u2460\u24ea"},{"id":"ref-for-wpt-element\u2460\u2460"},{"id":"ref-for-wpt-element\u2460\u2461"},{"id":"ref-for-wpt-element\u2460\u2462"},{"id":"ref-for-wpt-element\u2460\u2463"},{"id":"ref-for-wpt-element\u2460\u2464"},{"id":"ref-for-wpt-element\u2460\u2465"},{"id":"ref-for-wpt-element\u2460\u2466"},{"id":"ref-for-wpt-element\u2460\u2467"},{"id":"ref-for-wpt-element\u2460\u2468"},{"id":"ref-for-wpt-element\u2461\u24ea"},{"id":"ref-for-wpt-element\u2461\u2460"}],"title":"11.1. \nAnnotating Specs with Tests: the wpt element"}],"url":"#wpt-element"},
"wpt-element": {"dfnID":"wpt-element","dfnText":"11.1. \nAnnotating Specs with Tests: the wpt element","external":false,"refSections":[{"refs":[{"id":"ref-for-wpt-element"},{"id":"ref-for-wpt-element\u2460"},{"id":"ref-for-wpt-element\u2461"}],"title":"4. Metadata"},{"refs":[{"id":"ref-for-wpt-element\u2462"},{"id":"ref-for-wpt-element"},{"id":"ref-for-wpt-element\u2463"},{"id":"ref-for-wpt-element\u2464"},{"id":"ref-for-wpt-element\u2465"},{"id":"ref-for-wpt-element\u2466"},{"id":"ref-for-wpt-element\u2467"},{"id":"ref-for-wpt-element\u2468"},{"id":"ref-for-wpt-element\u2460\u24ea"},{"id":"ref-for-wpt-element\u2460\u2460"},{"id":"ref-for-wpt-element\u2460\u2461"},{"id":"ref-for-wpt-element\u2460\u2462"},{"id":"ref-for-wpt-element\u2460\u2463"},{"id":"ref-for-wpt-element\u2460\u2464"},{"id":"ref-for-wpt-element\u2460\u2465"},{"id":"ref-for-wpt-element\u2460\u2466"},{"id":"ref-for-wpt-element\u2460\u2467"},{"id":"ref-for-wpt-element\u2460\u2468"},{"id":"ref-for-wpt-element\u2461\u24ea"},{"id":"ref-for-wpt-element\u2461\u2460"},{"id":"ref-for-wpt-element\u2461\u2461"}],"title":"11.1. \nAnnotating Specs with Tests: the wpt element"}],"url":"#wpt-element"},
};

document.addEventListener("DOMContentLoaded", ()=>{
Expand Down

0 comments on commit 6cae8cf

Please sign in to comment.