Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update conformance for EGs #287

Merged
merged 8 commits into from
Dec 23, 2024
Merged

Update conformance for EGs #287

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
75f052e
Update conformance for EGs
SteveLLamb Oct 10, 2024
5fd7bc9
add note to documentation about no conformance
SteveLLamb Oct 10, 2024
c17ea95
account for all cases on search
SteveLLamb Oct 10, 2024
212bd78
changes as requested
SteveLLamb Oct 16, 2024
5059528
update doc note
SteveLLamb Oct 16, 2024
fc85e00
updates in loop
SteveLLamb Nov 5, 2024
1629690
Improve conformance notation matching
palemieux Dec 22, 2024
7fd36a8
Merge branch 'main' into features/conformance-options
SteveLLamb Dec 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions doc/main.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -491,6 +491,9 @@ <h4>Conformance section</h4>
&lt;/section&gt;
</pre>
</div>

<p class="note">This section and additional text is not allowed for AG, OM, and EG docs.</p>
SteveLLamb marked this conversation as resolved.
Show resolved Hide resolved

</section>

<section id="sec-norm-refs-section">
Expand Down
89 changes: 65 additions & 24 deletions smpte.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -612,6 +612,11 @@ function insertConformance(docMetadata) {
return;
}

if (docMetadata.pubType == smpte.EG_PUBTYPE) {
SteveLLamb marked this conversation as resolved.
Show resolved Hide resolved
if (sec !== null)
SteveLLamb marked this conversation as resolved.
Show resolved Hide resolved
logger_.error("EG must not contain a Conformance section.");
}

if (sec === null) {
sec = document.createElement("section");
sec.id = SMPTE_CONFORMANCE_ID;
Expand All @@ -632,44 +637,80 @@ function insertConformance(docMetadata) {

} else {

implConformance = sec.innerText.innerHTML;
implConformance = sec.innerText;
SteveLLamb marked this conversation as resolved.
Show resolved Hide resolved

}

} else if (sec.innerText.trim().length !== 0) {
logger_.error("Conformance section not used in AGs.");
}

sec.innerHTML = `
<h2>Conformance</h2>
<p>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. </p>
if (docMetadata.pubType !== smpte.EG_PUBTYPE) {

sec.innerHTML = `
<h2>Conformance</h2>
<p>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. </p>

<p>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:" </p>

<p>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.</p>

<p>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.</p>

<p>The keywords "may" and "need not" indicate courses of action permissible within the limits of the document. </p>

<p>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.</p>

<p>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:" </p>
${implConformance}

<p>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.</p>
<p>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.</p>
`;

<p>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.</p>
} else {

sec.innerHTML = `
<h2>Conformance</h2>
<p>This Engineering Guideline is purely informative and meant to provide tutorial information to the
SteveLLamb marked this conversation as resolved.
Show resolved Hide resolved
industry. It does not impose Conformance Requirements and avoids the use of Conformance Notation.</p>

<p>The keywords "may" and "need not" indicate courses of action permissible within the limits of the document. </p>
<p>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.</p>
`;

<p>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.</p>
}

${implConformance}
if (docMetadata.pubType === smpte.EG_PUBTYPE) {

const sections = document.querySelectorAll('section');
sections.forEach((element) => {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

use for...of when the body of the loop is huge.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tired this the first time around, but the element links don't pass through via the logger_.error messages.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That should work:

const list = document.querySelectorAll("input[type=checkbox]");
for (const checkbox of list) {
  checkbox.checked = true;
}

https://developer.mozilla.org/en-US/docs/Web/API/NodeList#example

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is updated in fc85e00

let id = element.id;
SteveLLamb marked this conversation as resolved.
Show resolved Hide resolved
if ((id !== "sec-front-matter") && (id !== "sec-foreword") && (id !== "sec-conformance")) {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
if ((id !== "sec-front-matter") && (id !== "sec-foreword") && (id !== "sec-conformance")) {
if (id === "sec-front-matter" || id === "sec-foreword" && id === "sec-conformance")
continue;

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The logic i have catches the sections that are to be excluded from the searching. This update only highlights those sections, and doesn't continue the search past those.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The logic is right. I think the following code style:

while () {

  if (bad) continue;

  Do a lot of things;
}

is easier to read and maintain than:

while () {

  if (not bad) {
    Do a lot of things;
  }
}

because Do a lot of things; can be big and you have to remember you are in a particular condition.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, yea understood. I meant the or and and combination. I did the same thing you mention with return; in the last update.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

updated in fc85e00

if (element.innerText.toLowerCase().includes("shall")) {
logger_.error(`EG must not contain Conformance Notation - "shall" found`, element);
}
if (element.innerText.toLowerCase().includes("should")) {
logger_.error(`EG must not contain Conformance Notation - "should" found`, element);
}
if (element.innerText.toLowerCase().includes("may")) {
logger_.error(`EG must not contain Conformance Notation - "may" found`, element);
}
}
});
}

<p>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.</p>
`;
}

const SMPTE_FOREWORD_ID = "sec-foreword";
Expand Down
Loading