HTML Pub — Tooling and documentation for HTML documents

7.2.1 General🔗

The head element shall contain the following:

• itemscope attribute equal to itemscope;
• itemtype attribute equal to 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" />
• a script element whose src attribute links to the smpte.js module in the tooling directory.

The title element shall be equal to the title of the document, excluding:

• the name of the publisher, e.g., SMPTE;
• the document type, e.g., ST;
• the document number, e.g., 428-1;
• the title of the suite if the document is part of a suite.

EXAMPLE The title of SMPTE ST 429-2 is DCP Operational Constraints.

In addition to the title element, the head element contains SMPTE publication metadata in the form of meta elements as specified below.

7.2.2 pubType🔗

The head element shall contain exactly one meta element with an itemprop attribute equal to pubType.

The element shall have a content attribute equal to one of the following values:

• ST, if the document is a Standard;
• RP, if the document is a Recommended Practice;
• EG, if the document is an Engineering Guideline;
• ER, if the document is an Engineering Report;
• RDD, if the document is an Registered Disclosure Document;
• AG, if the document is an Administrative Guideline; or
• OM, if the document is an Operations Manual.

7.2.3 pubNumber🔗

The head element shall contain zero or one meta element with an itemprop attribute equal to pubNumber.

The element shall be present if:

• pubState is pub; or
• pubPart is specified; or
• pubVersion is specified.

The content attribute of the element shall be equal to the document number, which is a sequence of digits.

7.2.4 pubPart🔗

The head element shall contain exactly one meta element with an itemprop attribute equal to pubPart if the document is part of a suite, and none otherwise.

The element shall have a content attribute equal to the document part number, which is a sequence of digits.

7.2.5 pubSuiteTitle🔗

The head element shall contain exactly one meta element with an itemprop attribute equal to pubSuiteTitle if the document is part of a suite, and none otherwise.

The element shall have a content attribute equal to the title of the document suite.

7.2.6 pubVersion🔗

The head element shall contain zero or one meta element with an itemprop attribute equal to pubVersion.

The element shall have a content attribute. The value of this attribute overrides the document version that is automatically generated by the tooling for Engineering Document and the pubStage is PUB.

This element shall be present if and only if the document version does not follow current practice.

7.2.7 pubState🔗

The head element shall contain one meta element with an itemprop attribute equal to pubState.

The element shall have a content attribute equal to one of the following values:

• draft, if the document is a draft.
• pub, if the document is published.

For further explanation of determining the value of the document's pubState, see Clause C.1

7.2.8 pubStage🔗

The head element shall contain zero or one meta element with an itemprop attribute equal to pubStage.

The element shall be present if the document is an Engineering Document.

The element shall have a content attribute equal to one of the following values:

• WD, if the document is a Working Draft;
• CD, if the document is a Committee Draft;
• FCD, if the document is a Final Committee Draft;
• DP, if the document is a Draft Publication; or
• PUB, if the document is a Published.

For further explanation of determining the value of the document's pubStage, see Clause C.1

7.2.9 pubRevisionOf🔗

The head element shall contain zero or one meta element with an itemprop attribute equal to pubRevisionOf.

The element shall have a content attribute equal to the identifier of the document that the document revises.

7.2.10 pubTC🔗

The head element shall contain zero or one meta element with an itemprop attribute equal to pubTC.

The element shall be present if the document is an Engineering Document.

The element shall have a content attribute equal to the identifier of the TC responsible for the document.

7.2.11 pubConfidential🔗

The head element shall contain zero or one meta element with an itemprop attribute equal to pubConfidential.

If present, the element shall have a content attribute equal to one of the following values:

yes

The Engineering Document is SMPTE confidential.

no

The Engineering Document is not SMPTE confidential.

The element shall not be present unless the document is an Engineering Document.

Unless specified otherwise, an Engineering Document that is not at publication stage is confidential.

7.2.12 pubDateTime🔗

The head element shall contain zero or one meta element with an itemprop attribute equal to pubDateTime.

The element shall be present if pubState is pub.

The element shall have a content attribute that conforms to the pattern YYYY-MM-DD, where YYYY, MM and DD are the year, month and day of the most recent approval date of the document.

See AG-02 for a definition of approval date.

7.2.13 effectiveDateTime🔗

The head element shall contain zero or one meta element with an itemprop attribute equal to effectiveDateTime.

The element shall be present if the document is an Operations Manual and the pubState is pub.

The element shall have a content attribute that conforms to the pattern YYYY-MM-DD, where YYYY, MM and DD are the year, month and day that the document becomes effective.

7.2.14 Additional script elements🔗

The head element may contain additional script elements that import JavaScript libraries for document layout, e.g. MathJax

<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script type="text/javascript" id="MathJax-script"
  async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-svg.js">
</script>

7.2.15 Additional stylesheet and style elements🔗

The head element shall not contain additional link elements that import either internal or external stylesheet files, nor shall it contain inline style elements.

<link rel="stylesheet"  href="./styles.css">
<style>
  p { color: red; }
</style>

NOTE —⁠ Also see 7.4.19 for guidance on styling.

7.3.1 Overall structure🔗

The body element shall consist of an ordered sequence of section elements to create their respective clauses, as specified at Table 1.

From the author-supplied section elements specified at Table 1, the tooling generates a document structure that conforms to SMPTE editorial requirements. For example:

• clauses are numbered automatically;
• headings of section elements (clause names) other than Prose and Annex are automatically generated;
• boilerplate is added, including the SMPTE masthead.

7.3.2 Foreword section🔗

<section id="sec-foreword">
  <p>This is the additional information relevant to the document.</p>
</section>

<section id="sec-foreword">
  <p>This is the additional information relevant to the document.</p>
  <dl id="element-proponent">
    <dt>Company 1 Name Here</dt>
      <dd>Contact Name</dd>
      <dd>Company Address</dd>
      <dd><a>Contact Email</a></dd>
      <dd><a>Company Website</a></dd>
    <dt>Company 2 Name Here</dt>
      <dd>Contact Name</dd>
      <dd>Company Address</dd>
      <dd><a>Contact Email</a></dd>
      <dd><a>Company Website</a></dd>
  <dl>
</section>

7.3.3 Introduction section🔗

The Introduction section contains author-supplied prose that forms the introduction of the document.

The absence of this section indicates that the document has no introduction.

The id attribute shall be present on the section element and equal to sec-introduction.

The heading shall not be present.

<section id="sec-introduction">
  <p>This is the introduction.</p>
</section>

7.3.4 Scope section🔗

The Scope section contains author-supplied prose that forms the scope of the document.

The id attribute shall be present on the section element and equal to sec-scope.

The heading shall not be present.

<section id="sec-scope">
  <p>This is the scope.</p>
</section>

7.3.5 Conformance section🔗

The Conformance section contains author-supplied, conformance-related prose that is added to the SMPTE boilerplate text that is generated depending on pubType.

The absence of this section indicates that no author-supplied, conformance-related prose is provided.

The id attribute shall be present on the section element and equal to sec-conformance.

The heading shall not be present.

<section id="sec-conformance">
  <p>These are additional conformance requirements and definitions.</p>
</section>

This section is prohibited unless the document is a Standard or Recommended Practice.

7.3.6 Normative references section🔗

The Normative references section collects normative references cited in the document.

The id attribute shall be present on the section element and equal to sec-normative-references.

The heading shall not be present.

The absence of this section indicates that no normative references are cited by the document.

If present, the section shall contain a single ul element where each li element is a normative reference, such that:

• Each li element shall contain one cite element, with value that contains the text that will be used when citing the reference in the prose.
• The cite element shall contain an id attribute with value prefixed by bib-.
• Each li element may contain additional title information.
• Each li element may contain one a element that contains a location where the reference can be retrieved.
• Each li element may contain one span element with a class="doi" attribute that contains the DOI of the document. Using this will also create a DOI resolver URL.

The DOI span element should be used, and not the a element, for both the most recent and specific editions of a SMPTE document. SMPTE HO can provide guidance for specific DOIs available.

Undated references should be used, since they point to the most up-to-date edition of a document.

Dated references shall be used when referencing a specific element of the document, e.g., a table. They should also be used when past and future editions of the document are likely to be inadequate.

<section id="sec-normative-references">
  <ul>
    <li>
      <cite id="bib-HTML-5">HTML Standard</cite>, Living Standard
      <a>https://html.spec.whatwg.org/multipage/</a>
    </li>
    <li>
      <cite id="bib-SMPTE-st429-18">SMPTE ST 429-18</cite>, D-Cinema Packaging - Immersive Audio Track 
      File 
      <span class="doi">10.5594/SMPTE.ST429-18</span>
    </li>
    <li>
      <cite id="bib-SMPTE-st429-18-2023">SMPTE ST 429-18:2023</cite>, D-Cinema Packaging - Immersive 
      Audio Track File (2023 Edition)
      <span class="doi">10.5594/SMPTE.ST429-18.2023</span>
    </li>
  </ul>
</section>

7.3.7 Terms and definitions section🔗

The Terms and definitions section collects terms, abbreviations and symbols that are not defined inline the clauses of the document, as described in 7.4.6.

The id attribute shall be present on the section element and equal to sec-terms-and-definitions.

The heading shall not be present.

The absence of this section indicates that all terms and abbreviations are defined inline the clauses of the document.

If present, the section contains one or both of the following elements:

• a ul element that cites external definitions, subject to the following constraints:
  • The id attribute of the ul element shall be equal to terms-ext-defs.
  • Each li element contains a citation link to a normative reference (see 7.3.6), whose definitions are included by reference.
• a dl element that contains individual definitions and abbreviations, subject to the following constraints:
  • The id attribute of the dl element shall be equal to terms-int-defs.
  • Each dt element contains a single term, abbreviation or symbol. Zero or more additional dt elements can follow the first dt element, in which case all the terms, abbreviations and symbols in the immediately preceding dt elements are synonyms.
  • The dd elements following the dt element(s) shall appear in the following order - each group is optional (except the definition), but if present, it shall appear in this sequence:
    1. Deprecated: the first dd element, if present, shall have a class attribute containing deprecated, indicating the term is deprecated. At most one such element is permitted.
    2. Definition: the next dd element shall be the definition of the term. This element is required. References to other defined terms and dfn elements are permitted using <a> elements without an href attribute. Citations to clauses or external references (i.e. <a href="#bib-HTML-5">) are not permitted.
    3. Examples: the next dd element(s), if present, shall each have a class attribute containing example.
    4. Notes: the next dd element(s), if present, shall each have a class attribute containing note. References to defined terms, clauses, and external references are all permitted.
    5. Source: the last dd element, if present, shall have a class attribute containing source and serves as the source of the definition. At most one such element is permitted. It shall contain a reference to a bibliographic entry and may contain additional text. If any changes are made to the original terminological entry, this shall be indicated, along with a description of what has been modified.

<section id="sec-terms-and-definitions">
  <ul id="terms-ext-defs">
    <li><a href="#bib-HTML-5"></a></li>
  </ul>
  <dl id="terms-int-defs">
    <dt><dfn>key number</dfn></dt>
    <dd class="deprecated">deprecated term</dd>
    <dd>number that is printed with ink or exposed onto the film at the time of
    manufacture at regular intervals, typically one foot</dd>
    <dd class="example">An example of a key number is 12345.</dd>
    <dd class="note">Key number shall not be confused with key frame.</dd>
    <dd class="source"><a href="#bib-key-number-spec"></a>, modified - definition has been updated.</dd>
  </dl>
</section>

NOTE —⁠ The boilerplate of the clause will be generated automatically.

7.3.8 Prose section(s)🔗

Each Prose sectioncontains author-supplied technical prose.

A Prose section may contain other nested Prose section elements. If any child of a Prose section is a Prose section, then all children shall be Prose section elements.

The id attribute shall be present and its value should be prefixed with sec-.

The class attribute of a Prose section shall not contain the annex class.

A section heading element of the appropriate level shall be present, starting with level 2 (h2) for all Prose section elements that are children of the body element.

Prose section elements are automatically numbered, so neither the heading element nor its id attribute should contain numbering information.

<section id="sec-prose-clause">
  <h2>Prose Clause</h2>
  <section id="sec-prose-sub-clause">
    <h3>Prose Sub Clause</h3>
    <p>Some technical content</p>
  </section>
  <section id="sec-next-prose-sub-clause">
    <h3>Next Prose Sub Clause</h3>
    <p>Some technical content</p>
  </section>
</section>

7.3.9 Annex section(s)🔗

An Annex section contains an author-supplied technical annex.

The requirements for an Annex section are the same as those of a Prose section, with the exception that the Annex section shall contain the class attribute with value of annex.

An Annex section shall not contain nested annex class elements.

By default, an Annex section is labeled as (Normative). To label any Annex section as (Informative), the class attribute value of informative shall be present.

<section class="annex informative" id="sec-additional-info">
  <h2>Additional Info</h2>
  <section id="sec-additional-info-sub-section">
    <h3>Additional Info Sub Clause</h3>
    <p>Some technical content</p>
  </section>
  <section id="sec-additional-info-sub-section-more">
    <h3>Additional Info Sub Clause More</h3>
    <p>Some technical content</p>
  </section>
</section>

7.3.10 Additional elements section🔗

The additional elements section collects the non-prose elements of the document.

The id attribute shall be present on the section element and equal to sec-elements.

The heading of thesection shall not be present.

If present, the section shall:

• come immediately before the Bibliography section; and
• contain a single ordered list ol where each element li contains exactly one a that links to an element of the document.

Each a element shall have:

• an id attribute whose value is prefixed with element-;
• a title attribute that provides a short description of the element;
• a href attribute that links to the element, as detailed below; and
• a class attribute that contains the token informative if the element is informative.

Each additional element shall be managed in one of the following ways:

• as a file in the doc/elements directory, in which case the href attribute shall be relative path to the file, e.g. elements/element.txt (Element a); or
• in a separate SMPTE repository, in which case the href attribute shall be the absolute URL to a version of the repo, e.g. https://github.com/SMPTE/html-pub/tree/631ed7a0312fa183c356a7b742129ce46f92736f (Element b).

Non-SMPTE repositories and SMPTE repositories that are not an integral part of the document shall be cited using a bibliographic reference.

<section id="sec-elements">
  <ol>
    <li>
      <a id="element-sample-text" title="Description of the element" href="elements/form.docx"></a>
    </li>
  </ol>
</section>

NOTE —⁠ This clause will automatically be labeled as the last Annex clause and marked as informative.

7.3.11 Bibliography section🔗

The Bibliography section contains author-supplied bibliographic references.

The id attribute shall be present on the section element and equal to sec-bibliography.

The heading shall not be present.

The absence of this section indicates that no bibliographic references are cited by the document.

If present, the section shall contain a single ul element that conforms to the same requirements as the ul element of the normative references 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 of ISO and IEC documents (Ninth edition, 2021)
      <a>https://www.iso.org/sites/directives/current/part2/index.xhtml</a>
    </li>
  </ul>
</section>

7.4.1 Referencing clauses🔗

When referencing a clause, an a element with its href attribute referencing a section element shall be used. The text of the link will be automatically set to clause number.

7.4.2 Citing normative references🔗

When citing a normative reference, an a element with its href attribute referencing a cite element from the normative references section shall be used. The text of the link will be automatically set to the contents of the cite element.

EXAMPLE <a href="#bib-HTML-5"></a> is rendered as HTML Standard.

7.4.3 Citing non-prose elements🔗

When citing an non-prose element of the document, an a element with its href referencing an a element from the additional elements section shall be used. The text of the link will be automatically set to the letter of the element in element list.

7.4.4 Citing bibliographic references🔗

When citing a bibliographic reference in the prose, an a element with its href attribute referencing a cite element from the Bibliography section shall be used. The text of the link will be automatically set to the contents of the cite element.

EXAMPLE <a href="#bib-iso-directives-part2"></a> is rendered as ISO/IEC Directives, Part 2.

7.4.5 External links🔗

Links to external resources shall be written by wrapping the URL in an a element

EXAMPLE <a>https://www.iso.org/sites/directives/current/part2/index.xhtml</a> is rendered as https://www.iso.org/sites/directives/current/part2/index.xhtml.

NOTE —⁠ An href attribute will automatically be generated.

7.4.6 Inline terms🔗

A term can be defined by wrapping it in a dfn element.

EXAMPLE 1 <dfn data-lt="alternate1|alternate2">term</dfn>

The optional data-lt attribute specify alternate forms of the term, each separated by a | character.

An optional id attribute can be specified; otherwise one will be generated automatically.

7.4.7 Lists of key-value pairs🔗

A dl element can be used for key-value pairs lists.

Since styling is automatically applied to dl elements, author should not specify additional formatting, either in the form of CSS styles or using markup such as the b element.

At least one dd shall be present for each dt element.

<dl>
  <dt>imperative forms</dt>
  <dd>"see"</dd>
  <dt>non-imperative forms</dt>
  <dd>"according to"</dd>
  <dd>"as defined in"</dd>
  <dd>"as specified in"</dd>
  <dd>"details as given in"</dd>
  <dd>"in accordance with"</dd>
</dl>

7.4.8 Lists🔗

A list can be inserted using either an ol or ul element. The ul (unordered list) element should be used when the order of listed items is not meaningful or important. The ol (ordered list) element should be only used when the order of listed items is meaningful and/or important to the list and/or document.

General guidelines for lists:

• An ol or ul element shall contain one (1) or more li element(s).
• A li element may contain one (1) or more nested ol or ul element(s).
• An ol element should not be nested within an ul element.

<ol>
  <li>First list item</li>
  <li>Second list item</li>
</ol>

For more examples of various list layouts and optional list types, see Annex B

7.4.9 Figures🔗

A figure can be inserted using a figure element, using the image format as defined in SMPTE AG 02, with the following requirements.

The figure element shall contain:

• an id attribute whose value starts with figure-
• one img or pre element
• one figcaption element following the img or pre element

If an img element is present, then its src attribute shall be present and be a relative path starting with the string media/.

Figures are automatically numbered.

EXAMPLE 1

<figure id="figure-sample-image">
  <img src="media/sample.svg">
  <figcaption>Example of a figure</figcaption>
</figure>

is rendered as

When referencing a figure in the prose, an a element with its href attribute referencing the figure element shall be used. The text of the link will be automatically set to the number of the figure.

7.4.10 Tables🔗

Tables can be inserted by using a table element.

The table element shall contain:

• an id attribute whose value starts with tab-
• one caption element as the first child of the table element
• one thead element, containing one tr element, with th element(s) as needed for each column header
• one or more tbody element, with tr element(s) as needed for each row

Unless all columns are uniform in contents, the relative width of each column should be specified by setting the CSS width property as a percentage value on each th element.

NOTE 1 —⁠ Page breaks are avoided within a tbody element when generating PDF. Care should be taken for especially long tables to ensure rendering is as expected. For data in tables spanning multiple pages, other options should be considered and used.

<table id="tab-sample-tabledata">
  <caption>Sample Table</caption>
  <thead>
    <tr>
      <th>Sample Number</th>
      <th>Sample Name</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>0001</td>
      <td>Name 01</td>
    </tr>
    <tr>
      <td>0002</td>
      <td>Name 02</td>
    </tr>
  </tbody>
</table>

When referencing a table in the prose, an a element with its href attribute referencing the table element shall be used. The text of the link will be automatically set to the number of the table.

For more examples of various table layouts and optional cell/column text alignment, see Annex A

Tables may include footnotes. Footnotes shall appear in a tfoot element at the foot of the table, each as a p element with class="footnote" and a unique id attribute. Footnotes are automatically assigned superscript lowercase letters (a, b, c, etc) in the order they appear in the tfoot element. References to footnotes within the table body are marked with an a element whose href attribute references the footnote's id.

NOTE 2 —⁠ Footnotes are only permitted within tables. They must not be used outside of a table element.

NOTE 3 —⁠ Each footnote reference (a element) shall be in the same table as the footnote it references, and each footnote shall be referenced exactly once.

<table id="tab-sample-footnote">
  <caption>Sample Table with Footnotes</caption>
  <thead>
    <tr>
      <th>Sample Number</th>
      <th>Sample Name</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>0001</td>
      <td>Name 01 <a href="#fn-doc-example"></a></td>
    </tr>
    <tr>
      <td>0002</td>
      <td>Name 02</td>
    </tr>
  </tbody>
  <tfoot>
    <tr>
      <td colspan="2">
        <p class="footnote" id="fn-doc-example">Footnote content goes here.</p>
      </td>
    </tr>
  </tfoot>
</table>

Notes are permitted in tables cells or tfoot elements and are automatically numbered. When a note is also present in the tfoot, it shall appear before all footnotes:

<tfoot>
  <tr>
    <td colspan="2">
      <p class="note">Note content goes here.</p>
      <p class="footnote" id="fn-doc-example-2">Footnote content goes here.</p>
    </td>
  </tr>
</tfoot>

7.4.11 External code snippets🔗

External code snippets can be inserted by setting the data-include attribute on a pre element to the relative path of the snippet.

<pre data-include="snippets/example.txt"></pre>

This an example.

Keeping code snippets separate from the main element allows the snippets to be individually formatted and validated.

External code snippets are not additional elements of the document and are not listed in the Additional element annex, which is covered at 7.3.10.

7.4.12 Internal code snippets🔗

Internal code snippets can be inserted by using pre element.

<pre>
SCHEMAID = %s"https://www.smpte-ra.org/json-schema/" PUBNUM "/" REVISION [ "/" SHORTNAME]
SHORTNAME = 1*4("/" 1*(ALPHA / DIGIT / "-" / "_" / ".") )
PUBNUM = 1*(DIGIT) ["-" 1*(DIGIT)]
REVISION = STABLEREV
STABLEREV = 4(DIGIT) [2(DIGIT)]
</pre>

The pre element preserves all white space. As a result, the pre element and its contents should not be indented.

7.4.13 Notes🔗

A note is inserted by using a p or div element whose class attribute is equal to note. The element element can also have an id attribute, in which case the value of the id attribute shall start with the string note-.

Notes will automatically be formatted and numbered.

<p id="note-example-ref" class="note">
  The license portion of Annex A is verbatim the BSD-3-Clause license
  available at <a>https://spdx.org/licenses/BSD-3-Clause.html</a>.
</p>

A note can also be cited by referencing the value of the id attribute.

7.4.14 Examples🔗

An example is inserted by using a p or div element whose class attribute is equal to example. The element can also have an id attribute, in which case the value of the id attribute shall start with the string ex-.

Notes will automatically be formatted and numbered.

<div id="ex-example-ref" class="example">The number <i>0.0003</i> can be written 
<i>3 × 10−4</i> but is never written <i>3e−4</i>.</div>

An example can also be cited by referencing the value of the id attribute.

7.4.15 Quotes and blockquotes🔗

Prose can be quoted inline using the q element or as a block using the blockquote element.

<blockquote>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat.</blockquote>

This is a quote: <q>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
do eiusmod tempor incididunt ut labore et dolore magna aliqua.</q>

7.4.16 Formulae🔗

Formulae are specified using the HTML math element.

Unless specified otherwise, a formula is inline.

One needs to evaluate <math><mrow><mi>y</mi><mo>=</mo><mi>a</mi><msup><mi>x</mi><mn>2</mn></msup><mo>+</mo>
<mi>b</mi><mi>x</mi><mo>+</mo><mi>c</mi></mrow></math> to find the position.

A block formula is specified by wrapping a single math element whose display attribute is "block" in a div element whose class is formula and whose id attribute starts with eq-. Block formulae are numbered and should be referenced: see, for example, Formula (1).

<div class="formula" id="eq-1">
<math display="block"><mrow><mi>y</mi><mo>=</mo><mi>a</mi><msup><mi>x</mi><mn>2</mn></msup><mo>+</mo>
<mi>b</mi><mi>x</mi><mo>+</mo><mi>c</mi></mrow></math>
</div>

NOTE —⁠ Tools such as https://temml.org/ can be used to convert from Latex to MathML.

The unicode minus sign (−) is used in math expressions instead of the hyphen-minus, e.g. −42 renders as −42, and 6x − 103y renders as 6x − 103y.

7.4.17 Special Characters🔗

Characters should be encoded as UTF-8-encoded Unicode codepoints, e.g. あ, instead of HTML entities, e.g. あ, except as needed for usage in pre or examples.

The characters listed in Table 5 are an exception to this guidance. They are commonly inserted by word processors (e.g. curly quotes substituted for straight quotes, en/em dashes substituted for hyphens) and shall not appear as literal codepoints in the document source. When one of these characters is genuinely needed, it shall be written as a unicode character reference (e.g. “) so that author intent is explicit.

NOTE —⁠ The validator reports each literal occurrence with line and column information. Numeric unicode, or named character references (e.g. “, “) are recognized as deliberate and are not flagged.

7.4.18 Inline code fragments🔗

Inline code fragments should be wrapped in a code element. A code fragment is text that is intended to be used verbatim in computer code, including command line code, including:

• script names (i.e. smpte.js)
• element names (i.e. head)
• namespaces (i.e. http://www.smpte-ra.org/schemas/428-7/2014/DCST)
• short code snippets, e.g. <meta charset="utf-8" /> or int i = 3;
• literal values, e.g., true or 00:00:04:ZeroE
• regular expressions or match pattern, e.g., YYYY-MM-DD

NOTE —⁠ Namespaces are wrapped with a code element and not with an a element since they do not necessarily resolve to a resource.

This is an <code>element</code> that is rendered with the <code>code</code> HTML element. 

7.4.19 Using class attributes🔗

In addition to the restriction of using internal or external defined stylesheet and style elements as per 7.2.15, editors shall not use style attributes within html elements for styling. Instead, the styling may be modified using class values where applicable as listed below.

annex

Used on a section element to designate the clause as an annex. See 7.3.9.

note

Applied to p, div, or dd elements to create a formatted and automatically numbered note. See 7.4.13.

example

Applied to p or div elements to create a formatted and automatically numbered example. See 7.4.14.

footnote

Applied to a p element inside a tfoot element to create a table footnote. Footnotes are only permitted inside a tfoot element - use outside of tables is not allowed. See 7.4.10.

center-cell;

right-cell;

left-cell;

top-cell

Applied to a td element to override the alignment of that individual table cell. See A.1.3.

text-nowrap

Applied to an element to prevent line wrapping of its contents. This is commonly used on th or td elements to keep short identifiers, tags, or codes on a single line. See Clause A.5

col-1-nowrap through col-8-nowrap

Applied to a table element to prevent line wrapping within the specified column. See Clause A.6

col-xsmall;

col-small;

col-medium;

col-wide

Applied to th or td elements to suggest a relative column width for that cell. These classes provide extra-narrow, narrow, medium, or wide column layouts without using inline style attributes. See Clause A.5

col-1-xsmall through col-8-xsmall;

col-1-small through col-8-small;

col-1-medium through col-8-medium;

col-1-wide through col-8-wide

Applied to a table element to suggest relative widths for specific columns. See Clause A.6

col-1-center through col-8-center;

col-1-right through col-8-right;

col-1-left through col-8-left;

col-1-top through col-8-top

Applied to a table element to override the alignment of the specified column. Multiple classes may be combined to align multiple columns. See A.1.2.

list-none

Applied to a ul element to remove bullet markers. See Clause B.4.

formula

Applied to a div element that contains a block math element to format and number displayed formulae. See 7.4.16

text-right

Applied to an element to right-align its text content.

text-left

Applied to an element to left-align its text content.

syntax

Applied to a td or th element in a syntax listing table to render its contents in a monospace font at a reduced size.

NOTE 1 —⁠ All other elements are automatically styled by the default SMPTE defined CSS values, such as "code" and may not be altered.

NOTE 2 —⁠ Tables are automatically formatted for best view on a variety of screen sizes and formats.

8.1.1 Overview🔗

The SMPTE HTML publication tooling consists of several components:

• Rendering code (smpte.js) that renders the author-supplied HTML document into a publication-ready HTML document. The rendering involves numbering clauses, inserting boilerplate, etc., and takes place directly in the web browser used by the author.
• Building code (scripts/build.mjs) that automates the process of validating, rendering, generating redlines and uploading publication artifacts to Amazon S3.
• A GitHub workflow (.github/workflows/main.yml and workflows/action.yml) that automatically executes the building code whenever a change is made to the GitHub repository where the document is tracked.
• Amazon AWS infrastructure where the publication artifacts are deployed.

8.1.2 Rendering🔗

At the heart of the tooling is the rendering code at smpte.js.

The rendering code runs in browser and is imported using a script element (see 7.2).

8.1.3 Building🔗

Building the document for publication involves the following steps:

1. Validating the document
2. Rendering the document
3. Creating redlines from the rendered document
4. Uploading the rendered document and corresponding redlines to S3

The build process carried by the build script scripts/build.mjs is usually executed by the GitHub workflow (see 8.1.4). The script has the following dependencies:

• node dependencies specified in ./package.json
• HTML 5 validator available as a Python package using pip install html5validator

The build process looks for the following environment variables:

• AWS_S3_REGION
• AWS_S3_BUCKET
• AWS_S3_KEY_PREFIX
• CANONICAL_LINK_PREFIX

The build process also expects the AWS environment to be set up to allow access to the bucket.

The S3 upload step can be skipped by providing the validate argument to the build script.

The build process can be configured using the .smpte-build.json file which is contains a JSON object that conforms to the JSON schema at Figure 3.

{
  "title": "Build configuration",
  "description": "Schema for the SMPTE HTML publication tooling build configuration file",
  "type": "object",
  "properties": {
    "latestEditionTag": {
      "description": "Git commit or tag used when generating redlines against the latest edition of the document",
      "type": [ "string", "null" ]
    }
  }
}

If present or not equal to null, the latestEditionTag property contains the Git tag or commit that is used when generating a redline against the latest published edition of the document.

{
  "latestEditionTag": "20260319-pub"
}

For further explanation of determining the value of latestEditionTag, see Clause C.2

8.1.4 GitHub integration🔗

To automatically create and upload to S3 the clean and redline copies of the document when commits are pushed to GitHub, the workflow file at Figure 4 is stored at .github/workflows/main.yml in the repository.

name: Build SMPTE document

on:
  push:
  pull_request:
  release:
    types: [published]

env:
  AWS_REGION: us-east-1
  AWS_S3_BUCKET: html-doc-pub
  AWS_ROLE: arn:aws:iam::189079736792:role/gh-actions-html-pub
  CANONICAL_LINK_PREFIX: https://doc.smpte-doc.org/

jobs:
  build:
    runs-on: ubuntu-latest
    if: >
      github.repository_owner	== 'SMPTE' && (
      (github.event_name == 'push' && github.ref == 'refs/heads/main')
      || github.event_name == 'pull_request'
      || github.event_name == 'release'
      )
    # These permissions are needed to interact with GitHub's OIDC Token endpoint.
    permissions:
      id-token: write
      contents: write
      pull-requests: write

    steps:

      - name: Checkout repo
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
          submodules: true

      - name: Set repository name
        run: echo "REPOSITORY_NAME=${GITHUB_REPOSITORY#*/}" >> $GITHUB_ENV

      - name: Check out all branches with the exception of the current branch
        run: CUR_BRANCH=$(git rev-parse --abbrev-ref HEAD); for i in `git branch -a | grep remote | grep -v "remotes/pull" | grep -v HEAD | grep -v ${CUR_BRANCH}`; do git branch --track ${i#remotes/origin/} $i; done

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v1-node16
        with:
          role-to-assume: ${{ env.AWS_ROLE }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Build and deploy document (local)
        uses: ./tooling/workflows
        if: github.repository != 'SMPTE/html-pub'
        with:
          AWS_S3_REGION: ${{env.AWS_REGION}}
          AWS_S3_BUCKET: 	${{env.AWS_S3_BUCKET}}
          AWS_S3_KEY_PREFIX: "${{env.REPOSITORY_NAME}}/"
          CANONICAL_LINK_PREFIX: ${{env.CANONICAL_LINK_PREFIX}}
          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

      - name: Build and deploy document (HTML Pub repo)
        uses: ./workflows
        if: github.repository == 'SMPTE/html-pub'
        with:
          AWS_S3_REGION: ${{env.AWS_REGION}}
          AWS_S3_BUCKET: 	${{env.AWS_S3_BUCKET}}
          AWS_S3_KEY_PREFIX: "${{env.REPOSITORY_NAME}}/"
          CANONICAL_LINK_PREFIX: ${{env.CANONICAL_LINK_PREFIX}}
          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

      - name: Notify template repo to update submodule
        if: github.event_name == 'release' && github.repository == 'SMPTE/html-pub'
        env:
          GH_TOKEN: ${{ secrets.TEMPLATE_REPO_PAT }}
          TAG_NAME: ${{ github.event.release.tag_name }}
        run: |
          gh api repos/SMPTE/html-pub-template/dispatches \
            --method POST \
            --field event_type=tooling-release \
            --field "client_payload[tag]=${TAG_NAME}" \
            --field "client_payload[sha]=${GITHUB_SHA}"

The workflow file defines the following environment variables:

AWS_S3_REGION

Used to set AWS_S3_REGION.

AWS_S3_BUCKET

Used to set AWS_S3_BUCKET.

CANONICAL_LINK_PREFIX

If set, used to generate the links to publication artifacts that are referenced from the GitHub pull request.

AWS_ROLE

ARN of the AWS role used by the workflow to upload files to S3 (see 8.1.5).

When the workflow is executed on a GitHub pull request, a comment that contains links to the clean and redline documents is automatically added to the pull request. The links use one of the following prefixes:

• CANONICAL_LINK_PREFIX/AWS_S3_KEY_PREFIX, if CANONICAL_LINK_PREFIX is set;
• http://AWS_S3_BUCKET.s3-website-AWS_S3_REGION.amazonaws.com/AWS_S3_KEY_PREFIX, otherwise.

The workflow file automatically sets AWS_S3_KEY_PREFIX to the name of the repository.

8.1.5 Amazon AWS integration🔗

The tooling uploads publication artifacts to an S3 bucket according to the following parameters:

AWS_S3_REGION

Region where the S3 bucket lives, e.g., us-west-1

AWS_S3_BUCKET

Name of the S3 bucket, e.g., html-doc-pub

AWS_S3_KEY_PREFIX

Prefix used when creating the S3 key where the document is stored, e.g., draft/ag05/

An OIDC role grants the tooling permissions to upload objects to the bucket. This avoids maintaining IAM users and storing GitHub secrets.

The trust policy for the role associated with one GitHub repository is specified at Figure 5.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::189079736792:oidc-provider/token.actions.githubusercontent.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
                },
                "StringLike": {
                    "token.actions.githubusercontent.com:sub": "repo:SMPTE/*"
                }
            }
        }
    ]
}

The permissions for the role associated with one GitHub repository is specified at Figure 6.

{
  "Version": "2012-10-17",
  "Statement": [
      {
          "Effect": "Allow",
          "Action": "s3:PutObject",
          "Resource": "arn:aws:s3:::<name of bucket>/*"
      }
  ]
}

The bucket is made public using the policy at Figure 7.

{
  "Version": "2008-10-17",
  "Statement": [
      {
          "Effect": "Allow",
          "Principal": "*",
          "Action": "s3:GetObject",
          "Resource": "arn:aws:s3:::<name of bucket>/*"
      }
  ]
}

The contents of the bucket are also made available through a Cloudfront distribution, which allows the publication artifacts to be made available through a custom domain name and TLS (currently https://doc.smpte-doc.org/).

8.1.6 Git commit hooks🔗

It is advisable to install the git commit hook listed at Figure 8. It detects errors before a document can be committed.

#!/bin/sh
if test -f "tooling/scripts/validate.mjs"; then
  validate=./tooling/scripts/validate.mjs
else
  validate=./scripts/validate.mjs
fi

node $validate ./doc/main.html

8.2.1 Overview🔗

Many of the features and automatic formatting available in the tooling is present and available when working locally. This allows an editor to create and edit a valid HTML document before pushing to a repo and encountering an error.

It is recommended to utilize VS Code (https://code.visualstudio.com/) as your local HTML editor, using the Live Preview extension (https://marketplace.visualstudio.com/items?itemName=ms-vscode.live-server), which shows some validation in real-time for an editor.

Other useful extension(s) for VS Code are:

• Git Graph (visual aid) - https://marketplace.visualstudio.com/items?itemName=mhutchie.git-graph

8.2.2 Installation and prerequisites🔗

To use the full features locally either on command line, or in termimal (also available inside of VS Code), an editor will need to have the following installed locally:

• Node.js - https://nodejs.org/en/download
• Python - https://www.python.org/downloads/
• PIP - https://pip.pypa.io/en/stable/installation/

Once installed, it is recommended to keep up to date with the latest versions.

8.2.3 Repo setup🔗

Assuming the prerequisites listed in 8.2.2 are already installed, each time a new repo is cloned and work is to be started, the repo will need to be configured for its dependencies, based on the current ./package.json file.

The command for this is:

npm install

NOTE —⁠ This command will update ./package-lock.json, and can be run again if changes are made to ./package.json for editing and/or updating dependencies based on the repo.

Once npm/Node is set up, it is also recommended to set up the requirements and further dependencies for validation to run properly.

The command for this is:

npm run prevalidate

This will check and (if needed) install the HTML 5 validator as noted in 8.1.3. If the HTML 5 validator has already been installed, or the command has been run before (on another repo), the prompt will return:

html5validator found. HTML validation ready.

8.2.4 Updating the tooling submodule🔗

Document repositories include the tooling (./tooling/) as a git submodule. When the tooling is updated, each document repo must be manually bumped to point to the new tooling commit. It is important to keep the submodule as up to date as possible, as updates may include bug fixes, validation improvements, and formatting changes that affect document output.

NOTE 1 —⁠ Individual changes to files within the ./tooling/ submodule directory are not permitted. All tooling changes must be made through the https://github.com/SMPTE/html-pub repository and picked up via a submodule bump.

To check which commit the submodule is currently pinned to and whether it is behind the remote, run:

git submodule status

The output lists each submodule with its current commit SHA. To determine whether the submodule is current, compare the commit SHA against the latest release tag and commit at https://github.com/SMPTE/html-pub.

To update the submodule to the latest commit on its tracked remote branch, run:

git submodule update --remote

NOTE 2 —⁠ This command fetches from the submodule's remote and advances the pointer in the superproject to the latest available commit on the tracked branch. It does not automatically stage or commit the change in the parent repo.

After updating, the parent repository will show the submodule directory as modified. Stage and commit the bump with:

git add tooling/
git commit -m "Bump tooling to latest"

Push the change to the remote as normal:

git push

8.2.5 Validation🔗

When creating a PR on GitHub, the tooling automatically performs a build process as noted in 8.1.3, and part of that process is doing validation, both the internal to the tooling and for general HTML 5 validation.

While the internal tooling validation occurs at runtime while editing, waiting until the build action during a PR to check the HTML 5 validation can present an editor with unforseen issues (i.e. an invalid element or broken schema error), which then results in failures on the PR/build that must be fixed. Often times when this occurs the preview with redlines is not available in the PR, and/or the tooling will not allow a build to finish. Therefore it is highly recommended an editor runs the validation locally prior to pushing to GitHub to prevent these failures frmo occuring.

The command for this is:

npm run validate

NOTE —⁠ This command reports back errors in (2) seperate sections that are required to be resolved before a build can complete. The HTML validation includes line numbers for the convenience of the editor.

> smpte-html-pub-tooling@2.1.0 prevalidate
> node scripts/ensure-html5validator.mjs

html5validator found. HTML validation ready.

> smpte-html-pub-tooling@2.1.0 validate
> run-p validate:doc validate:html

> smpte-html-pub-tooling@2.1.0 validate:html
> html5validator --errors-only ./doc/main.html

> smpte-html-pub-tooling@2.1.0 validate:doc
> node ./scripts/validate.mjs ./doc/main.html

Unknown element in clause HTMLElement {
  [Symbol(SameObject caches)]: [Object: null prototype] { children: HTMLCollection {} }
}
".../SMPTE/html-pub/./doc/main.html":1512.7-1512.10: error: No "p" element in scope but a "p" end tag seen.
".../SMPTE/html-pub/./doc/main.html":1524.7-1524.10: error: No "p" element in scope but a "p" end tag seen.
".../SMPTE/html-pub/./doc/main.html":1554.21-1555.7: error: Saw "<" when expecting an attribute name. Probable cause: Missing ">" immediately before.
".../SMPTE/html-pub/./doc/main.html":1554.21-1555.9: error: End tag had attributes.
".../SMPTE/html-pub/./doc/main.html":1555.242-1555.245: error: No "p" element in scope but a "p" end tag seen.
ERROR: "validate:html" exited with 5.

8.2.6 Handling new validation errors after a tooling bump🔗

A tooling update may introduce new or stricter validation rules. After bumping the submodule, run validation locally as described in 8.2.5 before committing or pushing.

If validation reports new errors that were not present before the bump, those errors must be resolved in the document source before the bump commit is pushed. Do not push a submodule bump that causes a document to fail validation.

NOTE —⁠ Validation errors introduced by a tooling update reflect real issues in the document source. They should be corrected in the document, not worked around by reverting or pinning to an older tooling commit.