Editing HTML documents

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 src="tooling/smpte.js"></script>

    <script type="module" src="../smpte.js"></script>

    <meta itemprop="pubType" content="AG" />
    <meta itemprop="pubNumber" content="XX" />
    <meta itemprop="pubState" content="draft" />
    <meta itemprop="pubDateTime" content="20XX-XX-XX" />
    <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 approprtiate 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; a meta element that conforms to 7.2.2 ; a meta element that conforms to 7.2.3 ; a meta element that conforms to 7.2.4 ; a meta element that conforms to 7.2.6 , if and only if pubType is OM ; a meta element that conforms to 7.2.5 , if pubState is pub ; directory.

The title element shall be equal to the title of the document, without any document number.

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 ~~the following: Additional~~ additional script ~~elements.~~ elements that import JavaScript libraries for document layout, e.g. MathJax

EXAMPLE —

<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 ~~have~~ 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:

AG, if the document is an Administrative Guideline;
OM, if the document is an Operations ~~Manual.~~ Manual;
ST, if the document is a Standard;
RP, if the document is a Recommended Practice; or
EG, if the document is an Engineering Guideline.

7.2.3 `pubNumber` 🔗

The head element shall ~~have~~ 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 zero or one meta element with an itemprop attribute equal to pubPart.

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

7.2.5 `pubVersion` 🔗

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

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

The element shall have a content attribute equal to the document version.

7.2.4 7.2.6 `pubState` 🔗

The head element shall ~~have~~ 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.

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

7.2.8 `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.9 `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.5 7.2.10 `pubDateTime` 🔗

The head element shall ~~have~~ 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 publication date of the document.

7.2.6 7.2.11 `effectiveDateTime` 🔗

The head element shall ~~have~~ 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.7 7.2.12 Additional `script` elements Addition script elements can be used to import JavaScript libraries to assist with document layout, e.g. MathJax 🔗 EXAMPLE — <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.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 🔗

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 infomation relevant to the document.</p>
</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.

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>

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 infomation.
Each li element may contain one a element that contains a location where the reference can be retrieved.

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>
  </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~~ symbol. More than one dt element can precede a dd element, in which case all the terms, abbreviations and symbols in the immediately preceding dt elements are synomys.
- Each dd element contains the matching definition. One or two dd elements can follow a dt element. The first dd element immediately following the dt element shall be a definition. The second dd element, if present, shall reference a bibliographic entry, in which case the entry will be considered the source of the definition of the term.

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>

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

EXAMPLE —

<section class="annex" id="sec-addtional-info">
  <h2>Additional Info</h2>
  <section id="sec-addtional-info-sub-section">
    <h3>Additional Info Sub Section</h3>
    <p>Some technical content</p>
  </section>
  <section id="sec-addtional-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 itself, typically in the doc/elements directory.

EXAMPLE —

<section id="sec-elements">
  <ol>
    <li>
      <a id="element-a" title="Description of the elemnent" 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 conform to the same requirement as the ul element of the normative references section.

EXAMPLE —

<section id="sec-bibliography">
  <ul>
    <li>
      <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>
    </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 attribute referencing a a element from the additional elements section shall be used.

EXAMPLE —


<a
href="#element-a"></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.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.

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>

7.4.8 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 element

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

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

NOTE — Page breaks are avoided within a tbody element.

EXAMPLE 1 —

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

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.10 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.11 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.12 Notes 🔗

Notes can be inserted by using p or div element whose class attribute is equal to note.

Notes will automatically be formatted, e.g. prepended with the text NOTE , and numbered.

EXAMPLE —

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

7.4.13 Examples 🔗

Examples can be inserted by using div element whose class attribute is equal to example.

Notes will automatically be formatted, e.g. prepended with the text EXAMPLE , and numbered.

EXAMPLE 1 —

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

results in:

EXAMPLE 2 — The number 0.0003 can be written 3×10−4 but is never written 3e−4.

7.4.14 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.15 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 = a x^{2} + b x + c$ to find the position.

A block formula are 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 can 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 = a x^{2} + b x + c

(1)

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

7.4.16 Special Characters 🔗

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

8 Tooling 🔗

8.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.2 Rendering 🔗

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

The rendering code ~~tuns~~ 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:

Validating the document
Rendering the document
Creating redlines from the rendered document
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:

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" ]
    }
  }
}

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": null

  "latestEditionTag": "v1.0.0"

}

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]
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.event_name == 'push' && github.ref == 'refs/heads/main') || github.event_name == 'pull_request'

    if: github.repository_owner	== 'SMPTE' && ((github.event_name == 'push' && github.ref == 'refs/heads/main') || github.event_name == 'pull_request')

    # 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
          ref: ${{ github.event.pull_request.head.sha }}

          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 HEAD | grep -v ${CUR_BRANCH}`; do git branch --track ${i#remotes/origin/} $i; done

        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 ~~variabls:~~ 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:

CANONICAL_LINK_PREFIX / AWS_S3_KEY_PREFIX 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 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.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 🔗

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 mutliple 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`
0001	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
0001	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

Editing HTML documents

Table of contents 🔗

Foreword 🔗

Introduction 🔗

1 Scope 🔗

2 Conformance 🔗

3 Normative references 🔗

4 Terms and definitions 🔗

5 Quick start 🔗 5.1 For document editors

6 Directory layout 🔗

7 Main element 🔗

7.1 General 🔗

7.2 head element 🔗

7.2.1 General 🔗

7.2.2 pubType 🔗

7.2.3 pubNumber 🔗

7.2.4 pubPart 🔗

7.2.5 pubVersion 🔗

7.2.4 7.2.6 pubState 🔗

7.2.7 pubStage 🔗

7.2.8 pubRevisionOf 🔗

7.2.9 pubTC 🔗

7.2.5 7.2.10 pubDateTime 🔗

7.2.6 7.2.11 effectiveDateTime 🔗

7.3 body element 🔗

7.3.1 Overall structure 🔗

7.3.2 Foreword section 🔗

7.3.3 Introduction section 🔗

7.3.4 Scope section 🔗

7.3.5 Conformance section 🔗

7.3.6 Normative references section 🔗

7.3.7 Terms and definitions section 🔗

7.3.8 Prose section(s) 🔗

7.3.9 Annex section(s) 🔗

7.3.10 Additional elements section 🔗

7.3.11 Bibliography section 🔗

7.4 Other elements 🔗

7.4.1 Referencing clauses 🔗

7.4.2 Citing normative references 🔗

7.4.3 Citing non-prose elements 🔗

7.4.4 Citing bibliographic references 🔗

7.4.5 External links 🔗

7.4.6 Inline terms 🔗

7.4.7 Lists of key-value pairs 🔗

7.4.8 Figures 🔗

7.4.9 Tables 🔗

7.4.10 External code snippets 🔗

7.4.11 Internal code snippets 🔗

7.4.12 Notes 🔗

7.4.13 Examples 🔗

7.4.14 Quotes and blockquotes 🔗

7.4.15 Formulae 🔗

7.4.16 Special Characters 🔗

8 Tooling 🔗

8.1 Overview 🔗

8.2 Rendering 🔗

8.3 Building 🔗

8.4 GitHub integration 🔗

8.5 Amazon AWS integration 🔗

8.6 Git commit hooks 🔗

Annex A Table Examples 🔗

A.1 Alignment 🔗

A.1.1 Default Alignment 🔗

A.1.2 Column Alignment 🔗

A.1.3 Cell Alignment 🔗

A.2 Multiple Headers 🔗

A.3 Cell Spanning 🔗

A.3.1 colspan 🔗

A.3.2 rowspan 🔗

A.4 Complex Example 🔗

Annex B Additional elements 🔗

Bibliography 🔗

7.2 `head` element 🔗

7.2.2 `pubType` 🔗

7.2.3 `pubNumber` 🔗

7.2.4 `pubPart` 🔗

7.2.5 `pubVersion` 🔗

7.2.4 7.2.6 `pubState` 🔗

7.2.7 `pubStage` 🔗

7.2.8 `pubRevisionOf` 🔗

7.2.9 `pubTC` 🔗

7.2.5 7.2.10 `pubDateTime` 🔗

7.2.6 7.2.11 `effectiveDateTime` 🔗

7.3 `body` element 🔗

Annex A
Table Examples 🔗

A.3.1 `colspan` 🔗

A.3.2 `rowspan` 🔗

Annex B
Additional elements 🔗