Update terms for Examples

css/smpte.css

@@ -209,7 +209,7 @@ blockquote {
 
 /* note and example */
 
-.note, .example {
+.note, .example, .deprecated {
   font-size: 0.9rem;
   margin-left: 1rem;
 }

doc/main.html

@@ -662,13 +662,20 @@ <h4>Terms and definitions section</h4>
               <li>Each <code>dt</code> element contains a single term, abbreviation or symbol. Zero or more additional <code>dt</code> elements
               can follow the first <code>dt</code> element, in which case all the terms, abbreviations and symbols in the immediately
               preceding <code>dt</code> elements are synonyms.</li>
-              <li>The first <code>dd</code> element immediately following the last <code>dt</code> element, if present, shall be
-              a definition.</li>
-              <li>The next <code>dd</code> element, if present, shall contain a single reference to a bibliographic entry,
-              in which case the entry is the source of the definition of the term.</li>
-              <li>The remaining <code>dd</code> elements, if present,
-              shall have a <code>class</code> attribute that contains the value <code>note</code>, in which case the
-              elements are notes to the entry.</li>
+              <li>The <code>dd</code> elements following the <code>dt</code> element(s) shall appear in the following
+              order — each group is optional, but if present, it shall appear in this sequence:
+                <ol>
+                  <li><strong>Definition:</strong> the first <code>dd</code> element shall be the definition of the term. This element is required.</li>
+                  <li><strong>Deprecated:</strong> the next <code>dd</code> element, if present, shall have a <code>class</code>
+                  attribute containing <code>deprecated</code>, indicating the term is deprecated. At most one such element is permitted.</li>
+                  <li><strong>Examples:</strong> the next <code>dd</code> element(s), if present, shall each have a <code>class</code>
+                  attribute containing <code>example</code>.</li>
+                  <li><strong>Notes:</strong> the next <code>dd</code> element(s), if present, shall each have a <code>class</code>
+                  attribute containing <code>note</code>.</li>
+                  <li><strong>Source:</strong> the last <code>dd</code> element, if present, shall contain a single reference to a
+                  bibliographic entry and serves as the source of the definition.</li>
+                </ol>
+              </li>
             </ul>
           </li>
         </ul>
@@ -683,8 +690,10 @@ <h4>Terms and definitions section</h4>
     &lt;dt&gt;&lt;dfn&gt;key number&lt;/dfn&gt;&lt;/dt&gt;
     &lt;dd&gt;number that is printed with ink or exposed onto the film at the time of
     manufacture at regular intervals, typically one foot.&lt;/dd&gt;
-    &lt;dd&gt;&lt;a href=&quot;#bib-key-number-spec&quot;&gt;&lt;/a&gt;&lt;/dd&gt;
+    &lt;dd class="deprecated"&gt;deprecated term&lt;/dd&gt;
+    &lt;dd class="example"&gt;An example of a key number is 12345.&lt;/dd&gt;
     &lt;dd class="note"&gt;Key number shall not be confused with key frame.&lt;/dd&gt;
+    &lt;dd&gt;&lt;a href=&quot;#bib-key-number-spec&quot;&gt;&lt;/a&gt;&lt;/dd&gt;
   &lt;/dl&gt;
 &lt;/section&gt;
 </pre>

js/validate.mjs

@@ -269,6 +269,36 @@ class DefinitionSourceMatcher {
   }
 }
 
+class DefinitionExampleMatcher {
+  static match(element, logger) {
+    if (element.localName !== "dd" || !element.classList.contains("example"))
+      return false;
+
+    for (const child of element.children) {
+      if (!AnyPhrasingMatcher.match(child, logger)) {
+        logger.error(`Note to entry contains non-phrasing element`, child);
+      }
+    }
+
+    return true;
+  }
+}
+
+class DefinitionDeprecatedMatcher {
+  static match(element, logger) {
+    if (element.localName !== "dd" || !element.classList.contains("deprecated"))
+      return false;
+
+    for (const child of element.children) {
+      if (!AnyPhrasingMatcher.match(child, logger)) {
+        logger.error(`Deprecated entry contains non-phrasing element`, child);
+      }
+    }
+
+    return true;
+  }
+}
+
 class DefinitionNoteMatcher {
   static match(element, logger) {
     if (element.localName !== "dd" || !element.classList.contains("note"))
@@ -652,7 +682,8 @@ class InternalDefinitionsMatcher {
       }
 
       if (count === 0) {
-        logger.error(`Invalid definition`, element);
+        const next = children[0];
+        logger.error(`Out of order or unrecognized element in definition${next ? `: ${next.localName}${next.className ? `.${next.className}` : ""}` : ""}<br>Required order is: definition, deprecated, example, note, source`, element);
         break;
       }
 
@@ -664,10 +695,20 @@ class InternalDefinitionsMatcher {
         children.shift();
       }
 
-      /* look for definition source */
+      /* look for deprecated marker (at most one) */
 
-      if (children.length > 0 && DefinitionSourceMatcher.match(children[0], logger)) {
+      if (children.length > 0 && DefinitionDeprecatedMatcher.match(children[0], logger)) {
+        children.shift();
+        if (children.length > 0 && DefinitionDeprecatedMatcher.match(children[0], logger))
+          logger.error(`Only one dd.deprecated is permitted per term`, children[0]);
+      }
+
+      /* look for examples to entry */
+      count = 0;
+
+      while (children.length > 0 && DefinitionExampleMatcher.match(children[0], logger)) {
         children.shift();
+        count++;
       }
 
       /* look for notes to entry */
@@ -678,6 +719,12 @@ class InternalDefinitionsMatcher {
         count++;
       }
 
+      /* look for definition source (must be last) */
+
+      if (children.length > 0 && DefinitionSourceMatcher.match(children[0], logger)) {
+        children.shift();
+      }
+
     }
 
     return true;

scripts/build.mjs

@@ -730,8 +730,10 @@ async function main() {
 
   const docMetadata = smpteValidate(dom.window.document, logger);
 
-  if (logger.hasFailed())
-    throw Error(`SMPTE schema validation failed:\n${logger.errorList().join("\n")}`);
+  if (logger.hasFailed()) {
+    const errors = logger.errorList().map(e => `  ${e.message}`).join("\n");
+    throw Error(`SMPTE schema validation failed:\n${errors}`);
+  }
 
    /* collect elements */
 

smpte.js

@@ -1194,6 +1194,18 @@ function numberExamples() {
   }
 }
 
+function markDeprecated() {
+  const terms = document.getElementById("terms-int-defs");
+  if (!terms) return;
+
+  for (const el of terms.querySelectorAll("dd.deprecated")) {
+    const label = document.createElement("span");
+    label.className = "heading-label";
+    label.appendChild(document.createTextNode("DEPRECATED: "));
+    el.insertBefore(label, el.firstChild);
+  }
+}
+
 function numberTerms() {
   const termsSection = document.getElementById("sec-terms-and-definitions");
   const terms = document.getElementById("terms-int-defs");
@@ -1487,6 +1499,7 @@ async function render() {
   numberFormulae();
   numberNotes();
   numberExamples();
+  markDeprecated();
   numberTerms();
   resolveLinks(docMetadata);
   insertTOC(docMetadata);

test/resources/html/validation/terms-note-to-entry-2-valid.html

@@ -31,9 +31,9 @@
         <dt><dfn>Clear</dfn></dt>
         <dt>CLR</dt>
         <dd>something that is clean</dd>
-        <dd><a href="#bib-smpte-standards-operations-manual"></a></dd>
         <dd class="note">The term shall not be used to refer to clarity of mind.</dd>
         <dd class="note">The term is not intended to be used ever.</dd>
+        <dd><a href="#bib-smpte-standards-operations-manual"></a></dd>
         <dt><dfn>Medium</dfn></dt>
         <dd>something that is not large as defined in <a href="#bib-smpte-standards-operations-manual"></a></dd>
       </dl>

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

@@ -31,8 +31,8 @@
         <dt><dfn>Clear</dfn></dt>
         <dt>CLR</dt>
         <dd>When something is clean</dd>
-        <dd><a href="#bib-smpte-standards-operations-manual"></a></dd>
         <dd class="note">The term shall not be used to refer to clarity of mind.</dd>
+        <dd><a href="#bib-smpte-standards-operations-manual"></a></dd>
       </dl>
     </section>
   </body>

test/src/testValidation.mjs

@@ -57,7 +57,7 @@ async function _test(path) {
   }
 
   console.log(`**** ${path} failed.`);
-  logger.errorList().map(msg => console.log(`    ${msg.message}`))
+  logger.errorList().map(msg => console.log(`    ${msg.message}`));
 
   return false;
 }