Ensure stable IDs for dfn refs in domintro sections

bikeshed/dfnpanels.py

@@ -45,8 +45,7 @@ def addDfnPanels(doc, dfns):
             for i, el in enumerate(els):
                 refID = el.get("id")
                 if refID is None:
-                    refID = f"ref-for-{id}"
-                    el.set("id", safeID(doc, refID))
+                    refID = generateAndSetRefID(id, el, doc)
                 if i == 0:
                     appendChild(
                         li,

bikeshed/h/__init__.py

@@ -25,6 +25,7 @@
     fixTypography,
     fixupIDs,
     foldWhitespace,
+    generateAndSetRefID,
     hasAncestor,
     hasAttr,
     hasAttrs,

bikeshed/h/dom.py

@@ -768,6 +768,15 @@ def safeID(transOrDoc, id):
     return id
 
 
+def generateAndSetRefID(id, el, doc):
+    if hasAncestor(el, lambda x: hasClass(x, "domintro")):
+        refID = f"{id}-dev"
+    else:
+        refID = f"ref-for-{id}"
+    el.set("id", safeID(doc, refID))
+    return refID
+
+
 def addOldIDs(els):
     for el in els:
         if not el.get("oldids"):
@@ -782,6 +791,7 @@ def dedupIDs(doc):
     import itertools as iter
 
     ids = DefaultOrderedDict(list)
+    subdfns = DefaultOrderedDict(list)
     for el in findAll("[id]", doc):
         ids[el.get("id")].append(el)
     for dupeId, els in list(ids.items()):
@@ -794,6 +804,25 @@ def dedupIDs(doc):
             warnAboutDupes = False
         ints = iter.count(1)
         for el in els[1:]:
+            # Ensure a stable ID for any element with a subdfn attribute
+            if "subdfn" in el.attrib:
+                if subdfns[dupeId] is True:
+                    warn(
+                        "Multiple '{0}' elements with subdfn attribute."
+                        + " Ignoring subdfn for all but the first one found.",
+                        dupeId,
+                        el=el,
+                    )
+                else:
+                    subdfns[dupeId] = True
+                    earlierRef = find("#{}".format(dupeId), doc)
+                    # See if earlier element already got the ID this one needs
+                    if earlierRef is not None:
+                        # Change earlier element's ID to one with ⓪ appended
+                        altId = "{}{}".format(dupeId, "⓪")
+                        earlierRef.set("id", altId)
+                        ids[altId].append(earlierRef)
+                    continue
             # If I registered an alternate ID, try to use that.
             if el.get("data-alternate-id"):
                 altId = el.get("data-alternate-id")
@@ -803,7 +832,7 @@ def dedupIDs(doc):
                     continue
             if el.get("data-silently-dedup") is not None:
                 warnAboutDupes = False
-            if dupeId.startswith("ref-for-"):
+            if dupeId.startswith("ref-for-") or dupeId.endswith("-dev"):
                 warnAboutDupes = False
             # Try to de-dup the id by appending an integer after it.
             if warnAboutDupes:

bikeshed/unsortedJunk.py

@@ -25,6 +25,7 @@
     findAll,
     fixupIDs,
     foldWhitespace,
+    generateAndSetRefID,
     hasAncestor,
     hasClass,
     hashContents,
@@ -1078,7 +1079,7 @@ def decorateAutolink(doc, el, linkType, linkText, ref):
     if el.get("id") is None:
         _, _, id = ref.url.partition("#")
         if id:
-            el.set("id", f"ref-for-{id}")
+            generateAndSetRefID(id, el, doc)
             el.set("data-silently-dedup", "")
 
     # Get all the values that the type expands to, add it as a title.

docs/index.bs

@@ -1830,6 +1830,20 @@ This isn't very pretty,
 so if you want to avoid it,
 supply an ID yourself.
 
+[=dfn autolinks=] also receive their own generated IDs.
+In sections that use the `class=domintro` convention to mark themselves as being written for web developers
+(to provide web developers with introductory information about, e.g.,
+how to use each method and property of a particular object),
+descendant [=dfn autolinks=] receive IDs ending with `-dev`, and possibly with a number appended.
+To avoid a particular [=dfn autolinks|dfn autolink=] element ending up with an ID that has a number appended,
+give that [=dfn autolinks|dfn autolink=] element an attribute named `subdfn`.
+
+So if you combine using `class=domintro` to mark up a section as being written for web developers,
+along with adding `subdfn` attributes to mark particular [=dfn autolinks|dfn autolink=] elements within that section,
+you ensure that those elements receive stable IDs ending with `-dev`,
+and with no numbers appended — which makes those elements useful for being referenced (linked to) from other documents,
+or from sites such as MDN.
+
 Bikeshed recognizes a fake element named `<assert>` for marking "assertions" that tests can refer to.
 In the generated output, this is converted to a `<span>` with a unique ID generated from its contents,
 like issues (described above).

docs/index.html

@@ -1487,9 +1487,9 @@
 		}
 	}
 </style>
-  <meta content="Bikeshed version 317afc682, updated Tue Jun 8 09:23:27 2021 +0200" name="generator">
+  <meta content="Bikeshed version 92caf2ca7, updated Thu Jul 1 00:10:15 2021 +0900" name="generator">
   <link href="https://tabatkins.github.io/bikeshed/" rel="canonical">
-  <meta content="317afc6824aaaf379ea2f8bd41bc897203287301" name="document-revision">
+  <meta content="92caf2ca7b51eeb5e68e62f39c8d71e14f4c54d3" name="document-revision">
 <style>/* style-autolinks */
 
 .css.css, .property.property, .descriptor.descriptor {
@@ -2180,7 +2180,7 @@
   <div class="head">
    <p data-fill-with="logo"></p>
    <h1 class="p-name no-ref" id="title">Bikeshed Documentation</h1>
-   <h2 class="no-num no-toc no-ref heading settled" id="profile-and-date"><span class="content">Living Standard, <time class="dt-updated" datetime="2021-06-08">8 June 2021</time></span></h2>
+   <h2 class="no-num no-toc no-ref heading settled" id="profile-and-date"><span class="content">Living Standard, <time class="dt-updated" datetime="2021-07-01">1 July 2021</time></span></h2>
    <div data-fill-with="spec-metadata">
     <dl>
      <dt>This version:
@@ -2195,7 +2195,7 @@ <h2 class="no-num no-toc no-ref heading settled" id="profile-and-date"><span cla
    <div data-fill-with="warning"></div>
    <p class="copyright" data-fill-with="copyright"><a href="http://creativecommons.org/publicdomain/zero/1.0/" rel="license"><img alt="CC0" height="15" src="https://licensebuttons.net/p/zero/1.0/80x15.png" width="80"></a> To the extent possible under law, the editors have waived all copyright
 and related or neighboring rights to this work.
-In addition, as of 8 June 2021,
+In addition, as of 1 July 2021,
 the editors have made this specification available under the <a href="http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0" rel="license">Open Web Foundation Agreement Version 1.0</a>,
 which is available at http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0.
 Parts of this work may be from another specification document.  If so, those parts are instead covered by the license of that specification document. </p>
@@ -4000,6 +4000,18 @@ <h3 class="heading settled" data-level="5.7" id="id-gen"><span class="secno">5.7
 This isn’t very pretty,
 so if you want to avoid it,
 supply an ID yourself.</p>
+   <p><a data-link-type="dfn" href="#dfn-autolink" id="ref-for-dfn-autolink⑤">dfn autolinks</a> also receive their own generated IDs.
+In sections that use the <code>class=domintro</code> convention to mark themselves as being written for web developers
+(to provide web developers with introductory information about, e.g.,
+how to use each method and property of a particular object),
+descendant <a data-link-type="dfn" href="#dfn-autolink" id="ref-for-dfn-autolink⑥">dfn autolinks</a> receive IDs ending with <code>-dev</code>, and possibly with a number appended.
+To avoid a particular <a data-link-type="dfn" href="#dfn-autolink" id="ref-for-dfn-autolink⑦">dfn autolink</a> element ending up with an ID that has a number appended,
+give that <a data-link-type="dfn" href="#dfn-autolink" id="ref-for-dfn-autolink⑧">dfn autolink</a> element an attribute named <code>subdfn</code>.</p>
+   <p>So if you combine using <code>class=domintro</code> to mark up a section as being written for web developers,
+along with adding <code>subdfn</code> attributes to mark particular <a data-link-type="dfn" href="#dfn-autolink" id="ref-for-dfn-autolink⑨">dfn autolink</a> elements within that section,
+you ensure that those elements receive stable IDs ending with <code>-dev</code>,
+and with no numbers appended — which makes those elements useful for being referenced (linked to) from other documents,
+or from sites such as MDN.</p>
    <p>Bikeshed recognizes a fake element named <code>&lt;assert></code> for marking "assertions" that tests can refer to.
 In the generated output, this is converted to a <code>&lt;span></code> with a unique ID generated from its contents,
 like issues (described above).
@@ -4522,7 +4534,7 @@ <h2 class="heading settled" data-level="7" id="autolinking"><span class="secno">
    <p>There are three types of autolink syntaxes you might see/use:</p>
    <ol>
     <li data-md>
-     <p><a data-link-type="dfn" href="#dfn-autolink" id="ref-for-dfn-autolink⑤">Dfn autolinks</a>, like <code>{{foo}}</code> or <code>[=foo=]</code>, which link to a definition.
+     <p><a data-link-type="dfn" href="#dfn-autolink" id="ref-for-dfn-autolink①⓪">Dfn autolinks</a>, like <code>{{foo}}</code> or <code>[=foo=]</code>, which link to a definition.
 See <a href="#autolink-microsyntax">§ 7.1 Dfn Autolinks</a> for details.</p>
     <li data-md>
      <p><a data-link-type="dfn" href="#biblio-autolink" id="ref-for-biblio-autolink">Spec/section autolinks</a>, like <code>[[FOO]]</code> or <code>[[#foo]]</code>, which link to a document or heading.
@@ -4534,7 +4546,7 @@ <h2 class="heading settled" data-level="7" id="autolinking"><span class="secno">
 See <a href="#autolink-manual">§ 7.3 Manual Autolinks</a> for details.</p>
    </ol>
    <p>You may also see an <code><a data-link-type="element" href="#l-element" id="ref-for-l-element④">l</a></code> element,
-which is used to help augment <a data-link-type="dfn" href="#dfn-autolink" id="ref-for-dfn-autolink⑥">dfn autolinks</a>,
+which is used to help augment <a data-link-type="dfn" href="#dfn-autolink" id="ref-for-dfn-autolink①①">dfn autolinks</a>,
 and can avoid the need to use an <code><a data-link-type="element" href="https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-a-element" id="ref-for-the-a-element⑥">a</a></code> in many cases.
 See <a href="#l-element" id="ref-for-l-element⑧">§ 5.4.1 Autolink Shortcuts That Work Anywhere: the l element</a> for details.</p>
    <h3 class="heading settled" data-level="7.1" id="autolink-microsyntax"><span class="secno">7.1. </span><span class="content">Dfn Autolinks</span><a class="self-link" href="#autolink-microsyntax"></a></h3>
@@ -4666,7 +4678,7 @@ <h3 class="heading settled" data-level="7.2" id="autolink-biblio"><span class="s
 and mixes the previous two syntaxes.</p>
    </ol>
    <p>See <a href="#section-links">§ 7.9 Section Links</a> for details on the latter two.</p>
-   <p>Like <a data-link-type="dfn" href="#dfn-autolink" id="ref-for-dfn-autolink⑦">dfn autolinks</a>, if you want to display a specific visual text
+   <p>Like <a data-link-type="dfn" href="#dfn-autolink" id="ref-for-dfn-autolink①②">dfn autolinks</a>, if you want to display a specific visual text
 rather than what the autolink would normally display,
 you can append <code>|visible text</code> to the internals,
 like <code>[[CSS-FOO|the CSS Foo spec]]</code>.</p>
@@ -4763,7 +4775,7 @@ <h3 class="heading settled" data-level="7.4" id="link-types"><span class="secno"
 Just add a <code>spec</code> attribute with the spec’s shortname to either the link or a container.
 This can also be specified document-wide,
 as described in <a href="#link-defaults">§ 7.7 Configuring Linking Defaults</a>.
-(You can add this to a <a data-link-type="dfn" href="#dfn-autolink" id="ref-for-dfn-autolink⑧">dfn autolink</a> by wrapping it in an <code><a data-link-type="element" href="#l-element" id="ref-for-l-element⑥">l</a></code> element,
+(You can add this to a <a data-link-type="dfn" href="#dfn-autolink" id="ref-for-dfn-autolink①③">dfn autolink</a> by wrapping it in an <code><a data-link-type="element" href="#l-element" id="ref-for-l-element⑥">l</a></code> element,
 or by fully converting to an <code><a data-link-type="element" href="https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-a-element" id="ref-for-the-a-element⑨">a</a></code> element,
 and adding a <code>spec</code> attribute.)</p>
    </ol>
@@ -7154,9 +7166,10 @@ <h2 class="no-num no-ref heading settled" id="issues-index"><span class="content
    <b><a href="#dfn-autolink">#dfn-autolink</a></b><b>Referenced in:</b>
    <ul>
     <li><a href="#ref-for-dfn-autolink">4. Metadata</a> <a href="#ref-for-dfn-autolink①">(2)</a> <a href="#ref-for-dfn-autolink②">(3)</a> <a href="#ref-for-dfn-autolink③">(4)</a> <a href="#ref-for-dfn-autolink④">(5)</a>
-    <li><a href="#ref-for-dfn-autolink⑤">7. Autolinking</a> <a href="#ref-for-dfn-autolink⑥">(2)</a>
-    <li><a href="#ref-for-dfn-autolink⑦">7.2. Spec/Section Autolinks</a>
-    <li><a href="#ref-for-dfn-autolink⑧">7.4. Link Types</a>
+    <li><a href="#ref-for-dfn-autolink⑤">5.7. Automatic ID Generation</a> <a href="#ref-for-dfn-autolink⑥">(2)</a> <a href="#ref-for-dfn-autolink⑦">(3)</a> <a href="#ref-for-dfn-autolink⑧">(4)</a> <a href="#ref-for-dfn-autolink⑨">(5)</a>
+    <li><a href="#ref-for-dfn-autolink①⓪">7. Autolinking</a> <a href="#ref-for-dfn-autolink①①">(2)</a>
+    <li><a href="#ref-for-dfn-autolink①②">7.2. Spec/Section Autolinks</a>
+    <li><a href="#ref-for-dfn-autolink①③">7.4. Link Types</a>
    </ul>
   </aside>
   <aside class="dfn-panel" data-for="biblio-autolink">