Normative text is text that describes elements of the design that are indispensable or contains the - conformance language keywords: "shall", "should", or "may". Informative text is text that is potentially - helpful to the user, but not indispensable, and can be removed, changed, or added editorially without - affecting interoperability. Informative text does not contain any conformance keywords.
+ if (docMetadata.pubType !== smpte.EG_PUBTYPE) { + + sec.innerHTML = ` +Normative text is text that describes elements of the design that are indispensable or contains the + conformance language keywords: "shall", "should", or "may". Informative text is text that is potentially + helpful to the user, but not indispensable, and can be removed, changed, or added editorially without + affecting interoperability. Informative text does not contain any conformance keywords.
+ +All text in this document is, by default, normative, except: the Introduction, any clause explicitly + labeled as "Informative" or individual paragraphs that start with "Note:"
+ +The keywords "shall" and "shall not" indicate requirements strictly to be followed in order to conform to the + document and from which no deviation is permitted.
+ +The keywords, "should" and "should not" indicate that, among several possibilities, one is recommended + as particularly suitable, without mentioning or excluding others; or that a certain course of action + is preferred but not necessarily required; or that (in the negative form) a certain possibility + or course of action is deprecated but not prohibited.
+ +The keywords "may" and "need not" indicate courses of action permissible within the limits of the document.
+ +The keyword "reserved" indicates a provision that is not defined at this time, shall not be used, + and may be defined in the future. The keyword "forbidden" indicates "reserved" and in addition + indicates that the provision will never be defined in the future.
-All text in this document is, by default, normative, except: the Introduction, any clause explicitly - labeled as "Informative" or individual paragraphs that start with "Note:"
+ ${implConformance} -The keywords "shall" and "shall not" indicate requirements strictly to be followed in order to conform to the -document and from which no deviation is permitted.
+Unless otherwise specified, the order of precedence of the types of normative information in + this document shall be as follows: Normative prose shall be the authoritative definition; + tables shall be next; then formal languages; then figures; and then any other language forms.
+ `; -The keywords, "should" and "should not" indicate that, among several possibilities, one is recommended - as particularly suitable, without mentioning or excluding others; or that a certain course of action - is preferred but not necessarily required; or that (in the negative form) a certain possibility - or course of action is deprecated but not prohibited.
+ } else { + + sec.innerHTML = ` +This Engineering Guideline is purely informative and meant to provide tutorial information to the + industry. It does not impose Conformance Requirements and avoids the use of Conformance Notation.
-The keywords "may" and "need not" indicate courses of action permissible within the limits of the document.
+Engineering Guidelines frequently provide tutorial information about a Standard or Recommended Practice + and when this is the case, the user should rely on the Standards and Recommended Practices referenced for + interoperability information.
+ `; -The keyword "reserved" indicates a provision that is not defined at this time, shall not be used, - and may be defined in the future. The keyword "forbidden" indicates "reserved" and in addition - indicates that the provision will never be defined in the future.
+ } -${implConformance} + if (docMetadata.pubType === smpte.EG_PUBTYPE) { + + const sections = document.querySelectorAll('section'); + sections.forEach((element) => { + let id = element.id; + if ((id !== "sec-front-matter") && (id !== "sec-foreword") && (id !== "sec-conformance")) { + if (element.innerText.includes("shall")) { + logger_.error(`EG must not contain Conformance Notation - "shall" found`, element); + } + if (element.innerText.includes("should")) { + logger_.error(`EG must not contain Conformance Notation - "should" found`, element); + } + if (element.innerText.includes("may")) { + logger_.error(`EG must not contain Conformance Notation - "may" found`, element); + } + } + }); + } -Unless otherwise specified, the order of precedence of the types of normative information in - this document shall be as follows: Normative prose shall be the authoritative definition; - tables shall be next; then formal languages; then figures; and then any other language forms.
- `; } const SMPTE_FOREWORD_ID = "sec-foreword"; From 5fd7bc9bab12d77c19abee2b672b31b1a663223a Mon Sep 17 00:00:00 2001 From: Steve LLamb <38917682+SteveLLamb@users.noreply.github.com> Date: Wed, 9 Oct 2024 18:27:54 -0700 Subject: [PATCH 2/7] add note to documentation about no conformance --- doc/main.html | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/main.html b/doc/main.html index 303aa90..6c8da07 100644 --- a/doc/main.html +++ b/doc/main.html @@ -491,6 +491,9 @@This section and additional text is not allowed for AG, OM, and EG docs.
+This section and additional text is not allowed for AG, OM, and EG docs.
+This section is prohibited when the document is an administrative guideline, operations manual or engineering guideline.
This section is prohibited when the document is an administrative guideline, operations manual or engineering guideline.
+This section is prohibited unless the document is a Standard or Recommended Practice.
diff --git a/smpte.js b/smpte.js index ec62007..5eeb876 100644 --- a/smpte.js +++ b/smpte.js @@ -606,14 +606,11 @@ function insertConformance(docMetadata) { let sec = document.getElementById(SMPTE_CONFORMANCE_ID); - if (docMetadata.pubType == smpte.OM_PUBTYPE) { + if (!(docMetadata.pubType == smpte.RP_PUBTYPE || docMetadata.pubType == smpte.ST_PUBTYPE)) { if (sec !== null) - logger_.error("OM must not contain a Conformance section."); - return; - } - - if ((docMetadata.pubType == smpte.EG_PUBTYPE) && (sec !== null)) { - logger_.error("EG must not contain a Conformance section."); + logger_.error(`An ${docMetadata.pubType} document must not contain a conformance section`); + if (docMetadata.pubType != smpte.EG_PUBTYPE) + return; } if (sec === null) { @@ -691,28 +688,6 @@ function insertConformance(docMetadata) { } - if (docMetadata.pubType === smpte.EG_PUBTYPE) { - - for (let section of document.querySelectorAll("body > section")) { - - let id = section.id; - - if (id === "sec-front-matter" || id === "sec-foreword" || id === "sec-conformance") - continue; - - if (section.innerText.toLowerCase().includes("shall")) { - logger_.error(`EG must not contain Conformance Notation - "shall" found`, section); - } - if (section.innerText.toLowerCase().includes("should")) { - logger_.error(`EG must not contain Conformance Notation - "should" found`, section); - } - if (section.innerText.toLowerCase().includes("may")) { - logger_.error(`EG must not contain Conformance Notation - "may" found`, section); - } - - }; - } - } const SMPTE_FOREWORD_ID = "sec-foreword"; @@ -1280,6 +1255,27 @@ function resolveLinks(docMetadata) { } } +const CONFORMANCE_RE = /\s*(shall)|(should)|(may)\s/i; + +function checkConformanceNotation(docMetadata) { + if (docMetadata.pubType !== smpte.EG_PUBTYPE) + return; + + for (let section of document.querySelectorAll("section:not(:has(section))")) { + + const id = section.id; + + if (id === SMPTE_FRONT_MATTER_ID || id === SMPTE_FOREWORD_ID || id === SMPTE_CONFORMANCE_ID) + continue; + + const r = CONFORMANCE_RE.exec(section.innerText); + + if (r !== null) + logger_.error(`An EG must not contain the conformance notation ${r[1]}`, section); + + }; +} + function asyncInsertSnippets() { return Promise.all(Array.from( document.querySelectorAll("pre[data-include]"), @@ -1326,6 +1322,7 @@ async function render() { let docMetadata = loadDocMetadata(); insertIconLink(); + checkConformanceNotation(docMetadata); insertFrontMatter(docMetadata); insertForeword(docMetadata); insertIntroduction(docMetadata); diff --git a/test/resources/html/validation/eg-conformance-valid.html b/test/resources/html/validation/eg-conformance-valid.html new file mode 100644 index 0000000..9af0ba8 --- /dev/null +++ b/test/resources/html/validation/eg-conformance-valid.html @@ -0,0 +1,27 @@ + + + + + + + + + + + + + + + +This is the scope of the document.
+The cat is blue.
+