Update tooling and instructions for ER and RDD (#315)

SteveLLamb · web-flow · commit 7e4ca8d97048 · 2025-04-25T11:11:29.000-07:00
* Update tooling and instructions for ER and RDD

* simplified the proponents to a `dl` in the foreward section

* check RDD has foreword

* min RDD for tests

* update min rdd

* update min rdd

* Update validation for dl in Foreword

* revert HEAD changes

* roll back gitignore

* update proponents example

* address comments and expand proponent example
diff --git a/doc/main.html b/doc/main.html
@@ -163,11 +163,13 @@ <h4><code>pubType</code></h4>
 
         <p>The element shall have a <code>content</code> attribute equal to one of the following values:</p>
         <ul>
-          <li><code>AG</code>, if the document is an Administrative Guideline;</li>
-          <li><code>OM</code>, if the document is an Operations Manual;</li>
           <li><code>ST</code>, if the document is a Standard;</li>
-          <li><code>RP</code>, if the document is a Recommended Practice; or</li>
-          <li><code>EG</code>, if the document is an Engineering Guideline.</li>
+          <li><code>RP</code>, if the document is a Recommended Practice;</li>
+          <li><code>EG</code>, if the document is an Engineering Guideline;</li>
+          <li><code>ER</code>, if the document is an Engineering Report;</li>
+          <li><code>RDD</code>, if the document is an Registered Disclosure Document;</li>
+          <li><code>AG</code>, if the document is an Administrative Guideline; or</li>
+          <li><code>OM</code>, if the document is an Operations Manual.</li>
         </ul>
 
       </section>
@@ -422,22 +424,60 @@ <h4>Overall structure</h4>
       <section id="sec-foreword-section">
         <h4>Foreword section</h4>
 
-        <p>The <dfn>Foreword</dfn> section contains author-supplied prose, e.g. list of substantive changes since the last edition,
-        that is added to the SMPTE boilerplate text.</p>
+        <section id="sec-foreword-general">
+          <h5>General</h5>
 
-        <p>The absence of this section indicates that no author-supplied prose was provided.</p>
 
-        <p>The <code>id</code> attribute shall be present on the <code>section</code> element and equal to
-        <code>sec-foreword</code>.</p>
+          <p>The <dfn>Foreword</dfn> section contains author-supplied prose, e.g. list of substantive changes since the last edition,
+          that is added to the SMPTE boilerplate text.</p>
 
-        <p>The heading shall not be present.</p>
+          <p>The absence of this section indicates that no author-supplied prose was provided.</p>
 
-        <div class="example">
+          <p>The <code>id</code> attribute shall be present on the <code>section</code> element and equal to
+          <code>sec-foreword</code>.</p>
+
+          <p>The heading shall not be present.</p>
+
+          <div class="example">
 <pre>&lt;section id=&quot;sec-foreword&quot;&gt;
   &lt;p&gt;This is the additional information relevant to the document.&lt;/p&gt;
 &lt;/section&gt;
 </pre>
-        </div>
+          </div>
+
+        </section>
+        <section id="sec-foreword-rdd">
+          <h5>RDD</h5>
+
+          <p>When <code>pubType</code> is set to <code>RDD</code>, the <a>Foreword</a> section shall be present and there there shall be a single <code>dl</code>, after any author-supplied prose if supplied, which contains contact information about the proponent(s) of the RDD document. </p>
+
+          <p>The <code>id</code> attribute shall be present on the <code>dl</code> element and equal to
+          <code>rdd-proponent</code>. </p>
+
+          <p>If present, the <code>dl</code> element shall use a single <code>dt</code> element for each company name designated as a Proponent of the document, and multiple lines of <code>dd</code> as needed for contact information for each company listed. The contact infomation should at least include an address and email, reach out to SMPTE HO for further deatails. </p> 
+
+          <div class="example">
+<pre>
+&lt;section id=&quot;element-proponent&quot;&gt;
+  &lt;p&gt;This is the additional information relevant to the document.&lt;/p&gt;
+  &lt;dl id=&quot;rdd-proponent&quot;&gt;
+    &lt;dt&gt;Company 1 Name Here&lt;/dt&gt;
+      &lt;dd&gt;Contact Name&lt;/dd&gt;
+      &lt;dd&gt;Company Address&lt;/dd&gt;
+      &lt;dd&gt;&lt;a&gt;Contact Email&lt;/a&gt;&lt;/dd&gt;
+      &lt;dd&gt;&lt;a&gt;Company Website&lt;/a&gt;&lt;/dd&gt;
+    &lt;dt&gt;Company 2 Name Here&lt;/dt&gt;
+      &lt;dd&gt;Contact Name&lt;/dd&gt;
+      &lt;dd&gt;Company Address&lt;/dd&gt;
+      &lt;dd&gt;&lt;a&gt;Contact Email&lt;/a&gt;&lt;/dd&gt;
+      &lt;dd&gt;&lt;a&gt;Company Website&lt;/a&gt;&lt;/dd&gt;
+  &lt;dl&gt;
+&lt;/section&gt;
+</pre>
+          </div>
+      
+        </section>
+
       </section>
 
       <section id="sec-introduction-section">
@@ -483,7 +523,7 @@ <h4>Scope section</h4>
         <h4>Conformance section</h4>
 
         <p>The <dfn>Conformance</dfn> section contains author-supplied, conformance-related prose that is added to the SMPTE
-        boilerplate text.</p>
+        boilerplate text that is generated depending on <code>pubType</code>.</p>
 
         <p>The absence of this section indicates that no author-supplied, conformance-related prose is provided.</p>
 
diff --git a/js/common.mjs b/js/common.mjs
@@ -30,17 +30,21 @@ export const AG_PUBTYPE = "AG";
 export const ST_PUBTYPE = "ST";
 export const RP_PUBTYPE = "RP";
 export const EG_PUBTYPE = "EG";
+export const ER_PUBTYPE = "ER";
+export const RDD_PUBTYPE = "RDD";
 
-export const PUB_TYPES = new Set([AG_PUBTYPE, OM_PUBTYPE, ST_PUBTYPE, RP_PUBTYPE, EG_PUBTYPE]);
+export const PUB_TYPES = new Set([AG_PUBTYPE, OM_PUBTYPE, ST_PUBTYPE, RP_PUBTYPE, EG_PUBTYPE, ER_PUBTYPE, RDD_PUBTYPE]);
 export const LONG_PUB_TYPE = new Map([
   [AG_PUBTYPE, "Administrative Guideline"],
   [OM_PUBTYPE, "Operations Manual"],
   [ST_PUBTYPE, "SMPTE Standard"],
   [RP_PUBTYPE, "SMPTE Recommended Practice"],
-  [EG_PUBTYPE, "SMPTE Engineering Guideline"]
+  [EG_PUBTYPE, "SMPTE Engineering Guideline"],
+  [ER_PUBTYPE, "SMPTE Engineering Report"],
+  [RDD_PUBTYPE, "SMPTE Registered Disclosure Document"]
 ])
 
-export const ENGDOC_PUBTYPES = new Set([ST_PUBTYPE, RP_PUBTYPE, EG_PUBTYPE]);
+export const ENGDOC_PUBTYPES = new Set([ST_PUBTYPE, RP_PUBTYPE, EG_PUBTYPE, ER_PUBTYPE, RDD_PUBTYPE]);
 
 export const PUB_STAGE_PUB = "PUB";
 export const PUB_STAGE_DP = "DP";
diff --git a/js/validate.mjs b/js/validate.mjs
@@ -495,10 +495,22 @@ class BlockMatcher {
   }
 }
 
+function validateProponents(sectionElement, logger) {
+
+  if (sectionElement.childElementCount > 0) {
+    for (const forewordElement of sectionElement.children) {
+      if (forewordElement.localName === "dl" && forewordElement.id !== "element-proponent") {
+        logger.error(`Foreword cannot contain dl element that doesn't have id of element-proponent`, forewordElement);
+      }
+    }
+    return;
+  }
+}
 
 class ForewordMatcher {
 
   static match(e, logger) {
+    validateProponents(e, logger);
     return e.localName === "section" && e.id === "sec-foreword";
   }
 }
@@ -829,6 +841,7 @@ function validateBody(body, logger) {
   if (elements.length > 0 && ForewordMatcher.match(elements[0], logger))
     elements.shift();
 
+
   /* validate optional introduction */
 
   if (elements.length > 0 && IntroductionMatcher.match(elements[0], logger))
diff --git a/smpte.js b/smpte.js
@@ -195,6 +195,8 @@ function insertFrontMatter(docMetadata) {
       case smpte.ST_PUBTYPE:
       case smpte.RP_PUBTYPE:
       case smpte.EG_PUBTYPE:
+      case smpte.ER_PUBTYPE:
+      case smpte.RDD_PUBTYPE:
         if (docMetadata.pubPart !== null)
           actualPubNumber += `-<span itemprop="doc-part" id="doc-part">${docMetadata.pubPart}</span>`;
         if (docMetadata.pubStage === smpte.PUB_STAGE_PUB) {
@@ -623,7 +625,7 @@ function insertConformance(docMetadata) {
   if (!(docMetadata.pubType == smpte.RP_PUBTYPE || docMetadata.pubType == smpte.ST_PUBTYPE || docMetadata.pubType == smpte.AG_PUBTYPE)) {
     if (sec !== null)
       logger_.error(`An ${docMetadata.pubType} document must not contain a conformance section`);
-    if (docMetadata.pubType != smpte.EG_PUBTYPE)
+    if (!(docMetadata.pubType == smpte.EG_PUBTYPE || docMetadata.pubType == smpte.ER_PUBTYPE))
       return;
   }
 
@@ -700,6 +702,14 @@ function insertConformance(docMetadata) {
     interoperability information.</p>
     `;
 
+  } else if (docMetadata.pubType === smpte.ER_PUBTYPE) {
+
+    sec.innerHTML = `
+    <h2>Conformance</h2>
+    <p>This Engineering Report is meant to provide information to the 
+    industry. It does not impose requirements.</p>
+    `;
+
   }  else {
     sec.innerHTML = `
     <h2>Conformance</h2>
@@ -720,7 +730,7 @@ function insertConformance(docMetadata) {
 
 const SMPTE_FOREWORD_ID = "sec-foreword";
 
-const SMPTE_AG_FOREWORD_BOILERPLATE = `<h2>Foreword</h2>
+const SMPTE_GEN_FOREWORD_BOILERPLATE = `<h2>Foreword</h2>
 <p>The Society of Motion Picture and Television Engineers (SMPTE) is an
 internationally-recognized standards developing organization. Headquartered
 and incorporated in the United States of America, SMPTE has members in over
@@ -730,26 +740,43 @@ by SMPTE’s Technology Committees. Participation in these Committees is open
 to all with a bona fide interest in their work. SMPTE cooperates closely
 with other standards-developing organizations, including ISO, IEC and ITU.
 SMPTE Engineering Documents are drafted in accordance with the rules given
-in its Standards Operations Manual. For more information, please visit
+in its Standards Operations Manual.</p> 
+
+<p>For more information, please visit
 <a href="https://www.smpte.org">www.smpte.org</a>.</p>
+`
+
+const SMPTE_AG_FOREWORD_BOILERPLATE = `${SMPTE_GEN_FOREWORD_BOILERPLATE}
 
 <p>This Standards Administrative Guideline forms an adjunct to the use and
 interpretation of the SMPTE Standards Operations Manual. In the event of a
 conflict, the Operations Manual shall prevail.</p>
 `
+const SMPTE_RDD_FOREWORD_BOILERPLATE = `<h2>Foreword</h2>
+<p>This document is a Registered Disclosure Document prepared by the sponsor(s) identified 
+below. It has been examined by the appropriate SMPTE Technology Committee and is believed to 
+contain adequate information to satisfy the objectives defined in the Scope, and to be   
+technically consistent.</p>
+<p>This document is NOT a Standard, Recommended Practice or Engineering Guideline and does NOT 
+imply a finding or representation of the Society.</p>
+<p>Every attempt has been made to ensure that the information contained in this document is 
+accurate. Errors in this document should be reported to the SMPTE Registered Disclosure 
+Document proponent(s) identified below with a copy to 
+<a href="mailto:eng@smpte.org">eng@smpte.org</a>.</p>
+
+<p>All other inquiries in respect of this document, including inquiries as to intellectual 
+property requirements, should be addressed to the SMPTE Registered Disclosure Document 
+proponent(s) identified below.</p>
 
-const SMPTE_DOC_FOREWORD_BOILERPLATE = `<h2>Foreword</h2>
-<p>The Society of Motion Picture and Television Engineers (SMPTE) is an
-internationally-recognized standards developing organization. Headquartered
-and incorporated in the United States of America, SMPTE has members in over
-80 countries on six continents. SMPTE’s Engineering Documents, including
-Standards, Recommended Practices, and Engineering Guidelines, are prepared
-by SMPTE’s Technology Committees. Participation in these Committees is open
-to all with a bona fide interest in their work. SMPTE cooperates closely
-with other standards-developing organizations, including ISO, IEC and ITU.
-SMPTE Engineering Documents are drafted in accordance with the rules given
-in its Standards Operations Manual.</p> For more information, please visit
-<a href="https://www.smpte.org">www.smpte.org</a>.</p>
+{{authorProse}}
+
+`
+const SMPTE_ER_FOREWORD_BOILERPLATE = `${SMPTE_GEN_FOREWORD_BOILERPLATE}
+
+{{authorProse}}
+`
+
+const SMPTE_DOC_FOREWORD_BOILERPLATE = `${SMPTE_GEN_FOREWORD_BOILERPLATE}
 
 <p>At the time of publication no notice had been received by SMPTE claiming patent
 rights essential to the implementation of this Engineering Document.
@@ -778,6 +805,22 @@ function insertForeword(docMetadata) {
     return;
   }
 
+  if (docMetadata.pubType == smpte.RDD_PUBTYPE) {
+    if (sec === null)
+      logger_.error("RDD must contain a Foreword section.");
+
+  }
+
+  const SMPTE_PROPONENT_ID = document.getElementById("element-proponent");
+
+  if (SMPTE_PROPONENT_ID === null && docMetadata.pubType === smpte.RDD_PUBTYPE) {
+    logger_.error("Missing required proponents.");
+    return;
+  } if (SMPTE_PROPONENT_ID !== null && docMetadata.pubType !== smpte.RDD_PUBTYPE) {
+    logger_.error("Proponents only allowed for RDD documents.");
+    return;
+  } 
+
   if (sec === null && docMetadata.pubType != smpte.OM_PUBTYPE) {
     sec = document.createElement("section");
     sec.id = SMPTE_FOREWORD_ID;
@@ -788,20 +831,27 @@ function insertForeword(docMetadata) {
 
   let authorProse = sec.innerHTML;
 
-  if (smpte.ENGDOC_PUBTYPES.has(docMetadata.pubType)) {
+  if (smpte.ENGDOC_PUBTYPES.has(docMetadata.pubType) && docMetadata.pubType != smpte.RDD_PUBTYPE) {
     authorProse = `<p>This document was prepared by Technology Committee ${docMetadata.pubTC}.</p>` + authorProse;
   }
 
   if (docMetadata.pubType == smpte.AG_PUBTYPE) {
     if (authorProse.trim().length > 0)
       logger_.error("AGs cannot contain author-specified Foreword prose.")
     sec.innerHTML = fillTemplate(SMPTE_AG_FOREWORD_BOILERPLATE, {copyrightYear: (new Date()).getFullYear()});
+  } else if (docMetadata.pubType == smpte.RDD_PUBTYPE) {
+    sec.innerHTML = fillTemplate(SMPTE_RDD_FOREWORD_BOILERPLATE, {authorProse: authorProse, copyrightYear: (new Date()).getFullYear()});  
+  } else if (docMetadata.pubType == smpte.ER_PUBTYPE) {
+    sec.innerHTML = fillTemplate(SMPTE_ER_FOREWORD_BOILERPLATE, {authorProse: authorProse, copyrightYear: (new Date()).getFullYear()});  
   } else {
     sec.innerHTML = fillTemplate(SMPTE_DOC_FOREWORD_BOILERPLATE, {authorProse: authorProse, copyrightYear: (new Date()).getFullYear()});
   }
 
 }
 
+  
+  
+
 function addHeadingLinks(docMetadata) {
   const headings = document.querySelectorAll("h2, h3, h4, h5, h6");
 
@@ -1286,7 +1336,7 @@ function resolveLinks(docMetadata) {
 const CONFORMANCE_RE = /\s*(shall)|(should)|(may)\s/i;
 
 function checkConformanceNotation(docMetadata) {
-  if (docMetadata.pubType !== smpte.EG_PUBTYPE)
+  if (!(docMetadata.pubType == smpte.EG_PUBTYPE || docMetadata.pubType == smpte.ER_PUBTYPE))
     return;
 
   for (let section of document.querySelectorAll("section:not(:has(section))")) {
@@ -1299,7 +1349,7 @@ function checkConformanceNotation(docMetadata) {
     const r = CONFORMANCE_RE.exec(section.innerText);
 
     if (r !== null)
-      logger_.error(`An EG must not contain the conformance notation ${r[1]}`, section);
+      logger_.error(`An ${docMetadata.pubType} must not contain the conformance notation ${r[1]}`, section);
 
   };
 }
diff --git a/test/resources/html/validation/rdd-standalone-invalid.html b/test/resources/html/validation/rdd-standalone-invalid.html
@@ -0,0 +1,34 @@
+<!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="invalid" />
+    <meta itemprop="pubType" content="RDD" />
+    <meta itemprop="pubNumber" content="26" />
+    <meta itemprop="pubState" content="draft" />
+    <meta itemprop="pubStage" content="WD" />
+    <meta itemprop="pubTC" content="XX" />
+    <meta itemprop="pubConfidential" content="yes" />
+    <meta itemprop="pubDateTime" content="2025-02-26" />
+    <title>Title of the document</title>
+  </head>
+  <body>
+
+    <section id="sec-foreword">
+      <dl id="element-proponents">
+        <dt>Company name</dt>
+          <dd>Contact name</dd>
+          <dd>Contact email</dd>
+          <dd>Company Address</dd>
+          <dd>Company website</dd>
+      </dl>
+    </section>
+    
+    <section id="sec-scope">
+      <p>This is the scope of the document.</p>
+    </section>
+  </body>
+</html>
diff --git a/test/resources/html/validation/rdd-standalone-valid.html b/test/resources/html/validation/rdd-standalone-valid.html
@@ -0,0 +1,34 @@
+<!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="RDD" />
+    <meta itemprop="pubNumber" content="26" />
+    <meta itemprop="pubState" content="draft" />
+    <meta itemprop="pubStage" content="WD" />
+    <meta itemprop="pubTC" content="XX" />
+    <meta itemprop="pubConfidential" content="yes" />
+    <meta itemprop="pubDateTime" content="2025-02-26" />
+    <title>Title of the document</title>
+  </head>
+  <body>
+
+    <section id="sec-foreword">
+      <dl id="element-proponent">
+        <dt>Company name</dt>
+          <dd>Contact name</dd>
+          <dd>Contact email</dd>
+          <dd>Company Address</dd>
+          <dd>Company website</dd>
+      </dl>
+    </section>
+    
+    <section id="sec-scope">
+      <p>This is the scope of the document.</p>
+    </section>
+  </body>
+</html>
