Use 'cite' elements for bibliography entries and links (#2016)

speced · Jul 28, 2021 · e4a654b · e4a654b
1 parent 392e7a1
commit e4a654b
Show file tree

Hide file tree

Showing 404 changed files with 26,402 additions and 26,399 deletions.
diff --git a/bikeshed/biblio.py b/bikeshed/biblio.py
@@ -96,10 +96,11 @@ def toHTML(self):
         ret.append(str)
 
         if self.url:
-            ret.append(E.a({"href": self.url}, self.title))
+            ret.append(E.a({"href": self.url}, E.cite(self.title)))
             ret.append(". ")
         else:
-            ret.append(self.title + ". ")
+            ret.append(E.cite(self.title))
+            ret.append(". ")
 
         str = ""
         if self.preferredURL == "current" and self.current_url:

diff --git a/bikeshed/boilerplate.py b/bikeshed/boilerplate.py
@@ -349,7 +349,7 @@ def addIndexOfLocallyDefinedTerms(doc, container):
         for linkText in linkTexts:
             entry = {
                 "url": "#" + id,
-                "label": "§" + headingLevel,
+                "label": "§\u202f" + headingLevel,
                 "disambiguator": disambiguator,
             }
             indexEntries[linkText].append(entry)

diff --git a/bikeshed/boilerplate/stylesheet.include b/bikeshed/boilerplate/stylesheet.include
@@ -7,7 +7,7 @@
  *   - .toc for the Table of Contents (<ol class="toc">)
  *     + <span class="secno"> for the section numbers
  *   - #toc for the Table of Contents (<nav id="toc">)
- *   - ul.index for Indices (<a href="#ref">term</a><span>, in §N.M</span>)
+ *   - ul.index for Indices (<a href="#ref">term</a><span>, in § N.M</span>)
  *   - table.index for Index Tables (e.g. for properties or elements)
  *
  * Structural Markup

diff --git a/bikeshed/unsortedJunk.py b/bikeshed/unsortedJunk.py
@@ -553,7 +553,8 @@ def fillInterDocumentReferenceFromShepherd(doc, el, spec, section):
     el.tag = "a"
     el.set("href", heading["url"])
     if isEmpty(el):
-        el.text = "{spec} §{number} {text}".format(**heading)
+        appendChild(el, E.cite("{spec}".format(**heading)))
+        appendChild(el, " §\u202f{number} {text}".format(**heading))
     removeAttr(el, "data-link-spec", "spec-section")
 
 
@@ -569,7 +570,7 @@ def fillInterDocumentReferenceFromSpecref(doc, el, spec, section):
     el.tag = "a"
     el.set("href", bib.url + section)
     if isEmpty(el):
-        el.text = bib.title + " §" + section[1:]
+        el.text = bib.title + " §\u202f" + section[1:]
     removeAttr(el, "data-link-spec", "spec-section")
 
 
@@ -939,7 +940,8 @@ def processBiblioLinks(doc):
             if (
                 el.text == f"[{linkText}]"
             ):  # False if it's already been replaced by an author supplied text using the [[FOOBAR inline|custom text]] syntax.
-                replaceContents(el, ref.title)
+                clearContents(el)
+                appendChild(el, E.cite(ref.title))
             if ref.url is not None:
                 el.set("href", ref.url)
 

diff --git a/tests/adjacent-boilerplate/adjacent-boilerplate.html b/tests/adjacent-boilerplate/adjacent-boilerplate.html
@@ -505,9 +505,9 @@ <h2 class="no-num no-ref heading settled" id="references"><span class="content">
   <h3 class="no-num no-ref heading settled" id="normative"><span class="content">Normative References</span></h3>
   <dl>
    <dt id="biblio-example-spec">[EXAMPLE-SPEC]
-   <dd>bar; baz. <a href="https://example.test/foo/">Foo Level 1</a>. REC. URL: <a href="https://example.test/foo/">https://example.test/foo/</a>
+   <dd>bar; baz. <a href="https://example.test/foo/"><cite>Foo Level 1</cite></a>. REC. URL: <a href="https://example.test/foo/">https://example.test/foo/</a>
    <dt id="biblio-fetch">[FETCH]
-   <dd>Anne van Kesteren. <a href="https://fetch.spec.whatwg.org/">Fetch Standard</a>. Living Standard. URL: <a href="https://fetch.spec.whatwg.org/">https://fetch.spec.whatwg.org/</a>
+   <dd>Anne van Kesteren. <a href="https://fetch.spec.whatwg.org/"><cite>Fetch Standard</cite></a>. Living Standard. URL: <a href="https://fetch.spec.whatwg.org/">https://fetch.spec.whatwg.org/</a>
   </dl>
 <script>/* script-dfn-panel */
 

diff --git a/tests/algorithm001.html b/tests/algorithm001.html
@@ -455,9 +455,9 @@ <h2 class="heading settled" data-level="2" id="foo2"><span class="secno">2. </sp
   <h2 class="no-num no-ref heading settled" id="index"><span class="content">Index</span><a class="self-link" href="#index"></a></h2>
   <h3 class="no-num no-ref heading settled" id="index-defined-here"><span class="content">Terms defined by this specification</span><a class="self-link" href="#index-defined-here"></a></h3>
   <ul class="index">
-   <li><a href="#find-even-more-foo">find even more foo</a><span>, in §2</span>
-   <li><a href="#find-more-foo">find more foo</a><span>, in §2</span>
-   <li><a href="#find-some-bar">find some bar</a><span>, in §2</span>
+   <li><a href="#find-even-more-foo">find even more foo</a><span>, in § 2</span>
+   <li><a href="#find-more-foo">find more foo</a><span>, in § 2</span>
+   <li><a href="#find-some-bar">find some bar</a><span>, in § 2</span>
   </ul>
 <script>/* script-var-click-highlighting */
 

diff --git a/tests/biblio001.html b/tests/biblio001.html
@@ -437,16 +437,16 @@ <h2 class="no-num no-ref heading settled" id="references"><span class="content">
   <h3 class="no-num no-ref heading settled" id="normative"><span class="content">Normative References</span></h3>
   <dl>
    <dt id="biblio-normative">[NORMATIVE]
-   <dd>alice; bob. <a href="https://example.test/bar/">Bar Level 1</a>. REC. URL: <a href="https://example.test/bar/">https://example.test/bar/</a>
+   <dd>alice; bob. <a href="https://example.test/bar/"><cite>Bar Level 1</cite></a>. REC. URL: <a href="https://example.test/bar/">https://example.test/bar/</a>
   </dl>
   <h3 class="no-num no-ref heading settled" id="informative"><span class="content">Informative References</span></h3>
   <dl>
    <dt id="biblio-alias-of-something-else">[ALIAS-OF-SOMETHING-ELSE]
    <dd>I'm something else string-based.
    <dt id="biblio-no-author">[NO-AUTHOR]
-   <dd><a href="https://example.test/baz/">Baz Level 1</a>. REC. URL: <a href="https://example.test/baz/">https://example.test/baz/</a>
+   <dd><a href="https://example.test/baz/"><cite>Baz Level 1</cite></a>. REC. URL: <a href="https://example.test/baz/">https://example.test/baz/</a>
    <dt id="biblio-non-normative">[NON-NORMATIVE]
-   <dd>bar; baz. <a href="https://example.test/foo/">Foo Level 1</a>. REC. URL: <a href="https://example.test/foo/">https://example.test/foo/</a>
+   <dd>bar; baz. <a href="https://example.test/foo/"><cite>Foo Level 1</cite></a>. REC. URL: <a href="https://example.test/foo/">https://example.test/foo/</a>
    <dt id="biblio-string-based">[STRING-BASED]
    <dd>I'm made out of unstructured text, oh no!
   </dl>
diff --git a/tests/biblio002.html b/tests/biblio002.html
@@ -421,12 +421,12 @@ <h2 class="no-num no-toc no-ref" id="contents">Table of Contents</h2>
   </nav>
   <main>
    <p><a data-link-type="biblio" href="#biblio-rfc2119">[RFC2119]</a></p>
-   <p><a data-biblio-display="inline" data-link-type="biblio" href="https://datatracker.ietf.org/doc/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a></p>
+   <p><a data-biblio-display="inline" data-link-type="biblio" href="https://datatracker.ietf.org/doc/html/rfc2119"><cite>Key words for use in RFCs to Indicate Requirement Levels</cite></a></p>
    <p><a data-biblio-display="index" data-link-type="biblio" href="#biblio-rfc2119">[RFC2119]</a></p>
   </main>
   <h2 class="no-num no-ref heading settled" id="references"><span class="content">References</span></h2>
   <h3 class="no-num no-ref heading settled" id="informative"><span class="content">Informative References</span></h3>
   <dl>
    <dt id="biblio-rfc2119">[RFC2119]
-   <dd>S. Bradner. <a href="https://datatracker.ietf.org/doc/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a>. March 1997. Best Current Practice. URL: <a href="https://datatracker.ietf.org/doc/html/rfc2119">https://datatracker.ietf.org/doc/html/rfc2119</a>
+   <dd>S. Bradner. <a href="https://datatracker.ietf.org/doc/html/rfc2119"><cite>Key words for use in RFCs to Indicate Requirement Levels</cite></a>. March 1997. Best Current Practice. URL: <a href="https://datatracker.ietf.org/doc/html/rfc2119">https://datatracker.ietf.org/doc/html/rfc2119</a>
   </dl>
diff --git a/tests/biblio003.html b/tests/biblio003.html
@@ -421,12 +421,12 @@ <h2 class="no-num no-toc no-ref" id="contents">Table of Contents</h2>
   </nav>
   <main>
    <p><a data-link-type="biblio" href="#biblio-rfc2119">[RFC2119]</a></p>
-   <p><a data-biblio-display="inline" data-link-type="biblio" href="https://datatracker.ietf.org/doc/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a></p>
+   <p><a data-biblio-display="inline" data-link-type="biblio" href="https://datatracker.ietf.org/doc/html/rfc2119"><cite>Key words for use in RFCs to Indicate Requirement Levels</cite></a></p>
    <p><a data-biblio-display="index" data-link-type="biblio" href="#biblio-rfc2119">[RFC2119]</a></p>
   </main>
   <h2 class="no-num no-ref heading settled" id="references"><span class="content">References</span></h2>
   <h3 class="no-num no-ref heading settled" id="informative"><span class="content">Informative References</span></h3>
   <dl>
    <dt id="biblio-rfc2119">[RFC2119]
-   <dd>S. Bradner. <a href="https://datatracker.ietf.org/doc/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a>. March 1997. Best Current Practice. URL: <a href="https://datatracker.ietf.org/doc/html/rfc2119">https://datatracker.ietf.org/doc/html/rfc2119</a>
+   <dd>S. Bradner. <a href="https://datatracker.ietf.org/doc/html/rfc2119"><cite>Key words for use in RFCs to Indicate Requirement Levels</cite></a>. March 1997. Best Current Practice. URL: <a href="https://datatracker.ietf.org/doc/html/rfc2119">https://datatracker.ietf.org/doc/html/rfc2119</a>
   </dl>
diff --git a/tests/biblio004.html b/tests/biblio004.html
@@ -420,13 +420,13 @@ <h2 class="no-num no-toc no-ref" id="contents">Table of Contents</h2>
    </ol>
   </nav>
   <main>
-   <p><a data-link-type="biblio" href="https://datatracker.ietf.org/doc/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a></p>
-   <p><a data-biblio-display="inline" data-link-type="biblio" href="https://datatracker.ietf.org/doc/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a></p>
+   <p><a data-link-type="biblio" href="https://datatracker.ietf.org/doc/html/rfc2119"><cite>Key words for use in RFCs to Indicate Requirement Levels</cite></a></p>
+   <p><a data-biblio-display="inline" data-link-type="biblio" href="https://datatracker.ietf.org/doc/html/rfc2119"><cite>Key words for use in RFCs to Indicate Requirement Levels</cite></a></p>
    <p><a data-biblio-display="index" data-link-type="biblio" href="#biblio-rfc2119">[RFC2119]</a></p>
   </main>
   <h2 class="no-num no-ref heading settled" id="references"><span class="content">References</span></h2>
   <h3 class="no-num no-ref heading settled" id="informative"><span class="content">Informative References</span></h3>
   <dl>
    <dt id="biblio-rfc2119">[RFC2119]
-   <dd>S. Bradner. <a href="https://datatracker.ietf.org/doc/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a>. March 1997. Best Current Practice. URL: <a href="https://datatracker.ietf.org/doc/html/rfc2119">https://datatracker.ietf.org/doc/html/rfc2119</a>
+   <dd>S. Bradner. <a href="https://datatracker.ietf.org/doc/html/rfc2119"><cite>Key words for use in RFCs to Indicate Requirement Levels</cite></a>. March 1997. Best Current Practice. URL: <a href="https://datatracker.ietf.org/doc/html/rfc2119">https://datatracker.ietf.org/doc/html/rfc2119</a>
   </dl>
diff --git a/tests/biblio005.html b/tests/biblio005.html
@@ -427,5 +427,5 @@ <h2 class="no-num no-ref heading settled" id="references"><span class="content">
   <h3 class="no-num no-ref heading settled" id="informative"><span class="content">Informative References</span></h3>
   <dl>
    <dt id="biblio-dom-level-2-style">[DOM-LEVEL-2-STYLE]
-   <dd>Chris Wilson; Philippe Le Hégaret. <a href="https://www.w3.org/TR/DOM-Level-2-Style/">Document Object Model (DOM) Level 2 Style Specification</a>. 3 November 2020. REC. URL: <a href="https://www.w3.org/TR/DOM-Level-2-Style/">https://www.w3.org/TR/DOM-Level-2-Style/</a>
+   <dd>Chris Wilson; Philippe Le Hégaret. <a href="https://www.w3.org/TR/DOM-Level-2-Style/"><cite>Document Object Model (DOM) Level 2 Style Specification</cite></a>. 3 November 2020. REC. URL: <a href="https://www.w3.org/TR/DOM-Level-2-Style/">https://www.w3.org/TR/DOM-Level-2-Style/</a>
   </dl>
diff --git a/tests/biblio006.html b/tests/biblio006.html
@@ -420,7 +420,7 @@ <h2 class="no-num no-toc no-ref" id="contents">Table of Contents</h2>
    </ol>
   </nav>
   <main>
-   <p><a data-biblio-display="inline" data-link-type="biblio" href="#biblio-jis4051">Formatting rules for Japanese documents (『日本語文書の組版方法』).</a></p>
+   <p><a data-biblio-display="inline" data-link-type="biblio" href="#biblio-jis4051"><cite>Formatting rules for Japanese documents (『日本語文書の組版方法』).</cite></a></p>
    <p><a data-biblio-display="inline" data-link-type="biblio" href="https://datatracker.ietf.org/doc/html/rfc2119">custom text here should work</a></p>
    <p><a data-biblio-display="inline" data-link-type="biblio" href="#biblio-jis4051">not sure why inline is useful on a document without a URL, but hey, the syntax’s there, so it might as well work</a></p>
   </main>
@@ -430,5 +430,5 @@ <h3 class="no-num no-ref heading settled" id="informative"><span class="content"
    <dt id="biblio-jis4051">[JIS4051]
    <dd><cite>Formatting rules for Japanese documents (『日本語文書の組版方法』).</cite> Japanese Standards Association. 2004. JIS X 4051:2004. In Japanese
    <dt id="biblio-rfc2119">[RFC2119]
-   <dd>S. Bradner. <a href="https://datatracker.ietf.org/doc/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a>. March 1997. Best Current Practice. URL: <a href="https://datatracker.ietf.org/doc/html/rfc2119">https://datatracker.ietf.org/doc/html/rfc2119</a>
+   <dd>S. Bradner. <a href="https://datatracker.ietf.org/doc/html/rfc2119"><cite>Key words for use in RFCs to Indicate Requirement Levels</cite></a>. March 1997. Best Current Practice. URL: <a href="https://datatracker.ietf.org/doc/html/rfc2119">https://datatracker.ietf.org/doc/html/rfc2119</a>
   </dl>
diff --git a/tests/caniuse001.html b/tests/caniuse001.html
@@ -483,7 +483,7 @@ <h2 class="no-num no-toc no-ref" id="contents">Table of Contents</h2>
   <h2 class="no-num no-ref heading settled" id="index"><span class="content">Index</span></h2>
   <h3 class="no-num no-ref heading settled" id="index-defined-here"><span class="content">Terms defined by this specification</span></h3>
   <ul class="index">
-   <li><a href="#insertadjacentelement-where-element">insertAdjacentElement(where, element)</a><span>, in §Unnumbered section</span>
+   <li><a href="#insertadjacentelement-where-element">insertAdjacentElement(where, element)</a><span>, in § Unnumbered section</span>
   </ul>
 <script>/* script-caniuse-panel */
 

diff --git a/tests/css-production-range001.html b/tests/css-production-range001.html
@@ -512,7 +512,7 @@ <h2 class="no-num no-ref heading settled" id="references"><span class="content">
   <h3 class="no-num no-ref heading settled" id="normative"><span class="content">Normative References</span></h3>
   <dl>
    <dt id="biblio-css-values-4">[CSS-VALUES-4]
-   <dd>Tab Atkins Jr.; Elika Etemad. <a href="https://www.w3.org/TR/css-values-4/">CSS Values and Units Module Level 4</a>. 11 November 2020. WD. URL: <a href="https://www.w3.org/TR/css-values-4/">https://www.w3.org/TR/css-values-4/</a>
+   <dd>Tab Atkins Jr.; Elika Etemad. <a href="https://www.w3.org/TR/css-values-4/"><cite>CSS Values and Units Module Level 4</cite></a>. 11 November 2020. WD. URL: <a href="https://www.w3.org/TR/css-values-4/">https://www.w3.org/TR/css-values-4/</a>
   </dl>
 <script>/* script-dfn-panel */
 

diff --git a/tests/dict-type.html b/tests/dict-type.html
@@ -619,9 +619,9 @@ <h2 class="heading settled" data-level="1" id="test"><span class="secno">1. </sp
   <h2 class="no-num no-ref heading settled" id="index"><span class="content">Index</span><a class="self-link" href="#index"></a></h2>
   <h3 class="no-num no-ref heading settled" id="index-defined-here"><span class="content">Terms defined by this specification</span><a class="self-link" href="#index-defined-here"></a></h3>
   <ul class="index">
-   <li><a href="#dom-dictwithdefaults-arraywithdefaultempty">arrayWithDefaultEmpty</a><span>, in §1</span>
-   <li><a href="#dom-dictwithdefaults-dictwithdefaultempty">dictWithDefaultEmpty</a><span>, in §1</span>
-   <li><a href="#dictdef-dictwithdefaults">DictWithDefaults</a><span>, in §1</span>
+   <li><a href="#dom-dictwithdefaults-arraywithdefaultempty">arrayWithDefaultEmpty</a><span>, in § 1</span>
+   <li><a href="#dom-dictwithdefaults-dictwithdefaultempty">dictWithDefaultEmpty</a><span>, in § 1</span>
+   <li><a href="#dictdef-dictwithdefaults">DictWithDefaults</a><span>, in § 1</span>
   </ul>
   <aside class="dfn-panel" data-for="term-for-idl-long">
    <a href="https://heycam.github.io/webidl/#idl-long">https://heycam.github.io/webidl/#idl-long</a><b>Referenced in:</b>
@@ -648,7 +648,7 @@ <h2 class="no-num no-ref heading settled" id="references"><span class="content">
   <h3 class="no-num no-ref heading settled" id="normative"><span class="content">Normative References</span><a class="self-link" href="#normative"></a></h3>
   <dl>
    <dt id="biblio-webidl">[WebIDL]
-   <dd>Boris Zbarsky. <a href="https://heycam.github.io/webidl/">Web IDL</a>. 15 December 2016. ED. URL: <a href="https://heycam.github.io/webidl/">https://heycam.github.io/webidl/</a>
+   <dd>Boris Zbarsky. <a href="https://heycam.github.io/webidl/"><cite>Web IDL</cite></a>. 15 December 2016. ED. URL: <a href="https://heycam.github.io/webidl/">https://heycam.github.io/webidl/</a>
   </dl>
   <h2 class="no-num no-ref heading settled" id="idl-index"><span class="content">IDL Index</span><a class="self-link" href="#idl-index"></a></h2>
 <pre class="idl highlight def"><c- b>dictionary</c-> <a href="#dictdef-dictwithdefaults"><code><c- g>DictWithDefaults</c-></code></a> {