OIML NISO STS toolkit. Converts OIML-flavored Metanorma presentation XML into OIML NISO STS XML (ANSI/NISO Z39.102-2022 profile), validates it against the OIML X 999:2026 constraints, and exposes a Thor CLI plus a native Ruby API.
|
Caution
|
The metanorma compile -t oiml -x oimlsts document.adoc # => document.oiml.sts.xml
|
oiml-sts convert <input.presentation.xml> [output.sts.xml]
oiml-sts convert-dir <input-dir> <output-dir>
oiml-sts validate <sts.xml>require "metanorma/oiml/sts"
sts_xml = Metanorma::Oiml::Sts.convert(metanorma_presentation_xml)
File.write("out.sts.xml", sts_xml)
report = Metanorma::Oiml::Sts.validate(sts_xml)
report.errors.any? { |e| puts e.message }The OIML NISO STS XML is derived from a Metanorma OIML publication’s presentation XML — the rendered XML form that Metanorma produces from AsciiDoc sources. The conversion pipeline is:
OIML AsciiDoc source --> metanorma (oiml flavor) --> document.presentation.xml
|
v
oiml-sts convert
|
v
OIML NISO STS XML
Use the metanorma-oiml flavor in your document.adoc header:
= Clinical thermometers (mercury-in-glass, with maximum device)
:docidentifier: OIML R 7
:docnumber: 7
:edition: 1979
:revdate: 1979
:copyright-year: 1979
:language: en
:title-main-en: Clinical thermometers (mercury-in-glass, with maximum device)
:doctype: international-recommendation
:docstage: 60
:docsubstage: 60
:mn-document-class: oiml
:mn-output-extensions: xml,html,pdf,rxlSee the OIML X 999:2026 spec (in ~/src/mn/sts-specs/sources/oiml-x-999-2026/)
for the full OIML profile: identifier schemes, document types, languages,
and the three normative constraints every OIML publication shall satisfy.
Run Metanorma against the AsciiDoc source:
bundle exec metanorma path/to/document.adocThis produces several outputs alongside the source:
-
document.xml— the semantic (canonical) Metanorma XML. -
document.presentation.xml— the presentation XML. This is the input tooiml-sts. It carries the rendered labels, table of contents, and resolved cross-references that the STS transformer needs. -
document.html,document.pdf— render outputs (optional for the STS pipeline).
|
Tip
|
If you only need the presentation XML, skip the heavy PDF render by
restricting extensions: :mn-output-extensions: xml in the header.
|
oiml-sts convert path/to/document.presentation.xml path/to/document.sts.xmlAdd --validate to also run the OIML X 999 Clause 6 rules against the
output and exit non-zero on any violation:
oiml-sts convert path/to/document.presentation.xml --validateFor a directory of OIML publications (e.g. the mn-samples-oiml repo):
oiml-sts convert-dir ~/src/mn/mn-samples-oiml/sources ./sts-outputThe converter walks every document.presentation.xml under the input
directory and writes <slug>.sts.xml into the output directory.
oiml-sts validate path/to/document.sts.xmlThe validator applies the rules defined in schematron/oiml-sts.sch
(implemented in pure Ruby for fast startup — no XSLT engine required):
-
oiml-x999-root-element— root shall be<standard>or<adoption>. -
oiml-x999-processing-meta— every<standard>shall declare<processing-meta>. -
oiml-x999-std-title-and-date— every<std>shall carry<title>and<pub-date>. -
oiml-x999-no-self-uri-in-xref—<self-uri>shall not occur inside<self-xref>. -
oiml-x999-permission-on-reuse-disp-quote—<disp-quote>with<attrib>shall carry<permissions>.
require "metanorma/oiml/sts"
presentation_xml = File.read("path/to/document.presentation.xml")
sts_xml = Metanorma::Oiml::Sts.convert(presentation_xml)
File.write("document.sts.xml", sts_xml)
report = Metanorma::Oiml::Sts.validate(sts_xml)
abort(report.to_s) unless report.valid?The mn-samples-oiml repository ships 32 OIML documents whose
presentation XMLs are already generated. To convert all of them to OIML
NISO STS XML and drop the outputs into a sts-output/ directory:
git clone https://github.com/metanorma/mn-samples-oiml ~/src/mn/mn-samples-oiml
cd ~/src/mn/mn-samples-oiml && bundle install && bundle exec metanorma site generate
oiml-sts convert-dir ~/src/mn/mn-samples-oiml/sources ./sts-outputFor every OIML publication the converter:
-
Wraps the output in a
<standard>root with@xml:langand@dtd-version="1.2". -
Emits a
<processing-meta>block declaring the OIML-default modeling choices (STS interchange tag set, XHTML table model, MathML 3.0, TBX terminology model). -
Builds a
<std-meta>block from the source<bibdata>: identifier, title group, publication date, release version, permissions, contributors, and a<custom-meta>recording the OIML document-series letter (R/B/D/G/E/X). OIML uses<std-meta>(the NISO STS generic container) — not<iso-meta>— because OIML is an intergovernmental organisation, not ISO. -
Walks the source
<sections>into<body><sec>(nested), preserving labels, titles, and@idvalues. -
Dispatches per-element transformers for paragraphs, lists, tables, figures, formulae, notes, examples, quotations, and references.
-
Emits annexes inside
<back><app-group><app>and the bibliography as<back><ref-list content-type="bibliography">. -
Ensures every bibliographic
<std>carries both<title>and<pub-date>(per OIML X 999 Clause 6.3).
The transformer mirrors Metanorma::Iso::Sts::Transformer:
-
Metanorma::Oiml::Sts::Transformer::SourceDocument— typed wrapper aroundMetanorma::Oiml::Document::Root(this gem’s document model, built on themetanorma-documentframework). -
Metanorma::Oiml::Sts::Transformer::Context— shared state per conversion. -
Metanorma::Oiml::Sts::Transformer::ModelBuilder— factory methods for constructing sts-ruby typed model instances (Sts::NisoSts::*). -
Per-element transformers under
Metanorma::Oiml::Sts::Transformer::*. -
Metanorma::Oiml::Sts::HtmlRenderer— Liquid-based STS XML → HTML renderer. Parses STS XML viaSts::NisoSts::Standard.from_xml, walks the typed model, and emits a complete branded HTML page through Liquid templates (no Nokogiri, no XSLT engine). Templates and assets (CSS, SVG logos, JS) live underlib/metanorma/oiml/sts/html_renderer/. -
Metanorma::Oiml::Sts::ParityValidator— compares the STS HTML output against metanorma-document’s HTML output at 100% content coverage (headings, paragraphs, table cells, list items, notes, images). -
Metanorma::Oiml::Sts::Validator— applies the Schematron ruleset and reports violations.
The STS HTML renderer produces a standalone, branded HTML page from any OIML NISO STS XML.
oiml-sts convert document.presentation.xml document.sts.xmlThen render the HTML:
require "metanorma/oiml/sts"
sts_xml = File.read("document.sts.xml")
html = Metanorma::Oiml::Sts::HtmlRenderer.render(sts_xml)
File.write("document.sts.html", html)require "metanorma/oiml/document"
require "metanorma/oiml/html"
require "metanorma/oiml/sts"
# Step 1: presentation XML → STS XML
presentation_xml = File.read("document.presentation.xml")
sts_xml = Metanorma::Oiml::Sts.convert(presentation_xml)
# Step 2: STS XML → branded STS HTML
sts_html = Metanorma::Oiml::Sts::HtmlRenderer.render(sts_xml)
File.write("document.sts.html", sts_html)-
Tailwind 4 CSS (via CDN) with OIML-branded theme variables.
-
OIML SMART logos (light + dark variants, toggled with the page theme).
-
Sticky header nav with document title and breadcrumb (section-aware).
-
Interactive table of contents with scroll-spy (auto-highlights the current section; auto-scrolls the TOC panel to keep the active entry visible).
-
Front-matter sections (Copyright, Feedback) as muted cards; Foreword and Introduction as normal sections.
-
Bibliography citations rendered with structured std-ref + title.
-
Term sections with heading-number + preferred-name in the TOC ("3.1 NISO STS").
-
Table cells with monospace preservation, table footnotes routed to
<tfoot>, body footnotes deferred to end-of-document. -
Dark / light / sepia / OLED theme toggle with localStorage persistence.
-
Back-to-top button.
The Schematron ruleset (schematron/oiml-sts.sch) checks every normative
constraint in OIML X 999:2026 Clause 6:
-
<permission>required on reused content. -
<self-uri>forbidden inside<self-xref>. -
<title>and<pub-date>required on every<std>.