The SMPTE HTML publication tooling consists of several components:
@@ -1336,7 +1338,7 @@At the heart of the tooling is the rendering code at smpte.js.
Building the document for publication involves the following steps:
@@ -1398,7 +1400,7 @@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 is stored at .github/workflows/main.yml in the
@@ -1435,7 +1437,7 @@
The tooling uploads publication artifacts to an S3 bucket according to the following parameters:
@@ -1485,7 +1487,7 @@It is advisable to install the git commit hook listed at . It detects errors before a document can be committed.
@@ -1495,7 +1497,102 @@Many of the features and automatic formatting available in the tooling is present and available when working locally. This allows an editor to create and edit a valid HTML document before pushing to a repo and encountering an error.
+It is recommended to utilize VS Code (https://code.visualstudio.com/) as your local HTML editor, using the Live Preview extension (https://marketplace.visualstudio.com/items?itemName=ms-vscode.live-server), which shows some validation in real-time for an editor.
+Other useful extension(s) for VS Code are:
++ To use the full features locally either on command line, or in termimal (also available inside of VS Code), an editor will need to have the following installed locally:
+Once installed, it is recommended to keep up to date with the latest versions.
+Assuming the prerequisites listed in are already installed, each time a new repo is cloned and work is to be started, the repo will need to be configured for its dependencies, based on the current ./package.json file.
The command for this is:
++npm install ++ +
This command will update ./package-lock.json, and can be run again if changes are made to ./package.json for editing and/or updating dependencies based on the repo.
Once npm/Node is set up, it is also recommended to set up the requirements and further dependencies for validation to run properly.
+ +The command for this is:
++npm run prevalidate ++ +
This will check and (if needed) install the HTML 5 validator as noted in . If the HTML 5 validator has already been installed, or the command has been run before (on another repo), the prompt will return: + +
+html5validator found. HTML validation ready. ++ +
When creating a PR on GitHub, the tooling automatically performs a build process as noted in , and part of that process is doing validation, both the internal to the tooling and for general HTML 5 validation.
+ +While the internal tooling validation occurs at runtime while editing, waiting until the build action during a PR to check the HTML 5 validation can present an editor with unforseen issues (i.e. an invalid element or broken schema error), which then results in failures on the PR/build that must be fixed. Often times when this occurs the preview with redlines is not available in the PR, and/or the tooling will not allow a build to finish. Therefore it is highly recommended an editor runs the validation locally prior to pushing to GitHub to prevent these failures frmo occuring.
+ +The command for this is:
++npm run validate ++ +
This command reports back errors in (2) seperate sections that are required to be resolved before a build can complete. The HTML validation includes line numbers for the convenience of the editor.
+ + +
+> smpte-html-pub-tooling@2.1.0 prevalidate
+> node scripts/ensure-html5validator.mjs
+
+html5validator found. HTML validation ready.
+
+> smpte-html-pub-tooling@2.1.0 validate
+> run-p validate:doc validate:html
+
+> smpte-html-pub-tooling@2.1.0 validate:html
+> html5validator --errors-only ./doc/main.html
+
+> smpte-html-pub-tooling@2.1.0 validate:doc
+> node ./scripts/validate.mjs ./doc/main.html
+
+Unknown element in clause HTMLElement {
+ [Symbol(SameObject caches)]: [Object: null prototype] { children: HTMLCollection {} }
+}
+".../SMPTE/html-pub/./doc/main.html":1512.7-1512.10: error: No "p" element in scope but a "p" end tag seen.
+".../SMPTE/html-pub/./doc/main.html":1524.7-1524.10: error: No "p" element in scope but a "p" end tag seen.
+".../SMPTE/html-pub/./doc/main.html":1554.21-1555.7: error: Saw "<" when expecting an attribute name. Probable cause: Missing ">" immediately before.
+".../SMPTE/html-pub/./doc/main.html":1554.21-1555.9: error: End tag had attributes.
+".../SMPTE/html-pub/./doc/main.html":1555.242-1555.245: error: No "p" element in scope but a "p" end tag seen.
+ERROR: "validate:html" exited with 5.
+
+
+