Specify DOI for SMPTE refs (#314)

* Specify AG-29 for SMPTE refs

* split into two statements

* add should to ISO statement

* update undated ref text

Co-authored-by: Pierre-Anthony Lemieux <[email protected]>

* update wording to AG-29

Co-authored-by: Pierre-Anthony Lemieux <[email protected]>

* change to DOI for referencing

* add SMPTE DOI examples

* fix ref link

* remove ag 29 bib

* update verbiage

Co-authored-by: Pierre-Anthony Lemieux <[email protected]>

* swp to DOI for refs

* unit test added

---------

Co-authored-by: Pierre-Anthony Lemieux <[email protected]>

Author: SteveLLamb

doc/main.html

@@ -564,17 +564,34 @@ <h4>Normative references section</h4>
           <li>The <code>cite</code> element shall contain an <code>id</code> attribute with value prefixed by
           <code>bib-</code>.</li>
           <li>Each <code>li</code> element may contain additional title information.
+          
           <li>Each <code>li</code> element may contain one <code>a</code> element that contains a location where the reference can
           be retrieved.</li>
+          <li>Each <code>li</code> element may contain one <code>span</code> element with a <code>class="doi"</code> attribute that contains the DOI of the document. Using this will also create a DOI resolver URL.</li>
         </ul>
-
+          <p>Undated references should be used, since they point to the most most up-to-date edition of a document.</p>
+          
+          <p>Dated references shall be used when referencing a specific element of the document, e.g., a table. They should also be used when past and future editions of the document are likely to be inadequate. </p>
+            
+          <p class="note">The DOI <code>span</code> element should be used, and not the <code>a</code> element, for both the most recent and specific editions of a SMPTE document. SMPTE HO can provide guidance for specific DOIs available.</p>
+       
         <div class="example">
 <pre>&lt;section id=&quot;sec-normative-references&quot;&gt;
   &lt;ul&gt;
     &lt;li&gt;
       &lt;cite id=&quot;bib-HTML-5&quot;&gt;HTML Standard&lt;/cite&gt;, Living Standard. 
         &lt;a&gt;https://html.spec.whatwg.org/multipage/&lt;/a&gt;&lt;/li&gt;
     &lt;/li&gt;
+    &lt;li&gt;
+      &lt;cite id=&quot;bib-SMPTE-st429-18&quot;&gt;SMPTE ST 429-18&lt;/cite&gt;, D-Cinema Packaging — Immersive Audio Track 
+      File 
+        &lt;span class=&quot;doi&quot;&gt;10.5594/SMPTE.ST429-18/&lt;/span&gt;&lt;/li&gt;
+    &lt;/li&gt;
+    &lt;li&gt;
+      &lt;cite id=&quot;bib-SMPTE-st429-18-2023&quot;&gt;SMPTE ST 429-18:2023&lt;/cite&gt;, D-Cinema Packaging — Immersive 
+      Audio Track File (2023 Edition)
+        &lt;span class=&quot;doi&quot;&gt;10.5594/SMPTE.ST429-18.2023/&lt;/span&gt;&lt;/li&gt;
+    &lt;/li&gt;
   &lt;/ul&gt;
 &lt;/section&gt;</pre>
 </div>
@@ -2383,6 +2400,7 @@ <h3>Sample Workflow </h3>
       <a>https://doc.smpte-doc.org/ag-16/main/</a></li>
       <li><cite id="bib-smpte-gh-om">SMPTE GitHub Operating Manual</cite>
         <a>https://github.com/SMPTE/github-operating-manual</a></li>
+        
     </ul>
   </section>
 

js/validate.mjs

@@ -543,6 +543,7 @@ class ReferenceMatcher {
 
     let aCount = 0;
     let citeCount = 0;
+    let doiCount = 0;
 
     for (const child of element.children) {
       if (child.localName === "a") {
@@ -551,6 +552,8 @@ class ReferenceMatcher {
         if (child.id === null)
           logger.error(`All cite element must have an id attribute`, child);
         citeCount++;
+      } else if (child.matches("span.doi")) {
+        doiCount++;
       }
     }
 
@@ -560,6 +563,9 @@ class ReferenceMatcher {
     if (citeCount !== 1)
       logger.error(`Reference element must contain exactly one cite element`, element);
 
+    if (doiCount > 1)
+      logger.error(`Reference element must contain at most one DOI`, element);
+
     return true;
   }
 }

smpte.js

@@ -453,6 +453,21 @@ function insertNormativeReferences(docMetadata) {
 
   h2.innerText = "Normative references";
 
+  /* style DOIs */
+
+  for (const doi of sec.querySelectorAll("ul span.doi")) {
+    doi.parentNode.insertBefore(document.createElement("br"), doi);
+    doi.parentNode.insertBefore(document.createTextNode("doi:\u00a0"), doi);
+
+    const prefix = "https://doi.org/";
+    const url = prefix + doi.textContent.trim();
+
+    const label = document.createTextNode("url:\u00a0");
+    const link = document.createElement("a");
+    link.textContent = url;
+    doi.parentNode.insertBefore(link, label.nextSibling);
+  }
+
   /* style URLs */
 
   for(const u of sec.querySelectorAll("ul a")) {
@@ -542,6 +557,21 @@ function insertBibliography(docMetadata) {
 
   h2.innerText = "Bibliography";
 
+  /* style DOIs */
+
+  for (const doi of sec.querySelectorAll("ul span.doi")) {
+    doi.parentNode.insertBefore(document.createElement("br"), doi);
+    doi.parentNode.insertBefore(document.createTextNode("doi:\u00a0"), doi);
+
+    const prefix = "https://doi.org/";
+    const url = prefix + doi.textContent.trim();
+
+    const label = document.createTextNode("url:\u00a0");
+    const link = document.createElement("a");
+    link.textContent = url;
+    doi.parentNode.insertBefore(link, label.nextSibling);
+  }
+
   /* style links */
 
   for(const u of sec.querySelectorAll("ul a")) {

test/resources/html/validation/norm-ref-valid.html

@@ -0,0 +1,36 @@
+<!doctype html>
+<html>
+  <head itemscope="itemscope" itemtype="http://smpte.org/standards/documents">
+    <meta charset="utf-8" />
+    <meta http-equiv="x-ua-compatible" content="ie=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <script type="module" src="../../../../smpte.js"></script>
+    <meta itemprop="test" content="valid" />
+    <meta itemprop="pubType" content="AG" />
+    <meta itemprop="pubNumber" content="99" />
+    <meta itemprop="pubState" content="draft" />
+    <title>Title of the document</title>
+  </head>
+  <body>
+    <section id="sec-scope">
+      <p>This is the scope of the document.</p>
+    </section>
+    <section id="sec-normative-references">
+      <ul>
+        <li>
+      <cite id="bib-HTML-5">HTML Standard</cite>, Living Standard. 
+        <a>https://html.spec.whatwg.org/multipage/</a></li>
+    </li>
+    <li>
+      <cite id="bib-SMPTE-st429-18">SMPTE ST 429-18</cite>, D-Cinema Packaging — Immersive Audio Track 
+      File 
+        <span class="doi">10.5594/SMPTE.ST429-18/</span></li>
+    </li>
+    <li>
+      <cite id="bib-SMPTE-st429-18-2023">SMPTE ST 429-18:2023</cite>, D-Cinema Packaging — Immersive 
+      Audio Track File (2023 Edition)
+        <span class="doi">10.5594/SMPTE.ST429-18.2023/</span></li>
+      </ul>
+    </section>
+  </body>
+</html>