Skip to content

About

No description, website, or topics provided.

Resources

Contributing

Stars

0 stars

Watchers

7 watching

Forks

Repository files navigation

metanorma-oiml

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.

Installation

gem install metanorma-oiml

Or, in a Gemfile:

gem "metanorma-oiml"

CLI

Caution

The oiml-sts CLI is deprecated. OIML STS output is now produced through the Metanorma pipeline as a taste output format (see metanorma-core#12):

metanorma compile -t oiml -x oimlsts document.adoc   # => document.oiml.sts.xml

oiml-sts is retained for one release cycle, then removed. The reusable library API (Metanorma::Oiml::Sts.convert / .validate) is unaffected.

oiml-sts convert <input.presentation.xml> [output.sts.xml]
oiml-sts convert-dir <input-dir> <output-dir>
oiml-sts validate <sts.xml>

Native Ruby API

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 }

Creating OIML STS from MN-OIML XML output

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

Step 1 — Author the OIML publication in Metanorma AsciiDoc

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

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

Step 2 — Compile to presentation XML

Run Metanorma against the AsciiDoc source:

bundle exec metanorma path/to/document.adoc

This produces several outputs alongside the source:

  • document.xml — the semantic (canonical) Metanorma XML.

  • document.presentation.xml — the presentation XML. This is the input to oiml-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.

Step 3 — Convert presentation XML to OIML STS XML

oiml-sts convert path/to/document.presentation.xml path/to/document.sts.xml

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

For a directory of OIML publications (e.g. the mn-samples-oiml repo):

oiml-sts convert-dir ~/src/mn/mn-samples-oiml/sources ./sts-output

The converter walks every document.presentation.xml under the input directory and writes <slug>.sts.xml into the output directory.

Step 4 — (Optional) Validate standalone

oiml-sts validate path/to/document.sts.xml

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

Step 5 — (Optional) Drive the conversion from Ruby

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?

End-to-end example

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

What the converter does

For every OIML publication the converter:

  1. Wraps the output in a <standard> root with @xml:lang and @dtd-version="1.2".

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

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

  4. Walks the source <sections> into <body><sec> (nested), preserving labels, titles, and @id values.

  5. Dispatches per-element transformers for paragraphs, lists, tables, figures, formulae, notes, examples, quotations, and references.

  6. Emits annexes inside <back><app-group><app> and the bibliography as <back><ref-list content-type="bibliography">.

  7. Ensures every bibliographic <std> carries both <title> and <pub-date> (per OIML X 999 Clause 6.3).

Architecture

The transformer mirrors Metanorma::Iso::Sts::Transformer:

  • Metanorma::Oiml::Sts::Transformer::SourceDocument — typed wrapper around Metanorma::Oiml::Document::Root (this gem’s document model, built on the metanorma-document framework).

  • 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 via Sts::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 under lib/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.

Rendering STS HTML

The STS HTML renderer produces a standalone, branded HTML page from any OIML NISO STS XML.

CLI

oiml-sts convert document.presentation.xml document.sts.xml

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

From Metanorma presentation XML (one-shot)

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)

Renderer features

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

Validation rules

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

License

MIT — see LICENSE.

About

No description, website, or topics provided.

Resources

Contributing

Stars

0 stars

Watchers

7 watching

Forks

Releases

Packages

Used by

Contributors

Languages