diff --git a/skills/bikeshed-conversion/ID_PATTERNS.md b/skills/bikeshed-conversion/ID_PATTERNS.md new file mode 100644 index 0000000..c5e7b1d --- /dev/null +++ b/skills/bikeshed-conversion/ID_PATTERNS.md @@ -0,0 +1,12 @@ +# Common ID Patterns to Preserve + +Based on [w3c/hr-time#173](https://github.com/w3c/hr-time/pull/173), these are typical ID patterns that get lost during Bikeshed conversion: + +| Type | Pattern | Example | +|------|---------|---------| +| Concept definitions | `dfn-{name}` | `id=dfn-wall-clock`, `id=dfn-monotonic-clock`, `id=dfn-duration` | +| Algorithm definitions | `dfn-{algorithm-name}` | `id=dfn-coarsen-time`, `id=dfn-duration-from` | +| IDL typedefs | `dom-{typename}` | `id=dom-domhighrestimestamp`, `id=dom-epochtimestamp` | +| IDL interfaces | `dom-{interface}` | `id=dom-performance` | +| IDL blocks | `idl-def-{name}` | `id=idl-def-domhighrestimestamp` | +| Compound concepts | `dfn-{hyphenated}` | `id=dfn-current-high-resolution-time`, `id=dfn-relative-high-resolution-coarse-time` | diff --git a/skills/bikeshed-conversion/SKILL.md b/skills/bikeshed-conversion/SKILL.md index fe16837..c907915 100644 --- a/skills/bikeshed-conversion/SKILL.md +++ b/skills/bikeshed-conversion/SKILL.md @@ -1,69 +1,46 @@ --- name: bikeshed-conversion -description: Guidelines for converting W3C specs to Bikeshed format. Covers anchor ID preservation, dfn handling, and common pitfalls. Read this before any Bikeshed conversion or migration work. +description: "Convert W3C ReSpec documents to Bikeshed (.bs) format — preserves anchor IDs, handles dfn elements and IDL attributes, resolves cross-spec references, and avoids common formatting pitfalls. Use when doing any respec-to-bikeshed migration, spec format conversion, or .bs markup work." --- # Bikeshed Conversion ## Preserving Anchor IDs -When converting a spec to Bikeshed, **anchor IDs used by other specifications must be preserved**. Bikeshed auto-generates IDs for `` elements based on their text content, but these auto-generated IDs often differ from the IDs that were in the original spec. Other specs link to these IDs, so changing them silently breaks cross-spec references. +**Always preserve anchor IDs from the original spec.** Bikeshed auto-generates IDs for `` elements that often differ from the originals, breaking cross-spec references. -### The Problem - -Bikeshed generates IDs like `dfn-wall-clock` from `wall clock`, but the original spec may have used a different ID or no explicit ID (relying on the HTML spec's own ID generation). When other W3C specs reference anchors like `#dfn-wall-clock`, `#dom-performance`, or `#dfn-coarsen-time`, those links break if the IDs change. - -### The Fix - -Always add explicit `id` attributes to `` elements to preserve the anchors other specs depend on: +Add explicit `id` attributes to every ``: ```html - + wall clock - + wall clock ``` -### Common ID Patterns to Preserve - -Based on [w3c/hr-time#173](https://github.com/w3c/hr-time/pull/173), these are typical ID patterns that get lost: +See [ID_PATTERNS.md](ID_PATTERNS.md) for the full table of ID naming conventions (`dfn-*`, `dom-*`, `idl-def-*`) based on [w3c/hr-time#173](https://github.com/w3c/hr-time/pull/173). -| Type | Pattern | Example | -|------|---------|---------| -| Concept definitions | `dfn-{name}` | `id=dfn-wall-clock`, `id=dfn-monotonic-clock`, `id=dfn-duration` | -| Algorithm definitions | `dfn-{algorithm-name}` | `id=dfn-coarsen-time`, `id=dfn-duration-from` | -| IDL typedefs | `dom-{typename}` | `id=dom-domhighrestimestamp`, `id=dom-epochtimestamp` | -| IDL interfaces | `dom-{interface}` | `id=dom-performance` | -| IDL blocks | `idl-def-{name}` | `id=idl-def-domhighrestimestamp` | -| Compound concepts | `dfn-{hyphenated}` | `id=dfn-current-high-resolution-time`, `id=dfn-relative-high-resolution-coarse-time` | +## IDL Attribute Definitions -### IDL Attribute Definitions - -When converting `` elements inside a `
` that describes IDL interface attributes, add the `attribute` keyword to each `` so Bikeshed knows they define IDL attributes (not plain terms). The parent `
` should have `dfn-for` set to the interface name. +Add the `attribute` keyword to `` elements inside IDL `
` blocks so Bikeshed treats them as IDL attributes, not plain terms: ```html - +
duration
-
...
- +
duration
-
...
``` -Without the `attribute` keyword, Bikeshed won't correctly associate the dfn with the IDL attribute, and cross-references like `{{PerformanceEntry/duration}}` may fail to resolve. - -### Checklist - -When converting a spec to Bikeshed: +## Conversion Checklist 1. **Inventory all `` elements** in the original spec and note their IDs 2. **Check for cross-spec references** — search other W3C specs that link to this spec's anchors (use [xref](https://respec.org/xref/) or grep the spec's URL in other repos) -3. **Add explicit `id` attributes** to every `` that had an ID in the original, matching the original ID exactly -4. **Verify after conversion** — build the Bikeshed output and confirm all anchors from the original spec still resolve -5. **Check `data-dfn-for` scoping** — Bikeshed uses `data-dfn-for` to scope definitions; make sure scoped dfns also retain their original IDs (e.g., `id="wall-clock-unsafe-current-time"` for `unsafe current time`) +3. **Add explicit `id` attributes** to every ``, matching the original ID exactly +4. **Verify after conversion** — build with `bikeshed --die-on=warning` and confirm all anchors resolve. If anchors are missing, check for `Missing dfn` errors and compare generated IDs against originals +5. **Check `data-dfn-for` scoping** — ensure scoped dfns retain their original IDs