SMPTE AG 26
Administrative Guideline

HTML Pub β€” Tooling and documentation for HTML documents

Draft - Mon Dec 01 2025 18:30:28 GMT+0000 (Coordinated Universal Time)

Copyright Β© 2025, Society of Motion Picture and Television Engineers. All rights reserved. No part of this material may be reproduced, by any means whatsoever, without the prior written permission of the Society of Motion Picture and Television Engineers.

Warning: This document is an unpublished work under development and shall not be referred to as a SMPTE Standard, Recommended Practice, or Engineering Guideline. It is distributed for review and comment; distribution does not constitute publication. Recipients of this document are strongly encouraged to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

Table of contentsπŸ”—

  1. Foreword
  2. Introduction
  3. 1 Scope
  4. 2 Conformance
  5. 3 Normative references
  6. 4 Terms and definitions
  7. 5 Quick start
  8. 6 Directory layout
  9. 7 Main element
    1. 7.1 General
    2. 7.2 head element
      1. 7.2.1 General
      2. 7.2.2 pubType
      3. 7.2.3 pubNumber
      4. 7.2.4 pubPart
      5. 7.2.5 pubSuiteTitle
      6. 7.2.6 pubVersion
      7. 7.2.7 pubState
      8. 7.2.8 pubStage
      9. 7.2.9 pubRevisionOf
      10. 7.2.10 pubTC
      11. 7.2.11 pubConfidential
      12. 7.2.12 pubDateTime
      13. 7.2.13 effectiveDateTime
      14. 7.2.14 Additional script elements
    3. 7.3 body element
      1. 7.3.1 Overall structure
      2. 7.3.2 Foreword section
        1. 7.3.2.1 General
        2. 7.3.2.2 RDD
      3. 7.3.3 Introduction section
      4. 7.3.4 Scope section
      5. 7.3.5 Conformance section
      6. 7.3.6 Normative references section
      7. 7.3.7 Terms and definitions section
      8. 7.3.8 Prose section(s)
      9. 7.3.9 Annex section(s)
      10. 7.3.10 Additional elements section
      11. 7.3.11 Bibliography section
    4. 7.4 Other elements
      1. 7.4.1 Referencing clauses
      2. 7.4.2 Citing normative references
      3. 7.4.3 Citing non-prose elements
      4. 7.4.4 Citing bibliographic references
      5. 7.4.5 External links
      6. 7.4.6 Inline terms
      7. 7.4.7 Lists of key-value pairs
      8. 7.4.8 Lists
      9. 7.4.9 Figures
      10. 7.4.10 Tables
      11. 7.4.11 External code snippets
      12. 7.4.12 Internal code snippets
      13. 7.4.13 Notes
      14. 7.4.14 Examples
      15. 7.4.15 Quotes and blockquotes
      16. 7.4.16 Formulae
      17. 7.4.17 Special Characters
      18. 7.4.18 Inline code fragments
  10. 8 Tooling
    1. 8.1 Overview
    2. 8.2 Rendering
    3. 8.3 Building
    4. 8.4 GitHub integration
    5. 8.5 Amazon AWS integration
    6. 8.6 Git commit hooks
  11. Annex A Table Examples (Informative)
    1. A.1 Alignment
      1. A.1.1 Default Alignment
      2. A.1.2 Column Alignment
      3. A.1.3 Cell Alignment
    2. A.2 Multiple Headers
    3. A.3 Cell Spanning
      1. A.3.1 colspan
      2. A.3.2 rowspan
    4. A.4 Complex Example
  12. Annex B List Examples (Informative)
    1. B.1 Customizing Ordered Lists
      1. B.1.1 General
      2. B.1.2 List type Examples
    2. B.2 List Nesting
    3. B.3 Complex List Example
  13. Annex C Document Status Workflow (Normative)
    1. C.1 Mapping pubState and pubStage to Document Status
    2. C.2 GitHub Releases
    3. C.3 Pull Request Guidelines
    4. C.4 Sample Workflow
  14. Additional elements
  15. Bibliography

ForewordπŸ”—

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.

For more information, please visit www.smpte.org.

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.

IntroductionπŸ”—

Authoring SMPTE documents consist of two aspects:

1 ScopeπŸ”—

This Administrative Guideline describes the process for authoring SMPTE documents using HTML.

2 ConformanceπŸ”—

The following keywords have a specific meaning in the context of this document:

3 Normative referencesπŸ”—

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

4 Terms and definitionsπŸ”—

No terms and definitions are listed in this document.

5 Quick startπŸ”—

  1. Install the git source control system
  2. Install a text editor and local web server. Visual Studio Code (https://code.visualstudio.com/) combined with the ms-vscode.live-server extension (https://marketplace.visualstudio.com/items?itemName=ms-vscode.live-server) is one option.
  3. Clone the HTML publication template: 
    git clone --recurse-submodules https://github.com/SMPTE/html-pub-template.git
  4. (Advanced) Add the pre-commit hook specified at 8.6 by following the instructions at https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks.
  5. If working on a project that has a repository, update the origin remote to that repository: 
    git remote set-url origin <HTTPS URL of the project repository found on GitHub>
    For example: 
    git remote set-url origin https://github.com/SMPTE/stxxx-y-private.git
  6. Start editing the main prose element at doc/main.html.

6 Directory layoutπŸ”—

A document consists of multiple files arranged in the following directory structure:

7 Main elementπŸ”—

7.1 GeneralπŸ”—

The main element shall be an HTML document represented using the XML syntax, as specified at HTML Standard.

The basic structure of the main element is illustrated at Figure 1.

<!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="../tooling/smpte.js"></script>
    <meta itemprop="pubType" content="AG" />
    <meta itemprop="pubNumber" content="XX" />
    <!-- <meta itemprop="pubPart" content="99" /> -->
    <!-- <meta itemprop="pubSuiteTitle" content="Suite title" /> -->
    <meta itemprop="pubState" content="draft" />
    <meta itemprop="pubDateTime" content="20XX-XX-XX" />
    <!-- <meta itemprop="pubStage" content="WD" /> -->
    <!-- <meta itemprop="pubTC" content="27C" /> -->
    <!-- <meta itemprop="pubConfidential" content="no" /> -->
    <!-- <meta itemprop="pubRevisionOf" content="SMPTE ST XXXX-Y:ZZZZ" /> -->
    <title>Title of the document</title>
  </head>
  <body>
    <section id="sec-scope">
      <p>This is the scope of the document.<p>
    </section>
  </body>
</html>
Figure 1 β€” Basic structure of the main element.

The smpte.js script contains the code that renders the HTML document provided by the author into an HTML document appropriate for publication. This rendering happens automatically when loading the document in a web browser.

7.2 head elementπŸ”—

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 1 —⁠ 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.

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

EXAMPLE 2 —⁠ 
<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.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πŸ”—

7.3 body elementπŸ”—

7.3.1 Overall structureπŸ”—

The body element shall consist of an ordered sequence of section elements, as specified at Table 1.

Table 1 β€” Ordered sequence of section elements comprising the body element.
Section Name Cardinality
Foreword 0 or 1
Introduction 0 or 1
Scope Exactly 1
Conformance 0 or 1
Normative references 0 or 1
Terms and definitions 0 or 1
Prose section 0 or more
Annex section 0 or more
Additional elements section 0 or 1
Bibliography 0 or 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 other than Prose sections and Annex sections are automatically generated;
  • boilerplate is added, including the SMPTE masthead.

7.3.2 Foreword sectionπŸ”—

7.3.2.1 GeneralπŸ”—

The Foreword section contains author-supplied prose, e.g. list of substantive changes since the last edition, that is added to the SMPTE boilerplate text.

The absence of this section indicates that no author-supplied prose was provided.

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

The heading shall not be present.

EXAMPLE —⁠ 
<section id="sec-foreword">
  <p>This is the additional information relevant to the document.</p>
</section>
7.3.2.2 RDDπŸ”—

When pubType is set to RDD, the Foreword section shall be present and there there shall be a single dl, after any author-supplied prose if supplied, which contains contact information about the proponent(s) of the RDD document.

The id attribute shall be present on the dl element and equal to rdd-proponent.

If present, the dl element shall use a single dt element for each company name designated as a Proponent of the document, and multiple lines of dd 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.

EXAMPLE —⁠ 
<section id="sec-foreword">
  <p>This is the additional information relevant to the document.</p>
  <dl id="rdd-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.

EXAMPLE —⁠ 
<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.

EXAMPLE —⁠ 
<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.

EXAMPLE —⁠ 
<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.

EXAMPLE —⁠ 
<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 first dd element immediately following the last dt element, if present, shall be a definition.
    • The next dd 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.
    • The remaining dd elements, if present, shall have a class attribute that contains the value note, in which case the elements are notes to the entry.
EXAMPLE —⁠ 
<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>number that is printed with ink or exposed onto the film at the time of
    manufacture at regular intervals, typically one foot.</dd>
    <dd><a href="#bib-key-number-spec"></a></dd>
    <dd class="note">Key number shall not be confused with key frame.</dd>
  </dl>
</section>

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

7.3.8 Prose section(s)πŸ”—

Each Prose section contains author-supplied technical prose.

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

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 sections that are children of the body element.

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

EXAMPLE —⁠ 
<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 sections.

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.

EXAMPLE —⁠ 
<section class="annex informative" id="sec-addtional-info">
  <h2>Additional Info</h2>
  <section id="sec-additional-info-sub-section">
    <h3>Additional Info Sub Section</h3>
    <p>Some technical content</p>
  </section>
  <section id="sec-additional-info-sub-section-more">
    <h3>Additional Info Sub Section 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 the section 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.

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

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.

EXAMPLE —⁠ 
<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 Other elementsπŸ”—

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 section number.

EXAMPLE —⁠ <a href="#sec-scope"></a> is rendered as Clause 1 and <a href="#sec-section-linking"></a> is rendered as 7.4.1

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.

EXAMPLE —⁠ <a href="#element-sample-text"></a> is rendered as Element a.

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

EXAMPLE 2 —⁠

The definition above can be referenced using one of the following forms:

  • <a>term</a>, which is rendered as term
  • <a>alternate1</a>, which is rendered as alternate1
  • <a>alternate2</a>, which is rendered as alternate2

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.

EXAMPLE —⁠ 
<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>

is rendered as:

imperative forms
"see"
non-imperative forms
"according to"
"as defined in"
"as specified in"
"details as given in"
"in accordance with"

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.
EXAMPLE —⁠ 
<ol>
  <li>First list item</li>
  <li>Second list item</li>
</ol>

is rendered as:

  1. First list item
  2. Second list item

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 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.png">
  <figcaption>Example of a figure</figcaption>
</figure>

is rendered as

Figure 2 β€” Example of a figure

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.

EXAMPLE 2 —⁠ <a href="#figure-sample-image"></a> is rendered as Figure 2.

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 —⁠ 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.

EXAMPLE 1 —⁠ 
<table id="tab-sample-tabledata">
  <caption>Sample Table</caption>
  <thead>
    <tr>
      <th style="width: 30%">Sample Number</th>
      <th style="width: 70%">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>

is rendered as

Table 2 β€” Sample Table
Sample Number Sample Name
0001 Name 01
0002 Name 02

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.

EXAMPLE 2 —⁠ <a href="#tab-sample-tabledata"></a> is rendered as Table 2.

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

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.

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

is rendered as

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.

EXAMPLE —⁠ 
<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.

EXAMPLE 1 —⁠ 
<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>

is rendered as

NOTE —⁠ The license portion of Annex A is verbatim the BSD-3-Clause license available at https://spdx.org/licenses/BSD-3-Clause.html.

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

EXAMPLE 2 —⁠ <a href="#note-example-ref"></a> results in 7.4.13, Note.

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.

EXAMPLE 1 —⁠ 
<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>

results in:

EXAMPLE 2 —⁠ The number 0.0003 can be written 3Γ—10βˆ’4 but is never written 3eβˆ’4.

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

EXAMPLE 3 —⁠ <a href="#ex-example-ref"></a> results in 7.4.14, Example 2.

7.4.15 Quotes and blockquotesπŸ”—

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

EXAMPLE 1 —⁠ 
<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>

results in:

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.
EXAMPLE 2 —⁠ 
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>

results in:

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

7.4.16 FormulaeπŸ”—

Formulae are specified using the HTML math element.

Unless specified otherwise, a formula is inline.

EXAMPLE 1 —⁠ 
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.

results in:

One needs to evaluate y=ax2+ bx+c 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).

EXAMPLE 2 —⁠ 
<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>

results in:

y=ax2+ bx+c (1)

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

7.4.17 Special CharactersπŸ”—

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

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.

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

results in:

This is an element that is rendered with the code HTML element.

8 ToolingπŸ”—

8.1 OverviewπŸ”—

The SMPTE HTML publication tooling consists of several components:

8.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.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 is carried by the build script scripts/build.mjs, which is usually executed by the GitHub workflow (see 8.4). The script has the following dependencies:

The build process looks for the following environment variables:

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" ]
    }
  }
}
Figure 3 β€” Schema for the build configuration file .smpte-build.json.

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.

EXAMPLE —⁠ 
{
  "latestEditionTag": "v1.0.0"
}

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

8.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}}
Figure 4 β€” GitHub workflow file.

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.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:

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

8.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/
EXAMPLE —⁠

Given AWS_S3_BUCKET=html-doc-pub and AWS_S3_KEY_PREFIX=ag-05/, the tooling uploads publication artifacts under the prefix s3://html-doc-pub/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/*"
                }
            }
        }
    ]
}
Figure 5 β€” Trust policy for the OIDC role.

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>/*"
      }
  ]
}
Figure 6 β€” Permissions granted to the role associated with each GitHub repository, where <name of bucket> is replaced by AWS_S3_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>/*"
      }
  ]
}
Figure 7 β€” Public bucket policy where <name of bucket> is replaced by AWS_S3_BUCKET

The contents of the bucket is 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.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
Figure 8 β€” Pre-commit hook that validates the main element.

Annex A
Table Examples (Informative)πŸ”—

A.1 AlignmentπŸ”—

A.1.1 Default AlignmentπŸ”—

By default, table headers within thead are set to text-align: center;, and cells within the body tbody are set to text-align: left;, as the below example shows. 

<table id="tab-sample-tabledata-defaultalign">
  <caption>Default Alignment Table Sample</caption>
  <thead>
    <tr>
      <th>Sample Number</th>
      <th>Sample Name</th>
      <th>Sample Code</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>0001</td>
      <td>Name 01</td>
      <td><code>Code 1</code></td>
    </tr>
    <tr>
      <td>0002</td>
      <td>Name 02</td>
      <td><code>Code 2</code></td>
    </tr>
    <tr>
      <td>0003</td>
      <td>Name 03</td>
      <td><code>Code 3</code></td>
    </tr>
  </tbody>
</table>

is rendered as

Table A.1 β€” Default Alignment Table Sample
Sample Number Sample Name Sample Code
0001 Name 01 Code 1
0002 Name 02 Code 2
0003 Name 03 Code 3

A.1.2 Column AlignmentπŸ”—

To change the alignment of an entire column, a class such as col-3-center may be added to the table denoting which column to center align, as the below example shows. 

<table id="tab-sample-tabledata-colcenter" class="col-3-center">
  <caption><code>col-x-center</code> Table Sample</caption>
  <thead>
    <tr>
      <th>Sample Number</th>
      <th>Sample Name</th>
      <th>Sample Code</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>0001</td>
      <td>Name 01</td>
      <td><code>Code 1</code></td>
    </tr>
    <tr>
      <td>0002</td>
      <td>Name 02</td>
      <td><code>Code 2</code></td>
    </tr>
    <tr>
      <td>0003</td>
      <td>Name 03</td>
      <td><code>Code 3</code></td>
    </tr>
  </tbody>
</table>

is rendered as

Table A.2 β€” col-x-center Table Sample
Sample Number Sample Name Sample Code
0001 Name 01 Code 1
0002 Name 02 Code 2
0003 Name 03 Code 3

NOTE 1 —⁠ Classes are available to center align columns 1-8 (as col-x-center), and multiple classes to table may be added to align more columns as needed.

NOTE 2 —⁠ Tables over 8 columns wide should not be used and instead split into multiple smaller tables.

A.1.3 Cell AlignmentπŸ”—

To change the alignment of a individual cell, the class center-cell may be added to each td as needed, as the below example shows. 

<table id="tab-sample-tabledata-centercell">
  <caption><code>center-cell</code> Table Sample</caption>
  <thead>
    <tr>
      <th>Sample Number</th>
      <th>Sample Name</th>
      <th>Sample Code</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>0001</td>
      <td>Name 01</td>
      <td><code>Code 1</code></td>
    </tr>
    <tr>
      <td class="center-cell">centered 0002</td>
      <td>Name 02</td>
      <td><code>Code 2</code></td>
    </tr>
    <tr>
      <td>0003</td>
      <td>Name 03</td>
      <td><code>Code 3</code></td>
    </tr>
  </tbody>
</table>

is rendered as

Table A.3 β€” center-cell Table Sample
Sample Number Sample Name Sample Code
0001 Name 01 Code 1
centered 0002 Name 02 Code 2
0003 Name 03 Code 3

NOTE —⁠ The center-cell class may be added to as many td as needed.

Vertical cell alignment is not available at this time, and the default is set to top.

A.2 Multiple HeadersπŸ”—

To insert additional header(s), use th in place of td within the tr of tbody that will contain the additional header, as the below example shows.

EXAMPLE —⁠ 
<table id="tab-sample-tabledata-multiheader">
  <caption>Multiple Header Table Sample</caption>
  <thead>
    <tr>
      <th>Sample Number</th>
      <th>Sample Name</th>
      <th>Sample Code</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>0001</td>
      <td>Name 01</td>
      <td><code>Code 1</code></td>
    </tr>
    <tr>
      <td>0002</td>
      <td>Name 02</td>
      <td><code>Code 2</code></td>
    </tr>
    <tr>
      <th>Sample Number 2</th>
      <th>Sample Name 2</th>
      <th>Sample Code 2</th>
    </tr>
    <tr>
      <td>0003</td>
      <td>Name 03</td>
      <td><code>Code 3</code></td>
    </tr>
  </tbody>
</table>

is rendered as

Table A.4 β€” Multiple Header Table Sample
Sample Number Sample Name Sample Code
0001 Name 01 Code 1
0002 Name 02 Code 2
Sample Number 2 Sample Name 2 Sample Code 2
0003 Name 03 Code 3

A.3 Cell SpanningπŸ”—

A.3.1 colspanπŸ”—

colspan is supported as needed, as the below example shows. 

<table id="tab-sample-tabledata-colspan">
  <caption><code>colspan</code> Table Sample</caption>
  <thead>
    <tr>
      <th>Sample Number</th>
      <th>Sample Name</th>
      <th>Sample Code</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>0001</td>
      <td>Name 01</td>
      <td><code>Code 1</code></td>
    </tr>
    <tr>
      <td>0002</td>
      <td>Name 02</td>
      <td><code>Code 2</code></td>
    </tr>
    <tr>
      <td colspan="3">next section</td>
    </tr>
    <tr>
      <td>0003</td>
      <td>Name 03</td>
      <td><code>Code 3</code></td>
    </tr>
  </tbody>
</table>

is rendered as

Table A.5 β€” colspan Table Sample
Sample Number Sample Name Sample Code
0001 Name 01 Code 1
0002 Name 02 Code 2
next section
0003 Name 03 Code 3

NOTE —⁠ See https://html.com/tables/rowspan-colspan/ for additional information.

A.3.2 rowspanπŸ”—

rowspan is supported as needed, as the below example shows. 

<table id="tab-sample-tabledata-rowspan">
  <caption><code>rowspan</code> Table Sample</caption>
  <thead>
    <tr>
      <th>Sample Number</th>
      <th>Sample Name</th>
      <th>Sample Code</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td rowspan="2">0001</td>
      <td>Name 01</td>
      <td><code>Code 1</code></td>
    </tr>
    <tr>
      <td>Name 02</td>
      <td><code>Code 2</code></td>
    </tr>
    <tr>
      <td>0002</td>
      <td>Name 03</td>
      <td><code>Code 3</code></td>
    </tr>
  </tbody>
</table>

is rendered as

Table A.6 β€” rowspan Table Sample
Sample Number Sample Name Sample Code
0001 Name 01 Code 1
Name 02 Code 2
0002 Name 03 Code 3

NOTE —⁠ See https://html.com/tables/rowspan-colspan/ for additional information.

A.4 Complex ExampleπŸ”—

All the various options above are available to be combined as needed to create complex tables, as the below example shows. 

<table id="tab-sample-tabledata-complex" class="col-3-center col-4-center">
  <caption>Complex Table Sample</caption>
  <thead>
    <tr>
      <th>Sample Number</th>
      <th>Sample Name</th>
      <th>Sample Code</th>
      <th>Sample Data</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td rowspan="2">0001</td>
      <td>Name 01</td>
      <td><code>Code 1</code></td>
      <td>Data 01</td>
    </tr>
    <tr>
      <td>Name 02</td>
      <td class="center-cell"><code>Code 2</code></td>
      <td>Data 01</td>
    </tr>
    <tr>
      <td>0003</td>
      <td>Name 03</td>
      <td><code>Code 3</code></td>
      <td>Data 01</td>
    </tr>
    <tr>
      <th>Sample Number 2</th>
      <th>Sample Name 2</th>
      <th>Sample Code 2</th>
      <th>Sample Data 2</th>
    </tr>
    <tr>
      <td>0004</td>
      <td>Name 04</td>
      <td><code>Code 5</code></td>
      <td>Data 05</td>
    </tr>
    <tr>
      <td colspan="3" class="center-cell">section of data</td>
      <td class="center-cell">Data 05.5</td>
    </tr>
    <tr>
      <td>0005</td>
      <td>Name 05</td>
      <td><code>Code 5</code></td>
      <td>Data 06</td>
    </tr>
  </tbody>
</table>

is rendered as

Table A.7 β€” Complex Table Sample
Sample Number Sample Name Sample Code Sample Data
0001 Name 01 Code 1 Data 01
Name 02 Code 2 Data 01
0003 Name 03 Code 3 Data 01
Sample Number 2 Sample Name 2 Sample Code 2 Sample Data 2
0004 Name 04 Code 5 Data 05
section of data Data 05.5
0005 Name 05 Code 5 Data 06

Annex B
List Examples (Informative)πŸ”—

B.1 Customizing Ordered ListsπŸ”—

B.1.1 GeneralπŸ”—

Ordered lists (ol) may be modified from their default list numberings (numbers) using the type attribute. The possible list numberings are lowercase letter (a), uppercase letter (A), lowercase Roman numerals (i), uppercase Roman numerals (I), and numbers (1 - default if not used). The start attribute may also be used with a numeric value to denote the start of the numbering of the listed items.

NOTE —⁠ The type and start attributes are not supported for unordered lists (ul). Formatting for bullets on ul lists are auto-generated by the tooling, based on nesting.

B.1.2 List type ExamplesπŸ”—

See below for various list examples utilizing type and start

EXAMPLE 1 —⁠

Lower Case Letter: 

<ol type="a">
  <li>First list item</li>
  <li>Second list item</li>
</ol>

is rendered as:

  1. First list item
  2. Second list item
EXAMPLE 2 —⁠

Upper Case Letter: 

<ol type="A">
  <li>First list item</li>
  <li>Second list item</li>
</ol>

is rendered as:

  1. First list item
  2. Second list item
EXAMPLE 3 —⁠

Lower Case Roman Numeral: 

<ol type="i">
  <li>First list item</li>
  <li>Second list item</li>
</ol>

is rendered as:

  1. First list item
  2. Second list item
EXAMPLE 4 —⁠

Upper Case Roman Numeral: 

<ol type="I">
  <li>First list item</li>
  <li>Second list item</li>
</ol>

is rendered as:

  1. First list item
  2. Second list item
EXAMPLE 5 —⁠

List starting from (3): 

<ol start="3">
  <li>First list item</li>
  <li>Second list item</li>
</ol>

is rendered as:

  1. First list item
  2. Second list item

B.2 List NestingπŸ”—

Both ol and ul elements may be nested as many times within a li element as needed to achieve the required results. See below for various examples.

EXAMPLE 1 —⁠

Nesting ol: 

<ol>
  <li>First list item
    <ol type="a">
      <li>First sub item</li>
      <li>Second sub item</li>
    </ol>
  </li>
  <li>Second list item</li>
</ol>

is rendered as:

  1. First list item
    1. First sub item
    2. Second sub item
  2. Second list item

NOTE —⁠ When nesting ol style lists, different type attributes should be used to ensure readablity, as this is not achieved automatically.

EXAMPLE 2 —⁠

Nesting ul: 

<ul>
  <li>First list item
    <ul>
      <li>First sub item</li>
      <li>Second sub item</li>
    </ul>
  </li>
  <li>Second list item</li>
</ul>

is rendered as:

  • First list item
    • First sub item
    • Second sub item
  • Second list item
EXAMPLE 3 —⁠

Nesting ul in ol: 

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

is rendered as:

  1. First list item
    • First sub item
    • Second sub item
  2. Second list item

B.3 Complex List ExampleπŸ”—

The features in Clause B.1 and Clause B.2 may be combined as needed to achieve the required results for a complex list. See below for an example.

EXAMPLE —⁠ 
<ol>
  <li>First list item
    <ol type="a">
      <li>First sub item
        <ol type="i">
          <li>First sub item's 1st item with small roman numerals</li>
          <li>First sub item's 2nd item with small roman numerals</li>
        </ol>
      </li>
      <li>Second sub item
        <ol type="i" start="3">
          <li>Second sub item's 1st item with small roman numerals, starting with "iii" to continue numbers</li>
          <li>Second sub item's 2nd item with small roman numerals</li>
        </ol>
      </li>
    </ol>
  </li>
  <li>Second list item</li>
  <li>Third list item</li>
  <li>Forth list item
    <ol type="a">
      <li>Forth list item's sub item
        <ul>
          <li>1st bullet under sub item
            <ul>
              <li>1st sub bullet</li>
            </ul>
          </li>
          <li>2nd bullet under sub item</li>
        </ul>
      </li>
      <li>Forth list item's sub item</li>
    </ol>
  </li>
  <li>Fifth list item
    <ul>
      <li>1st bullet sub item</li>
      <li>2nd bullet sub item</li>
    </ul>
  </li>
</ol>

is rendered as:

  1. First list item
    1. First sub item
      1. First sub item's 1st item with small roman numerals
      2. First sub item's 2nd item with small roman numerals
    2. Second sub item
      1. Second sub item's 1st item with small roman numerals, starting with "iii" to continue numbers
      2. Second sub item's 2nd item with small roman numerals
  2. Second list item
  3. Third list item
  4. Forth list item
    1. Forth list item's sub item
      • 1st bullet under sub item
        • 1st sub bullet
      • 2nd bullet under sub item
    2. Forth list item's sub item
  5. Fifth list item
    • 1st bullet sub item
    • 2nd bullet sub item

Annex C
Document Status Workflow (Normative)πŸ”—

C.1 Mapping pubState and pubStage to Document StatusπŸ”—

Table C.1 maps the required values of content for pubState and pubStage during the various stages of document development.

Table C.1 β€” Mapping pubStage and pubState to Document Status
Document Status pubStage content value pubState content value
Undergoing initial draft or revision in DG/SG/WG WD draft
Undergoing pre-FCD review WD pub
Undergoing comment resolution from pre-FCD review (or) undergoing comment resolution from PCD period CD draft
Ready for FCD ballot (or) undergoing FCD ballot (or) ready for PCD (or) currently in PCD period CD pub
FCD ballot complete, undergoing comment resolution FCD draft
FCD ballot comment resolution complete (or) undergoing pre-DP review (or) ready for DP ballot (or) undergoing DP ballot FCD pub
FCD ballot complete with no comments (or) DP ballot passed (or) ready for ST Audit (or) undergoing ST audit DP pub
ST audit complete (or) waiting for publication PUB draft
Published PUB pub

See Clause C.4 for a sample workflow utilizing these statuses.

C.2 GitHub ReleasesπŸ”—

Whenever the state of the document changes to <meta itemprop="pubState" content="pub" /> on the main branch, then a release shall be created in the GitHub repo.

Both the GitHub release and git tag shall be named YYYYMMDD "-" pubStage. The YYYYMMDD should directly represent the value used in pubDateTime as defined in 7.2.12.

EXAMPLE 1 —⁠ 20230615-fcd or 20230925-pub

The latestEditionTag property in the .smpte-build.json file shall always be equal to the name of the most recent git tag. This will trigger the tooling to create a link for Redline to most recent edition during any PRs and merges to the main branch.

The tooling will automatically generate zip files within the release details page, to be used for both :

EXAMPLE 2 —⁠ See https://github.com/SMPTE/st428-24-private/releases/tag/20241101-dp, where https://github.com/SMPTE/st428-24-private/releases/download/20241101-dp/27c-st-428-24-dp-2024-12-06-pub.zip (ballot zip), and https://github.com/SMPTE/st428-24-private/releases/download/20241101-dp/20241101-dp.zip (publish zip) are available.

See Clause C.4 for a sample workflow utilizing releases.

C.3 Pull Request GuidelinesπŸ”—

Generally, no changes to a document shall ever be made directly on the main branch, which doesn't allow the tooling to create needed redlines. Instead, changes (regardless of the nature of the change) shall always be made on a new branch and managed via a PR (Pull Request). Each PR is then merged to main after approval, as noted below in Clause C.4 at the various stages.

PRs should have at least (1) approver that is not the the person requesting the PR. This can be the DG chair, TC chair, commentor, or secondary editor, depending on nature of the PR. For instance, on ballot state change PRs, this should be the DG or TC chair, and for publication state PRs, the TC chairs. See Clause C.4 for more details.

C.4 Sample Workflow πŸ”—

The below list shows a sample workflow which would be the steps for an Engineering Document going through the an initial draft or revision and the balloting process.

NOTE —⁠ Editors and Chairs should be aware of the general guidelines provided in the SMPTE GitHub Operating Manual.

  1. Project is approved
    1. If document is an initial draft, skip to Workflow Step (2)
    2. If document is a revision, skip to Workflow Step (3)
  2. Project is a document initial draft
    1. Follow the steps in Clause 5 to create repo.
    2. A new branch is created from main called 2023-initial-draft (where "2023" is the current year).
    3. Make sure that the pubState (7.2.7) and pubStage (7.2.8) of the main prose element in the 2023-initial-draft branch are set to draft and WD, respectively.
    4. Document editor creates initial version of the document.
    5. A PR is created named 2023 Initial Draft from the 2023-initial-draft branch on GitHub.
    6. Skip to Workflow Step (4)
  3. Project is a document revision
    1. Assumption: There is a prior release labeled 2020115-pub
    2. A new branch is created from main called 2023-revision (where "2023" is the current year).
    3. Make sure that the pubState (7.2.7) and pubStage (7.2.8) of the main prose element in the 2023-initial-draft branch are set to draft and WD, respectively.
    4. .smpte-build.json is updated in 2023-revision branch to last release tag 2020115-pub (see Clause C.2)
    5. Document editor makes initial changes to the document.
    6. A PR is created named 2023 Revision from the 2023-revision branch on GitHub. The tooling with create a redline against the most recent edition of the document.
    7. Continue to Workflow Step (4)
  4. DG meeting(s) held regarding drafting of the document
    1. Comments are received, either by reflector or during meeting(s).
    2. Comments and suggested changes are added to issue tracker.
    3. Document is updated via more commits in the current PR, closing comments.
    4. Continue to Workflow Step (5)
  5. DG is complete with drafting the document
    1. Document is updated in PR to <meta itemprop="pubState" content="pub" />, <meta itemprop="pubStage" content="WD" /> and <meta itemprop="pubDateTime" content="2023-04-15" /> (assumed date of completion).
    2. PR is approved by document editor and DG chair. PR is merged to main.
    3. A release is created targeted at main named 20230415-wd with a tag of the same name.
    4. The tooling creates the zip needed for TC 2-week preFCD review, with redlines against latest edition and/or last draft (if applicable)
    5. The link to the ZIP is sent to TC for 2-week preFCD review
    6. Continue to Workflow Step (6)
  6. TC 2-week preFCD review occurs
    1. A new branch is created from main called 20230415-cd1.
    2. Document is updated in 20230415-cd1 branch to <meta itemprop="pubState" content="draft" /> and <meta itemprop="pubStage" content="CD" />.
    3. .smpte-build.json is updated in 20230415-cd1 branch to 20230415-wd tag
    4. A PR is created named 20230415 CD1 from the 20230415-cd1 branch on GitHub.
    5. If no comments received, skip to Workflow Step (8)
    6. If comments are received, continue to Workflow Step (7)
  7. Comments received on pre-FCD ballot review
    1. Document is updated in PR from Workflow Step (6) as needed per comments received. A redline from last draft is created by the tooling as required to resolve comments.
    2. Once comments are resolved he document is updated in PR to <meta itemprop="pubDateTime" content="2023-05-15" /> (assumed date of completion).
    3. Continue to Workflow Step (8)
  8. Document is ready for FCD ballot
    1. Document is updated in PR from Workflow Step (6) to <meta itemprop="pubState" content="pub" />
      • If document did NOT receive any comments, the pubDateTime remains unchanged from Workflow Step (5).
    2. PR is merged to main.
    3. A release is created targeted at main named 20230415-cd1 (or 20230515-cd1 if Workflow Step 7 was used) with a tag of the same name.
    4. If document is to continue to FCD ballot, the link to the ZIP file that is generated by the tooling in main with required redlines is sent to the TC for FCD ballot. Skip to Workflow Step (9)
    5. If document is to undergo a PCD period, the contents in the ZIP file generated by the tooling in main are used for the PCD. After PCD period ends, go back to Workflow Step (6). See Clause C.2 for iterative CD naming.
    6. Continue to Workflow Step (9)
  9. TC conducts FCD ballot
    1. If no comments received, skip to Workflow Step (12)
    2. If comments are received, continue to Workflow Step (10)
  10. FCD ballot comment resolution
    1. A new branch is created from main called 2023-revision-fcd-comment-res.
    2. Document is updated in 2023-revision-fcd-comment-res branch to <meta itemprop="pubState" content="draft" /> and <meta itemprop="pubStage" content="FCD" />.
    3. .smpte-build.json is updated in 2023-revision-fcd-comment-res branch to 20230415-cd1 (or 20230515-cd1) tag
    4. PR is created on GitHub with the changes in 2023-revision-fcd-comment-res as needed to resolve comments. The tooling creates redline for review against the last edition (release 20230415-cd1 or 20230515-cd1).
    5. Additional commits are added to the PR as need to resolve comments.
    6. Comment resolution ends, document is updated to <meta itemprop="pubState" content="pub" /> and <meta itemprop="pubDateTime" content="2023-07-15" /> (assumed date of completion).
    7. PR is approved by document editor and DG chair. PR is merged to main.
    8. A release is created targeted at main named 20230715-fcd with a tag of the same name.
    9. The link to the ZIP file that is generated by the tooling in main is sent to the TC for pre-DP review.
    10. Continue to Workflow Step (11)
  11. TC conducts DP ballot
    1. DP ballot passes, continue to Workflow Step (12)
  12. Document is now DP
    1. A new branch is created from main called 20230415-dp (or 20230715-dp if Workflow Step 5 was used or 20230715-dp if Workflow Step 10 was used).
    2. Document is updated in 20230415-dp branch to <meta itemprop="pubStage" content="DP" />
    3. .smpte-build.json is updated in 20230415-dp branch to 20230415-cd1 tag (or 20230515-cd1)
    4. PR is created on GitHub with the changes as per needed to resolve comments. The tooling creates redline for review against the last edition (release 20230415-cd1 or 20230515-cd1 or 20230715-fcd).
    5. PR is approved by document editor and DG chair. PR is merged to main.
    6. A release is created targeted at main named 20230415-dp (or 20230515-dp or 20230715-dp) with a tag of the same name.
    7. The link to the ZIP file that is generated by the tooling in main is sent to DoS for ST audit.
    8. Continue to Workflow Step (13)
  13. ST conducts ST audit
    1. ST audit passes, continue to Workflow Step (14)
  14. Document is ready for publication
    1. A new branch is created from main called 20230415-pub (or 20230515-pub or 20230715-pub).
    2. Document is updated in 20230415-pub branch to <meta itemprop="pubStage" content="pub" />
    3. If document is a revision, .smpte-build.json is updated in 20230415-pub branch to 2020115-pub tag
    4. PR is created on GitHub from 20230415-pub
    5. PR is approved by document editor, DG chair, and TC chair(s). PR is merged to main.
    6. A release is created targeted at main named 20230415-pub (or 20230515-pub or 20230715-pub) with a tag of the same name.
    7. The document is now "published" on main.
    8. Send SMPTE HO the 20230415-pub.zip (or 20230515-pub.zip or 20230715-pub.zip) generated in the release to use in the https://github.com/SMPTE/document-library.
      • Automation for this step is planned for a future date.

Additional elementsπŸ”—

The following are the non-prose elements of this document:

  1. a. Sample text element (informative). file: <sample.txt>.
  2. b. Sample URL element (normative). url: <https://github.com/SMPTE/html-pub/tree/631ed7a0312fa183c356a7b742129ce46f92736f>.

BibliographyπŸ”—