Skip to content

Documentation and example updates #383

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Merged
SteveLLamb merged 2 commits into from
Mar 10, 2026
Merged

Documentation and example updates #383

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
314bbca
Closes #380, closes #382
SteveLLamb Mar 3, 2026
665ee6b
Approved per ST meeting 2026-03-10
SteveLLamb Mar 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
157 changes: 133 additions & 24 deletions doc/main.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
<meta itemprop="pubConfidential" content="no">
<!--< meta itemprop="pubTC" content="XX"> -->
<meta itemprop="pubSuiteTitle" content="HTML Pub">
<meta itemprop="pubDateTime" content="2026-01-30">
<meta itemprop="pubDateTime" content="2026-03-10">
<!-- <meta itemprop="pubRevisionOf" content="SMPTE ST XXXX-Y:ZZZZ"> -->
<title>Tooling and documentation for HTML documents</title>
</head>
Expand All @@ -37,10 +37,26 @@
<ul>
<li>
<cite id="bib-HTML-5">HTML Standard</cite>, Living Standard
<a>https://html.spec.whatwg.org/multipage/</a></li>
<a>https://html.spec.whatwg.org/multipage/</a></li>
<li><cite id="bib-smpte-standards-operations-manual">SMPTE Standards Operations Manual</cite>
<a>https://doc.smpte-doc.org/standards-operations-manual/main/</a></li>
<li><cite id="bib-smpte-ag-02">SMPTE AG 02</cite>, Document Naming and Packaging
<a>https://doc.smpte-doc.org/ag-02/main/</a></li>
<li><cite id="bib-smpte-ag-07">SMPTE AG 07</cite>, Document Flowcharts
<a>https://doc.smpte-doc.org/ag-07/main/</a></li>
<li><cite id="bib-smpte-ag-31">SMPTE AG 31</cite>, GitHub Operating Guidelines
<a>https://doc.smpte-doc.org/ag-31/main/</a></li>
</ul>
</section>

<section id="sec-terms-and-definitions">
<ul id="terms-ext-defs">
<li><a href="#bib-smpte-standards-operations-manual"></a></li>
<li><a href="#bib-smpte-ag-31"></a></li>
</ul>

</section>

<section id="sec-quick-start">
<h2>Quick start</h2>

Expand Down Expand Up @@ -983,7 +999,7 @@ <h4>Lists</h4>
<section id="sec-figure-element">
<h4>Figures</h4>

<p>A figure can be inserted using a <code>figure</code> element with the following requirements:</p>
<p>A figure can be inserted using a <code>figure</code> element, using the image format as defined in <a href="#bib-smpte-ag-02"></a>, with the following requirements. </p>

<p>The <code>figure</code> element shall contain:</p>
<ul>
Expand All @@ -1001,7 +1017,7 @@ <h4>Figures</h4>
<div class="example">
<pre>
&lt;figure id=&quot;figure-sample-image&quot;&gt;
&lt;img src=&quot;media/sample.png&quot;&gt;
&lt;img src=&quot;media/sample.svg&quot;&gt;
&lt;figcaption&gt;Example of a figure&lt;/figcaption&gt;
&lt;/figure&gt;
</pre>
Expand Down Expand Up @@ -2204,64 +2220,160 @@ <h3>Complex List Example</h3>
<h2>Document Status Workflow</h2>

<section id="sec-document-mapping-status">
<h3>Mapping <code>pubState</code> and <code>pubStage</code> to Document Status</h3>
<h3>Mapping <code>meta</code> tags to Document Status</h3>
<p>
<a href="#tab-document-mapping-status"></a> maps the required values of <code>content</code> for <code>pubState</code> and <code>pubStage</code> during the various stages of document development.
<a href="#tab-document-mapping-status"></a> maps the required <code>content</code> values of <code>pubState</code>, <code>pubStage</code>, and <code>pubConfidential</code> during the various stages of document development. These values represent the naming convention(s) as defined in <a href="#bib-smpte-ag-02"></a> and flowcharts as defined in <a href="#bib-smpte-ag-07"></a>
</p>
<table id="tab-document-mapping-status" class="col-2-center col-3-center">
<caption>Mapping <code>pubStage</code> and <code>pubState</code> to Document Status</caption>
<table id="tab-document-mapping-status" class="col-2-center col-3-center col-4-center">
<caption>Mapping <code>content</code> values for <code>meta</code> tags to Document Status</caption>
<thead>
<tr>
<th>Document Status</th>
<th><code>pubStage</code> <code>content</code> value</th>
<th><code>pubState</code> <code>content</code> value</th>
<th><code>pubStage</code> value</th>
<th><code>pubState</code> value</th>
<th><code>pubConfidential</code> value</th>
</tr>
</thead>
<tbody>
<tr>
<td>Undergoing initial draft or revision in DG/SG/WG</td>
<td>Initial draft or revision (Working Draft) in:
<br/>Draft Group (DG)
<br/>Study Group (SG)
<br/>Working Group (WG)</td>
<td><code>WD</code></td>
<td><code>draft</code></td>
<td><code>yes</code></td>
</tr>
<tr>
<td>Undergoing pre-FCD review</td>
<td class="center-cell" colspan="4"><em>>> Document moves to TC >></em></td>
</tr>
<tr>
<td>Pre-FCD (Final Committee Draft) review</td>
<td><code>WD</code></td>
<td><code>pub</code></td>
<td><code>yes</code></td>
</tr>
<tr>
<td class="center-cell" colspan="4"><em>>> If pre-FCD comments received, back to DG/SG/WG >></em></td>
</tr>
<tr>
<td>Pre-FCD comment resolution ongoing </td>
<td><code>CD</code></td>
<td><code>draft</code></td>
<td><code>yes</code></td>
</tr>
<tr>
<td>Pre-FCD comment resolution complete </td>
<td><code>CD</code></td>
<td><code>pub</code></td>
<td><code>yes</code></td>
</tr>
<tr>
<td class="center-cell" colspan="4"><em>>> Document moves to TC >></em></td>
</tr>
<tr>
<td>PCD (Public Committee Draft) period</td>
<td><code>CD</code></td>
<td><code>pub</code></td>
<td><code>no</code></td>
</tr>
<tr>
<td>Undergoing comment resolution from pre-FCD review (or) undergoing comment resolution from PCD period</td>
<td>PCD comment resolution ongoing (moves back to DG/SG/WG)</td>
<td><code>CD</code></td>
<td><code>draft</code></td>
<td><code>yes</code></td>
</tr>
<tr>
<td>PCD comment resolution complete</td>
<td colspan="3"><em>>> Back to Pre-FCD (Final Committee Draft) review >></em></td>
</tr>

<tr>
<td class="center-cell" colspan="4"><em>(OR)</em></td>
</tr>
<tr>
<td>Ready for FCD ballot</td>
<td><code>CD</code></td>
<td><code>pub</code></td>
<td><code>yes</code></td>
</tr>
<tr>
<td>Ready for FCD ballot (or) undergoing FCD ballot (or) ready for PCD (or) currently in PCD period</td>
<td>FCD ballot period</td>
<td><code>CD</code></td>
<td><code>pub</code></td>
<td><code>yes</code></td>
</tr>
<tr>
<td class="center-cell" colspan="4"><em>>> If FCD ballot comments received >></em></td>
</tr>
<tr>
<td>FCD ballot complete, undergoing comment resolution</td>
<td>FCD ballot comment resolution ongoing</td>
<td><code>FCD</code></td>
<td><code>draft</code></td>
<td><code>yes</code></td>
</tr>
<tr>
<td>FCD ballot comment resolution complete</td>
<td><code>FCD</code></td>
<td><code>pub</code></td>
<td><code>yes</code></td>
</tr>
<tr>
<td>FCD ballot comment resolution complete (or) undergoing pre-DP review (or) ready for DP ballot (or) undergoing DP ballot </td>
<td>Pre-DP (Draft Publication) review</td>
<td><code>FCD</code></td>
<td><code>pub</code></td>
<td><code>yes</code></td>
</tr>
<tr>
<td>Pre-DP ballot period</td>
<td><code>FCD</code></td>
<td><code>pub</code></td>
<td><code>yes</code></td>
</tr>
<tr>
<td class="center-cell" colspan="4"><em>(ELSE)</em></td>
</tr>
<tr>
<td>FCD ballot passes, no comments</td>
<td><code>DP</code></td>
<td><code>pub</code></td>
<td><code>yes</code></td>
</tr>
<tr>
<td>DP ballot passes</td>
<td><code>DP</code></td>
<td><code>pub</code></td>
<td><code>yes</code></td>
</tr>
<tr>
<td>FCD ballot complete with no comments (or) DP ballot passed (or) ready for ST Audit (or) undergoing ST audit</td>
<td>Ready for ST (Standards Committee) Audit</td>
<td><code>DP</code></td>
<td><code>pub</code></td>
<td><code>yes</code></td>
</tr>
<tr>
<td>ST audit complete (or) waiting for publication</td>
<td>ST Audit period</td>
<td><code>DP</code></td>
<td><code>pub</code></td>
<td><code>yes</code></td>
</tr>
<tr>
<td>ST Audit complete</td>
<td><code>PUB</code></td>
<td><code>draft</code></td>
<td><code>yes</code></td>
</tr>
<tr>
<td>Waiting for publication</td>
<td><code>PUB</code></td>
<td><code>draft</code></td>
<td><code>yes</code></td>
</tr>
<tr>
<td>Published</td>
<td><code>PUB</code></td>
<td><code>pub</code></td>
<td><code>no</code></td>
</tr>
</tbody>
</table>
Expand All @@ -2287,7 +2399,7 @@ <h3>GitHub Releases</h3>
The <code>latestEditionTag</code> property in the <code>.smpte-build.json</code> file shall always be equal to the name of the most recent git tag. This will trigger the tooling to create a link for <code>Redline to most recent edition</code> during any PRs and merges to the <code>main</code> branch.
</p>
<p>
The tooling will automatically generate zip files within the release details page, to be used for both :</p>
The tooling will automatically generate zip file packages within the release details page, to be used for both :</p>
<ul>
<li>TC review/balloting (named as per <a href="#bib-smpte-ag-02"></a>)</li>
<li>(and) SMPTE Document Library publishing (named by the tag)</li>
Expand Down Expand Up @@ -2317,7 +2429,7 @@ <h3>Sample Workflow </h3>
The below list shows a sample workflow which would be the steps for an Engineering Document going through an initial draft or revision and the balloting process.
</p>

<p class="note">Editors and Chairs should be aware of the general guidelines provided in the <a href="#bib-smpte-gh-om"></a>.
<p class="note">Editors and Chairs should be aware of the general guidelines provided in the <a href="#bib-smpte-ag-31"></a>.
</p>
<ol>

Expand Down Expand Up @@ -2491,12 +2603,9 @@ <h3>Sample Workflow </h3>
<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><cite id="bib-smpte-ag-02">SMPTE AG 02</cite>, Document Naming and Packaging
<a>https://doc.smpte-doc.org/ag-02/main/</a></li>
<li><cite id="bib-smpte-ag-16">SMPTE AG 16</cite>, Standards Style Guide
<a>https://doc.smpte-doc.org/ag-16/main/</a></li>
<li><cite id="bib-smpte-gh-om">SMPTE GitHub Operating Manual</cite>
<a>https://github.com/SMPTE/github-operating-manual</a></li>


</ul>
</section>
Expand Down