Add support for non-prose elements (#82)

Author: palemieux

css/smpte.css

@@ -247,6 +247,12 @@ figure {
   margin-top: 1rem;
 }
 
+/* elements */
+
+#sec-elements ol {
+  list-style-type: none;
+}
+
 /* links */
 
 .ext-ref {

doc/elements/sample.txt

@@ -0,0 +1 @@
+This is a sample element.

doc/main.html

@@ -99,6 +99,8 @@ <h2>Directory layout</h2>
     <ul>
       <li><code>doc/main.html</code>: main element of the document (see <a href="#sec-main-element"></a>).</li>
       <li><code>doc/media/</code>: directory containing media referenced by the main element (see <a href="#sec-figure-element"></a>).</li>
+      <li><code>doc/elements/</code>: directory containing non-prose elements of the document (see <a
+      href="#sec-elements-section"></a>).</li>
       <li><code>doc/snippets/</code>: directory containing snippets embedded in the main element (see <a href="#sec-snippets-element"></a>).</li>
       <li><code>tooling/</code>: directory consisting of the tools necessary to render SMPTE documents (see <a href="#sec-tooling"></a>).</li>
       <li><code>.smpte-build.json</code>: JSON file used to configure the HTML rendering process (see <a href="#sec-building"></a>).</li>
@@ -278,6 +280,10 @@ <h4>Overall structure</h4>
               <td><a>Annex section</a></td>
               <td>0 or more</td>
             </tr>
+            <tr>
+              <td><a>Additional elements section</a></td>
+              <td>0 or 1</td>
+            </tr>
             <tr>
               <td><a>Bibliography</a></td>
               <td>0 or 1</td>
@@ -531,6 +537,42 @@ <h4>Annex section(s)</h4>
 
       </section>
 
+      <section id="sec-elements-section">
+        <h4>Additional elements section</h4>
+
+        <p>The <dfn>additional elements section</dfn> collects the non-prose elements of the document.</p>
+
+        <p>The <code>id</code> attribute shall be present on the <code>section</code> element and equal to
+        <code>sec-elements</code>.</p>
+
+        <p>The heading of the section shall not be present.</p>
+
+        <p>If present, the section shall:</p>
+        <ul>
+          <li>come immediately before the <a>Bibliography</a> section; and</li>
+          <li>contain a single ordered list <code>ol</code> where each element <code>li</code> contains exactly one <code>a</code>
+          that links to an element of the document.</li>
+        </ul>
+
+        <p>Each <code>a</code> element shall have:</p>
+        <ul>
+          <li>an <code>id</code> attribute whose value is prefixed with <code>element-</code>;</li>
+          <li>a <code>title</code> attribute that provides a short description of the element;</li>
+          <li>a <code>href</code> attribute that links to the element itself, typically in the <code>doc/elements</code>
+          directory.</li>
+        </ul>
+
+        <div class="example">
+<pre>&lt;section id=&quot;sec-elements&quot;&gt;
+  &lt;ol&gt;
+    &lt;li&gt;
+      &lt;a id=&quot;element-a&quot; title=&quot;Description of the elemnent&quot; href=&quot;./elements/form.docx&quot;&gt;&lt;/a&gt;
+    &lt;/li&gt;
+  &lt;/ol&gt;
+&lt;/section&gt;</pre>
+        </div>
+      </section>
+
       <section id="sec-bibliography-section">
         <h4>Bibliography section</h4>
 
@@ -593,6 +635,17 @@ <h4>Citing normative references</h4>
 
       </section>
 
+      <section id="sec-elements-linking">
+        <h4>Citing non-prose elements</h4>
+
+        <p>When citing an non-prose element of the document, an <code>a</code> element with its <code>href</code> attribute
+        referencing a <code>a</code> element from the <a>additional elements section</a> shall be used.</p>
+
+        <div class="example">
+<code>&lt;a href=&quot;#element-a&quot;&gt;&lt;/a&gt;</code> is rendered as <a href="#element-a"></a>.
+        </div>
+
+      </section>
 
       <section id="sec-bibliographic-linking">
         <h4>Citing bibliographic references</h4>
@@ -1031,6 +1084,12 @@ <h3>Amazon AWS integration</h3>
     </section>
   </section>
 
+  <section id="sec-elements">
+    <ol>
+      <li><a id="element-a" title="Sample text element" href="./elements/sample.txt"></a></li>
+    </ol>
+  </section>
+
   <section id="sec-bibliography">
     <ul>
       <li><cite id="bib-iso-directives-part2">ISO/IEC Directives, Part 2</cite>, Principles and rules for the structure and drafting

js/validate.mjs

@@ -265,7 +265,7 @@ function _validateClause(e, lvl, logger) {
 }
 
 function validateClause(e, logger) {
-  if (e.classList.contains("annex") || e.id === "sec-bibliography")
+  if (e.classList.contains("annex") || e.id === "sec-bibliography" || e.id === "sec-elements")
     return false;
 
   _validateClause(e, 2, logger);
@@ -282,6 +282,27 @@ function validateAnnex(e, logger) {
   return true;
 }
 
+function validateElementsAnnex(e, logger) {
+  if (e.id !== "sec-elements")
+    return false;
+
+  if (e.firstElementChild.tagName === "OL" && e.childElementCount === 1) {
+    for (const li of e.firstElementChild.children) {
+      if (li.tagName === "LI") {
+        if (li.firstElementChild.tagName !== "A" || !li.firstElementChild.id || li.childElementCount !== 1 || !li.firstElementChild.title || !li.firstElementChild.href) {
+          logger.error(`Each <li> element of the Elements Annex must contain a single <a> element with a title, id and href attributes.`);
+        }
+      } else {
+        logger.error(`The <ol> element of the Elements Annex must contain only <li> elements`);
+      }
+    }
+  } else {
+    logger.error(`The Elements Annex section must contain a single <ol> element.`);
+  }
+
+  return true;
+}
+
 function validateBibliography(e, logger) {
   if (e.id !== "sec-bibliography")
     return false;
@@ -302,6 +323,7 @@ function validateBody(body, logger) {
     [validateDefs, 0, 1],
     [validateClause, 0, Infinity],
     [validateAnnex, 0, Infinity],
+    [validateElementsAnnex, 0, 1],
     [validateBibliography, 0, 1],
   ];
 
@@ -319,18 +341,24 @@ function validateBody(body, logger) {
     while (index < sectionDefs.length) {
       sectionDef = sectionDefs.at(index);
 
-      if ((sectionDef.at(0))(child, logger))
+      if ((sectionDef.at(0))(child, logger)) {
+        matchCount++;
         break;
+      }
+
+      index++;
 
       if (matchCount < sectionDef.at(1))
         logger.error(`Too few instances of ${sectionDef.at(0).name}`);
 
-      matchCount = 0
+      matchCount = 0;
 
-      index++;
     }
 
-    matchCount++;
+    if (index >= sectionDefs.length) {
+      logger.error(`Expected ${sectionDef.at(0).name} but found ${child.tagName} with id ${child.id}`);
+      break
+    }
 
     if (matchCount > sectionDef.at(2))
       logger.error(`Too few instances of ${sectionDef.at(0).name}`);

smpte.js

@@ -422,6 +422,55 @@ function insertBibliography(docMetadata) {
   h2.innerText = "Bibliography";
 }
 
+const SMPTE_ELEMENTS_ID = "sec-elements";
+
+function insertElementsAnnex(docMetadata) {
+  const sec = document.getElementById(SMPTE_ELEMENTS_ID);
+
+  if (sec === null)
+    return;
+
+  if (sec.children.length !== 1 || sec.firstElementChild.tagName !== "OL") {
+    logEvent(`Elements section must contain a single <ol> element.`);
+    return;
+  }
+
+  sec.classList.add("annex");
+
+  const intro = document.createElement("p");
+  intro.innerText = "This annex lists non-prose elements of this document."
+  sec.insertBefore(intro, sec.firstChild);
+
+  const h2 = document.createElement("h2");
+  h2.innerText = "Additional elements";
+  sec.insertBefore(h2, sec.firstChild);
+
+  let counter = "a".charCodeAt();
+
+  for(const e of sec.querySelectorAll("li > a")) {
+
+    const headingNum = document.createElement("span");
+    headingNum.className = "heading-number";
+    headingNum.innerText = String.fromCharCode(counter++);
+
+    const headingLabel = document.createElement("span");
+    headingLabel.className = "heading-label";
+    headingLabel.appendChild(headingNum);
+    headingLabel.appendChild(document.createTextNode("."));
+
+    e.parentElement.insertBefore(headingLabel, e);
+
+    e.innerText = "(link)";
+
+    if (e.title) {
+      e.parentElement.insertBefore(document.createTextNode(" " + e.title + " "), e);
+    } else {
+      logEvent("All links listed in the Elements Annex must have a title attribute.")
+    }
+
+  }
+}
+
 const SMPTE_CONFORMANCE_ID = "sec-conformance";
 
 function insertConformance(docMetadata) {
@@ -727,6 +776,47 @@ function numberNotes() {
   }
 }
 
+function numberElements() {
+  let counter = 1;
+
+  for (let e of document.querySelectorAll("#sec-elements li")) {
+
+    let numPrefix = "";
+
+    if (section.classList.contains("annex")) {
+      counter = 1;
+      numPrefix = section.querySelector(".heading-number").innerText + ".";
+    }
+
+    for (let figure of section.querySelectorAll("figure")) {
+
+      const figcaption = figure.querySelector("figcaption");
+  
+      if (figcaption === null) {
+        logEvent(`Figure is missing a caption`);
+        continue;
+      }
+
+      const headingLabel = document.createElement("span");
+      headingLabel.className = "heading-label";
+  
+      const headingNumberElement = document.createElement("span");
+      headingNumberElement.className = "heading-number";
+      headingNumberElement.innerText = numPrefix + counter;
+      
+      headingLabel.appendChild(document.createTextNode("Figure "));
+      headingLabel.appendChild(headingNumberElement);
+      headingLabel.appendChild(document.createTextNode(" –⁠ "));
+
+
+      figcaption.insertBefore(headingLabel, figcaption.firstChild);
+      
+      counter++;
+    }
+
+  }
+}
+
 function numberExamples() {
 
   for (let section of document.querySelectorAll("section")) {
@@ -888,6 +978,11 @@ function resolveLinks(docMetadata) {
           anchor.innerText = targetNumber;
         }
 
+      } else if (target.parentElement.parentElement.parentElement.id === "sec-elements") {
+        /* element */
+
+        anchor.innerText = "Element " + target.parentElement.querySelector(".heading-number").innerText;
+
       } else {
         logEvent(`Anchor points to ambiguous #${target_id}`)
         anchor.innerText = "????";
@@ -929,6 +1024,7 @@ function render() {
   insertNormativeReferences(docMetadata);
   insertTermsAndDefinitions(docMetadata);
 
+  insertElementsAnnex(docMetadata);
   insertBibliography(docMetadata);
   numberSections(document.body, "");
   numberTables();

test/resources/html/validation/elements-invalid.html

@@ -0,0 +1,39 @@
+<!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 src="../../../../smpte.js"></script>
+    <meta itemprop="test" content="invalid" />
+    <meta itemprop="pubType" content="AG" />
+    <meta itemprop="pubNumber" content="99" />
+    <meta itemprop="pubState" content="draft" />
+    <meta itemprop="pubDateTime" content="20XX-XX-XX" />
+    <title>Title of the document</title>
+  </head>
+  <body>
+    <section id="sec-scope">
+      <p>This is the scope of the document.</p>
+    </section>
+    <section>
+      <h2>Hello</h2>
+
+      <p>Reference to <a href="#element-a"></a></p>
+    </section>
+    <section id="sec-elements">
+      <ol>
+        <li><a id="element-a" title="I am an element" href="https://smpte.org"></a></li>
+      </ol>
+    </section>
+    <section class="annex" id="sec-last-annex">
+      <h2>Last Annex</h2>
+    </section>
+    <section id="sec-bibliography">
+      <ul>
+        <li><cite id="bib-draft-bhutton-json-schema-00">IETF draft-bhutton-json-schema-00</cite>, Wright, A., H. Andrews; B. Hutton, G. Dennis, "JSON Schema: A Media Type for Describing JSON Documents", Work in Progress, December 8, 2020.
+        <a>https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00</a></li>
+      </ul>
+    </section>
+  </body>
+</html>

test/resources/html/validation/elements-valid.html

@@ -0,0 +1,30 @@
+<!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 src="../../../../smpte.js"></script>
+    <meta itemprop="test" content="valid" />
+    <meta itemprop="pubType" content="AG" />
+    <meta itemprop="pubNumber" content="99" />
+    <meta itemprop="pubState" content="draft" />
+    <meta itemprop="pubDateTime" content="20XX-XX-XX" />
+    <title>Title of the document</title>
+  </head>
+  <body>
+    <section id="sec-scope">
+      <p>This is the scope of the document.</p>
+    </section>
+    <section>
+      <h2>Hello</h2>
+
+      <p>Reference to <a href="#element-a"></a></p>
+    </section>
+    <section id="sec-elements">
+      <ol>
+        <li><a id="element-a" title="I am an element" href="https://smpte.org"></a></li>
+      </ol>
+    </section>
+  </body>
+</html>